org.netbeans.api.db.explorer

Class DatabaseConnection

java.lang.Object

org.netbeans.api.db.explorer.DatabaseConnection

public final class DatabaseConnection
extends Object

Encapsulates a database connection. Each DatabaseConnection instance represents a connection to a database in the Database Explorer.

This class provides access to the properties of a database connection, such as the connection name, database URL, user or default schema. New connections can be created using the DatabaseConnection.create(org.netbeans.api.db.explorer.JDBCDriver, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method (these connections can be added to the Database Explorer using the ConnectionManager.addConnection(org.netbeans.api.db.explorer.DatabaseConnection) method.

It is also possible to retrieve the JDBC Connection using the DatabaseConnection.getJDBCConnection() method (the connection can be connected or disconnected using the ConnectionManager.showConnectionDialog(org.netbeans.api.db.explorer.DatabaseConnection) and ConnectionManager.disconnect(org.netbeans.api.db.explorer.DatabaseConnection) methods.

See Also:

ConnectionManager

Method Summary

Modifier and Type	Method and Description
static DatabaseConnection	create(JDBCDriver driver, String databaseURL, String user, String schema, String password, boolean rememberPassword) Creates a new DatabaseConnection instance w/ a default display name based on connection URL and user
static DatabaseConnection	create(JDBCDriver driver, String databaseURL, String user, String schema, String password, boolean rememberPassword, String displayName) Creates a new DatabaseConnection instance.
static DatabaseConnection	create(JDBCDriver driver, String databaseURL, String user, String schema, String password, boolean rememberPassword, String displayName, Properties connectionProperties) Creates a new DatabaseConnection instance.
Properties	getConnectionProperties() Returns additional connection properties for the connection.
String	getDatabaseURL() Returns this connection's database URL.
String	getDisplayName() Returns the name used to display this connection in the UI.
String	getDriverClass() Returns the JDBC driver class that this connection uses.
Connection	getJDBCConnection() Returns the Connection instance which encapsulates the physical connection to the database if this database connection is connected.
Connection	getJDBCConnection(boolean test) Returns the Connection instance which encapsulates the physical connection to the database if this database connection is connected.
JDBCDriver	getJDBCDriver() Returns the JDBC driver instance that this connection uses.
String	getName() Returns the programmatic name of this connection in the Database Explorer.
String	getPassword() Returns the password used to connect to the database.
String	getSchema() Returns this connection's default schema.
String	getUser() Returns the user name used to connect to the database.
boolean	isUseScrollableCursors() Check whether usage of scrollable cursors is recommended for this connection.
void	setUseScrollableCursors(boolean useScrollableCursors) Set whether usage of scrollable cursors is recommended for this connection.
String	toString() Returns a string representation of the database connection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

create

public static DatabaseConnection create(JDBCDriver driver,
                                        String databaseURL,
                                        String user,
                                        String schema,
                                        String password,
                                        boolean rememberPassword)

Creates a new DatabaseConnection instance w/ a default display name based on connection URL and user

Parameters:

driver - the JDBC driver the new connection uses; cannot be null.

databaseURL - the URL of the database to connect to; cannot be null.

user - the username.

schema - the schema to use, or null for the default schema

password - the password.

rememberPassword - whether to remember the password for the current session.

Returns:

the new instance.

Throws:

NullPointerException - if driver or database are null.

create

public static DatabaseConnection create(JDBCDriver driver,
                                        String databaseURL,
                                        String user,
                                        String schema,
                                        String password,
                                        boolean rememberPassword,
                                        String displayName)

Creates a new DatabaseConnection instance.

Parameters:

driver - the JDBC driver the new connection uses; cannot be null.

databaseURL - the URL of the database to connect to; cannot be null.

user - the username.

schema - the schema to use, or null for the default schema

password - the password.

rememberPassword - whether to remember the password for the current session.

displayName - the display name of the connection as it shows under the Databases node

Returns:

the new instance.

Throws:

NullPointerException - if driver or database are null.

Since:

1.42

create

public static DatabaseConnection create(JDBCDriver driver,
                                        String databaseURL,
                                        String user,
                                        String schema,
                                        String password,
                                        boolean rememberPassword,
                                        String displayName,
                                        Properties connectionProperties)

Creates a new DatabaseConnection instance.

Parameters:

driver - the JDBC driver the new connection uses; cannot be null.

databaseURL - the URL of the database to connect to; cannot be null.

user - the username.

schema - the schema to use, or null for the default schema

password - the password.

rememberPassword - whether to remember the password for the current session.

displayName - the display name of the connection as it shows under the Databases node

connectionProperties - Additional connection properties, see DatabaseConnection.getConnectionProperties().

Returns:

the new instance.

Throws:

NullPointerException - if driver or database are null.

Since:

1.53

getDriverClass

public String getDriverClass()

Returns the JDBC driver class that this connection uses.

Returns:

the JDBC driver class

getJDBCDriver

public JDBCDriver getJDBCDriver()

Returns the JDBC driver instance that this connection uses.

Returns:

the JDBC driver or null if no driver registered

Since:

1.32

getDatabaseURL

public String getDatabaseURL()

Returns this connection's database URL.

Returns:

the connection's database URL

getSchema

public String getSchema()

Returns this connection's default schema.

Returns:

the schema

getUser

public String getUser()

Returns the user name used to connect to the database.

Returns:

the user name

getPassword

public String getPassword()

Returns the password used to connect to the database.

Returns:

the password

getName

public String getName()

Returns the programmatic name of this connection in the Database Explorer.

Returns:

the programmatic name

getDisplayName

public String getDisplayName()

Returns the name used to display this connection in the UI.

Returns:

the display name

getConnectionProperties

public Properties getConnectionProperties()

Returns additional connection properties for the connection.

The properties can be set by the user and may be used e.g. in Driver.connect(String, Properties). Note that properties "user" and "password" are not included in this object, use DatabaseConnection.getUser() and DatabaseConnection.getPassword(). Additional properties are usually needed to configure some database-specific connection options (e.g. charset).

Changes made to returned object will have no effect (copy of internal properties is returned).

Returns:

the connection properties (maybe null)

Since:

db/1.53

isUseScrollableCursors

public boolean isUseScrollableCursors()

Check whether usage of scrollable cursors is recommended for this connection.

Returns:

True if scrollable cursors can be used, false if scrollable cursors are not supported by driver or database of this connection.

Since:

db/1.57

setUseScrollableCursors

public void setUseScrollableCursors(boolean useScrollableCursors)

Set whether usage of scrollable cursors is recommended for this connection.

Parameters:

useScrollableCursors - True if this connection is allowed to use scrollable cursors, false otherwise (older JDBC methods will be used instead.).

Since:

db/1.57

getJDBCConnection

public Connection getJDBCConnection()

Returns the Connection instance which encapsulates the physical connection to the database if this database connection is connected. Note that "connected" here means "connected using the Database Explorer". There is no check if Connection.close() has been called on the returned connection. However, clients should not call Connection.close() on the returned connection, therefore this method should always return a non-closed connection or null.

Calling Connection.close() on the connection returned by this method is illegal. Use ConnectionManager.disconnect(org.netbeans.api.db.explorer.DatabaseConnection) to close the connection.

Returns:

the physical connection or null if not connected.

Throws:

IllegalStateException - if this connection is not added to the ConnectionManager.

getJDBCConnection

public Connection getJDBCConnection(boolean test)

Returns the Connection instance which encapsulates the physical connection to the database if this database connection is connected. Note that "connected" here means "connected using the Database Explorer". Unless testtrue, there is no check if Connection.close() has been called on the returned connection. However, clients should not call Connection.close() on the returned connection, therefore this method should always return a non-closed connection or null.

Calling Connection.close() on the connection returned by this method is illegal. Use ConnectionManager.disconnect(org.netbeans.api.db.explorer.DatabaseConnection) to close the connection.

Parameters:

test - Set this to true if you want the Database Explorer to validate the JDBC connection before returning it. If the JDBC connection is invalid, the DatabaseConnection is marked as disconnected and null is returned.

NOTE that setting this to true can have a performance impact because it requires sending a command to the database server. Also, this method should not be called on the AWT event thread if you set test to true.

Returns:

the physical connection or null if not connected.

Throws:

IllegalStateException - if this connection is not added to the ConnectionManager, or if test is set to true and this method is called on the AWT event thread.

Since:

1.30

toString

public String toString()

Returns a string representation of the database connection.

Overrides:

toString in class Object