Where Am I? Class Hierarchy All Classes All Fields and Methods

Class com.ibm.db.DatabaseConnection

java.lang.Object
   |
   +----com.ibm.db.DatabaseConnection

public class DatabaseConnection
implements Serializable
extends Object

DatabaseConnection represents a connection to the database.

See Also:
Statement

Field Index

POOL_TYPE_NONE
No connection pools
POOL_TYPE_WEBSPHERE
Use WebSphere connection pools

Constructor Index

DatabaseConnection()
Constructs a new DatabaseConnection.
DatabaseConnection(Connection)
Constructs a new DatabaseConnection with the specified JDBC connection.

Method Index

addDatabaseConnectionAfterListener(DatabaseConnectionAfterListener)
Adds a listener to the DatabaseConnectionAfter event set.
addDatabaseConnectionBeforeListener(DatabaseConnectionBeforeListener)
Adds a listener to the DatabaseConnectionBefore event set.
commit()
Commits changes to the database.
connect()
Attempts to establish a connection to the database.
disconnect()
Closes the JDBC connection for further use by this DatabaseConnection object.
getAutoCommit()
Returns true if changes to the database are automatically committed as soon as they are made.
getConnectionAlias()
Returns the alias name that is associated with this DatabaseConnection.
getConnectionPoolType()
Returns the connection pool type.
getDataSourceName()
Returns the URL used when establishing a connection to the database.
getDriverName()
Returns the JDBC driver used when establishing a connection to the database.
getJDBCMetaData()
Returns the java.sql.DatabaseMetaData associated with this DatabaseConnection.
getPromptUID()
Returns true if before a database connection is made, a logon dialog will be displayed to obtain the userid and password for the connection.
getProperties()
Returns the properties for this DatabaseConnection.
getUserID()
Returns the userid used when establishing a connection to the database.
isConnected()
Returns true if the DatabaseConnection is associated with an active JDBC connection.
isExternallyManaged()
Returns true if the associated JDBC connection is considered to be externally managed.
removeDatabaseConnectionAfterListener(DatabaseConnectionAfterListener)
Removes a listener to the DatabaseConnectionAfter event set.
removeDatabaseConnectionBeforeListener(DatabaseConnectionBeforeListener)
Removes a listener to the DatabaseConnectionBefore event set.
rollback()
Rollback changes in the database.
setAutoCommit(boolean)
If true, any changes to the database are automatically committed as soon as they are made.
setConnectionAlias(String)
Sets the connection alias name used when a connect is invoked on this DatabaseConnection.
setConnectionPoolType(int)
Sets the connection pool type for this DatabaseConnection.
setDataSourceName(String)
Sets the URL used when establishing a connection to the database.
setDriverName(String)
Sets the JDBC driver used when establishing a connection to the database.
setPassword(String)
Sets the password used when establishing a connection to the database.
setPassword(String, boolean)
Decodes the specified password if requested, and sets the password used when establishing a connection to the database.
setPromptUID(boolean)
If true, before a database connection is made, a logon dialog will be displayed to obtain the userid and password for the connection.
setProperties(Properties)
Sets the properties to use when establishing a connection.
setUserID(String)
Sets the userid used when establishing a connection to the database.

Fields

POOL_TYPE_NONE
 public static final int POOL_TYPE_NONE
No connection pools

POOL_TYPE_WEBSPHERE
 public static final int POOL_TYPE_WEBSPHERE
Use WebSphere connection pools


Constructors

DatabaseConnection
 public DatabaseConnection() 
Constructs a new DatabaseConnection.

DatabaseConnection
 public DatabaseConnection(Connection jdbcConnection) throws DataException
Constructs a new DatabaseConnection with the specified JDBC connection. Use this constructor when you already have an open java.sql.Connection that you want to use in a new DatabaseConnection. When you use this constructor, the connection is considered to be externally managed. You cannot issue the connect method against an externally managed DatabaseConnection. When you issue the disconnect method against an externally managed DatabaseConnection, the JDBC connection remains open, but is closed for use by this DatabaseConnection object.

Parameters:
jdbcConnection - open java.sql.Connection
Throws: DataException
connectionClosed - if the jdbcConnection is closed
Throws: DataException
sqlException - if an SQL exception occurred
See Also:
isExternallyManaged

Methods

addDatabaseConnectionAfterListener
 public void addDatabaseConnectionAfterListener(DatabaseConnectionAfterListener listener) 
Adds a listener to the DatabaseConnectionAfter event set. DatabaseConnectionAfter events occur after connection-scoped actions have completed, such as connect, disconnect, commit, or rollback.

Parameters:
listener - DatabaseConnectionAfterListener
See Also:
DatabaseConnectionAfterListener
removeDatabaseConnectionAfterListener
addDatabaseConnectionBeforeListener
 public void addDatabaseConnectionBeforeListener(DatabaseConnectionBeforeListener listener) 
Adds a listener to the DatabaseConnectionBefore event set. DatabaseConnectionBefore events occur before connection-scoped actions are performed, such as connect, disconnect, commit, or rollback.

Parameters:
listener - DatabaseConnectionBeforeListener
See Also:
DatabaseConnectionBeforeListener
removeDatabaseConnectionBeforeListener
commit
 public synchronized void commit() throws DataException
Commits changes to the database. All outstanding changes made to the database using this connection are committed to the database and any database locks currently held by the connection are released. This method should only be used when auto commit has been turned off.

The events aboutToCommit and committed are triggered by this method.

Throws: DataException
noActiveConnection - if no active connection exists
Throws: DataException
sqlException - if an SQL exception occurs
See Also:
setAutoCommit
rollback
connect
 public synchronized boolean connect() throws DataException
Attempts to establish a connection to the database. The URL used for the connection is obtained from the previously specified DataSourceName. The JDBC driver specified by DriverName is registered prior to attempting to make the connection.

If a connection already exists for the specified connectionAlias, no new connection is made and the existing connection is shared. If the value of connectionAlias is null, a new connection is always established.

If the connectionPoolType property is POOL_TYPE_WEBSPHERE, the connection is obtained from the WebSphere connection pools. If no connection pool currently exists, a new connection pool with default settings is created based on the specified URL. Then the connection is obtained from the new pool.

If the connectionPoolType property is POOL_TYPE_NONE, a new connection is obtained directly from the JDBC DriverManager.

The events aboutToConnect and connected are triggered by this method.

Returns:
true if the connection was successfully establish, else false.
Throws: DataException
externallyManaged - if connection is externally managed
Throws: DataException
alreadyConnected - if connection is already established
Throws: DataException
noGui - if no GUI available and logon prompt requested
Throws: DataException
badUidPwd - if incorrect Userid or password specified
Throws: DataException
noTransactions - if database does not support transactions and autoCommit set to false
Throws: DataException
sqlException - if an SQLException occurred
Throws: DataException
websphereConnectionError - if an error occurred obtaining the connection from WebSphere
See Also:
disconnect
setConnectionPoolType
disconnect
 public synchronized void disconnect() throws DataException
Closes the JDBC connection for further use by this DatabaseConnection object. A disconnect may or may not be performed on the JDBC connection itself depending on whether the JDBC connection was obtained from a WebSphere connection pool, whether it is externally managed, and if neither of the former applies, whether it is being shared by another DatabaseConnection object using the same connection alias.

If the connection is externally managed or is being shared by another DatabaseConnection object, the association between the JDBC connection and the DatabaseConnection object is removed, but the JDBC connection itself is not closed.

If the connection was obtained from a Webshpere connection pool and is not externally managed, the JDBC connection is simply released back to the connection pool.

If the connection is not externally managed, is not from a Webshpere connection pool, and is not being shared with another DatabaseConnection object, the JDBC connection is closed, releasing the JDBC resources associated with the connection.

The events aboutToDisconnect and disconnected are triggered by this method.

Throws: DataException
noActiveConnection - if no active Connection
Throws: DataException
notRegistered - if connection alias not registered as in use
Throws: DataException
sqlException - if an SQLException occurred
Throws: DataException
websphereConnectionError - if an error occurred releasing the connection to WebSphere
See Also:
connect
setConnectionPoolType
getAutoCommit
 public boolean getAutoCommit() 
Returns true if changes to the database are automatically committed as soon as they are made.

Returns:
true if the changes are automatically committed, else false.
See Also:
setAutoCommit
getConnectionAlias
 public String getConnectionAlias() 
Returns the alias name that is associated with this DatabaseConnection.

Returns:
the alias name
See Also:
setConnectionAlias
getConnectionPoolType
 public int getConnectionPoolType() 
Returns the connection pool type.

Returns:
the connection pool type - POOL_TYPE_NONE indicates no connections pools are used. POOL_TYPE_WEBSPHERE indicates WebSphere connection pools are used.
See Also:
setConnectionPoolType
getDataSourceName
 public String getDataSourceName() 
Returns the URL used when establishing a connection to the database.

Returns:
the URL for the connection
See Also:
setDataSourceName
getDriverName
 public String getDriverName() 
Returns the JDBC driver used when establishing a connection to the database.

Returns:
the JDBC driver name for the connection
See Also:
setDriverName
getJDBCMetaData
 public DatabaseMetaData getJDBCMetaData() throws DataException
Returns the java.sql.DatabaseMetaData associated with this DatabaseConnection. Returns null if there is no active connection.

Returns:
the associated DatabaseMetaData if there is an active connection; otherwise returns null.
Throws: DataException
sqlException - if an SQL exception occurs
getPromptUID
 public boolean getPromptUID() 
Returns true if before a database connection is made, a logon dialog will be displayed to obtain the userid and password for the connection.

Returns:
true if logon dialog will be displayed, else false
See Also:
setPromptUID
getProperties
 public Properties getProperties() 
Returns the properties for this DatabaseConnection. Properties specify keyword/value pairs other than userid and password required for connecting to the database. Userid and password can be set separately.

Returns:
the properties for the connection.
See Also:
setProperties
setUserID
setPassword
getUserID
 public String getUserID() 
Returns the userid used when establishing a connection to the database.

Returns:
the userid for the connection
See Also:
setUserID
isConnected
 public boolean isConnected() throws DataException
Returns true if the DatabaseConnection is associated with an active JDBC connection. Otherwise returns false.

Returns:
true if associated with an active JDBC connection, else false.
Throws: DataException
sqlException - if an SQL exception occurs
isExternallyManaged
 public boolean isExternallyManaged() 
Returns true if the associated JDBC connection is considered to be externally managed. A connect is not allowed for an externally managed connection. When you issue the disconnect method for an externally managed connection, the JDBC connection remains open, but is closed for use by this DatabaseConnection object.

Returns:
true if the connection is externally managed, else false.
removeDatabaseConnectionAfterListener
 public void removeDatabaseConnectionAfterListener(DatabaseConnectionAfterListener listener) 
Removes a listener to the DatabaseConnectionAfter event set. DatabaseConnectionAfter events occur after connection-scoped actions have completed, such as connect, disconnect, commit, or rollback.

Parameters:
listener - DatabaseConnectionAfterListener
See Also:
DatabaseConnectionAfterListener
addDatabaseConnectionAfterListener
removeDatabaseConnectionBeforeListener
 public void removeDatabaseConnectionBeforeListener(DatabaseConnectionBeforeListener listener) 
Removes a listener to the DatabaseConnectionBefore event set. DatabaseConnectionBefore events occur before connection-scoped actions are performed, such as connect, disconnect, commit, or rollback.

Parameters:
listener - DatabaseConnectionBeforeListener
See Also:
DatabaseConnectionBeforeListener
addDatabaseConnectionBeforeListener
rollback
 public synchronized void rollback() throws DataException
Rollback changes in the database. All changes made since the previous commit/rollback are rolled back and any database locks currently held by the connection are released. This method should only be used when auto commit has been turned off.

The events aboutToRollback and rolledBack are triggered by this method.

Throws: DataException
noActiveConnection - if no active connection exists
Throws: DataException
sqlException - if an SQL exception occurs
See Also:
commit
setAutoCommit
setAutoCommit
 public synchronized void setAutoCommit(boolean autoCommit) throws DataException
If true, any changes to the database are automatically committed as soon as they are made. Otherwise changes are not committed until commit is issued.

The default value of this property is true.

Parameters:
autoCommit - true - automatically commit changes; false - don't automatically commit changes
Throws: DataException
sqlException - if an SQL exception occurs
Throws: DataException
noTransactions - if database does not support transactions and autoCommit set to false
See Also:
getAutoCommit
setConnectionAlias
 public void setConnectionAlias(String alias) 
Sets the connection alias name used when a connect is invoked on this DatabaseConnection. If a connection to the database has already been established for this alias name, no new connection is made and the existing connection is shared.

Parameters:
alias - the alias name for the connection
See Also:
getConnectionAlias
setConnectionPoolType
 public void setConnectionPoolType(int aConnectionPoolType) throws DataException
Sets the connection pool type for this DatabaseConnection. If the connectionPoolType property is POOL_TYPE_WEBSPHERE, when you invoke the connect method the connection is obtained from the WebSphere connection pools. If no connection pool currently exists, a new connection pool with default settings is created based on the specified URL, and the connection is obtained from the new pool.

If the connectionPoolType property is POOL_TYPE_NONE, a new connection is obtained directly from the JDBC DriverManager.

Parameters:
aConnectionPoolType - POOL_TYPE_NONE indicates no connections pools are used. POOL_TYPE_WEBSPHERE indicates WebSphere connection pools are used.
Throws: DataException
invalidConnPoolType - if an invalid connection pool type was specified
See Also:
getConnectionPoolType
setDataSourceName
 public void setDataSourceName(String dataSourceName) 
Sets the URL used when establishing a connection to the database. A URL specification has the format jdbc:subprotocol:subname, where subprotocol and subname identify the data source for the connection. The value of subprotocol depends on the JDBC driver used. For example, for the DB2 application JDBC driver, subprotocol is db2; for the Oracle thin driver, subprotocol is thin. The value of subname depends on the subprotocol specification; the subname value provides information to locate the database. For example, a full URL specification for an application accessing a local database named sample through the DB2 application JDBC driver is: jdbc:db2:sample. By comparison, a full URL specification for an applet using the Sybase jConnect driver to access a database named sample, on a remote server named myserv, through port number 88 on the internet is: jdbc:sybase:Tds:myserver:88/sample. Here, the subname value includes the database server name, port number, and database name.

Parameters:
dataSourceName - The URL for the connection.
See Also:
getDataSourceName
setDriverName
 public void setDriverName(String driverName) 
Sets the JDBC driver used when establishing a connection to the database. This is the class name of the JDBC driver (including the package name). For example, the DB2 application JDBC driver is COM.ibm.db2.jdbc.appDB2Driver.

Parameters:
driverName - the JDBC driver name for the connection
See Also:
getDriverName
setPassword
 public void setPassword(String password) 
Sets the password used when establishing a connection to the database.

Parameters:
password - the password for the connection
See Also:
setPromptUID
setPassword
 public void setPassword(String password,
                         boolean decode) throws DataException
Decodes the specified password if requested, and sets the password used when establishing a connection to the database.

This method is provided for use by VisualAge for Java in its generated code. Because the encoding/decoding algorithm is proprietary, you should use the method with signature setPassword(String) in code that you write yourself.

Parameters:
password - the password for the connection
decode - true - decode password; false - password is not encoded.
Throws: DataException
decodeError - if error encountered while decoding password
See Also:
setPromptUID
setPromptUID
 public void setPromptUID(boolean promptUID) 
If true, before a database connection is made, a logon dialog will be displayed to obtain the userid and password for the connection. The userid and password entered in the dialog will override any userid or password that had been previously specified.

The default value of this property is false.

Parameters:
promptUID - true -display logon dialog; false - don't display logon dialog
See Also:
getPromptUID
setProperties
 public void setProperties(Properties properties) 
Sets the properties to use when establishing a connection. Use properties to specify keyword/value pairs other than userid and password required for connecting to the database. Userid and password can be set separately.

Parameters:
properties - the properties for the connection
See Also:
getProperties
setPassword
setUserID
setUserID
 public void setUserID(String userid) 
Sets the userid used when establishing a connection to the database.

Parameters:
userid - the userid for the connection
See Also:
getUserID
setPromptUID

Where Am I? Class Hierarchy All Classes All Fields and Methods