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
extends Object
implements Serializable

DatabaseConnection represents a connection to the database.

Version:
1.0 06/30/98
See Also:
Statement

Constructor Index

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

Method Index

addDatabaseConnectionAfterListener(DatabaseConnectionAfterListener)
Adds the DatabaseConnectionAfterListener.
addDatabaseConnectionBeforeListener(DatabaseConnectionBeforeListener)
Adds the DatabaseConnectionBeforeListener.
commit()
Commits changes to the database.
connect()
Attempts to establish a connection to the database.
disconnect()
If no other DatabaseConnection is currently sharing the connection represented by the connectionAlias, disconnects from the database and releases JDBC resources associated with the connection.
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.
getConnectionSpec()
Returns the DatabaseConnectionSpec associated with this DatabaseConnection.
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.
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.
isExternallyManaged()
Returns true if the associated JDBC connection is considered to be externally managed.
removeDatabaseConnectionAfterListener(DatabaseConnectionAfterListener)
Removes the DatabaseConnectionAfterListener.
removeDatabaseConnectionBeforeListener(DatabaseConnectionBeforeListener)
Removes the DatabaseConnectionBeforeListener.
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.
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.

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 associated with a new DatabaseConnection. When you use this constructor, the connection is considered to be externally managed. You cannot issue the connect or disconnect methods against an externally managed DatabaseConnection.

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

Methods

addDatabaseConnectionAfterListener
 public void addDatabaseConnectionAfterListener(DatabaseConnectionAfterListener newListener)
Adds the DatabaseConnectionAfterListener. DatabaseConnectionAfter events occur after connection scoped actions have completed, such as connect, disconnect, commit, or rollback.

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

Parameters:
newListener - 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 disabled.

The events aboutToCommit and committed are triggered by this method.

Throws: DataException
noActiveConnection - if no active connection exists
Throws: DataException
sqlException - if a 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 previoiusly 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 conneciton is shared. If the value of connectionAlias is null>, a new connection is always established.

The events aboutToConnect and connected are triggered by this method.

Throws: DataException
externallyManaged - if connection is externally managed
Throws: DataException
noGui - if no GUI available and logon prompt requested
Throws: DataException
badUidPwd - if incorrect Userid or password specified
Throws: DataException
sqlException - if SQLException occurred
See Also:
disconnect
disconnect
 public synchronized void disconnect() throws DataException
If no other DatabaseConnection is currently sharing the connection represented by the connectionAlias, disconnects from the database and releases JDBC resources associated with the connection. If the connection is being shared, the use count is decremeted by 1.

The events aboutToDisconnect and disconnected are triggered by this method.

Throws: DataException
externallyManaged - if connection is externally managed
Throws: DataException
noActiveConnection - if no active Connection
Throws: DataException
sqlException - if SQLException occurred
See Also:
connect
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
getConnectionSpec
 public DatabaseConnectionSpec getConnectionSpec()
Returns the DatabaseConnectionSpec associated with this DatabaseConnection. The connectionSpec contains all of the information needed to establish a connection with the database.

Returns:
the associated DatabaseConnectionSpec
See Also:
setConnectionSpec, DatabaseConnectionSpec
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
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.

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

Returns:
the userid for the connection
See Also:
setUserID
isExternallyManaged
 public boolean isExternallyManaged()
Returns true if the associated JDBC connection is considered to be externally managed. A connect or disconnect is not allowed for an externally managed connection.

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

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

Parameters:
newListener - 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 disabled.

The events aboutToRollback and rolledBack are triggered by this method.

Throws: DataException
noActiveConnection - if no active connection exists
Throws: DataException
sqlException - if a 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 a SQL exception occurs
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
setDataSourceName
 public void setDataSourceName(String dataSourceName)
Sets the URL used when establishing a connection to the database. The URL contains the database type and the name of the database.

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.

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
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.

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
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.

Parameters:
properties - the properties for the connection
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

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