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
