| java.lang.Object
 com.uwyn.rife.database.DbConnection
| DbConnection | | public class DbConnection (Code) | | Represents one connection to a database. A connection has to be obtained by
using the getConnection method on a Datasource
instance. The resulting DbConnection instance can be used to
obtain statement objects from and to manage transactions.
Statements are used to execute SQL queries either in a static or in a
prepared fashion. This corresponds to the DbStatement and
DbPreparedStatement classes. Look there for details about how
to use them. A DbConnection keeps track of which statements
have been openened and will automatically close them when database access
errors occur or when the connection itself is closed.
Several statements can be executed as a whole through the use of
transactions. Only if they all succeeded, the transaction should be
committed and all the modifications will be preserved. Otherwise, the
transaction should be rolled back, and the modifications will not be
integrated into the general data storage. When a transaction has been
started through the beginTransaction() method, it will be
bound to the currently executing thread. Other threads will not be able to
manipulate the transaction status and if they obtain and execute
statements, they will be put in a wait state and woken up again after the
transaction has finished.
author:
Geert Bevin (gbevin[remove] at uwyn dot com)
version:
$Revision: 3634 $
See Also: com.uwyn.rife.database.Datasource.getConnection
See Also: com.uwyn.rife.database.DbStatement
See Also: com.uwyn.rife.database.DbPreparedStatement
since:
1.0 |
| Constructor Summary | |
| | DbConnection(Connection connection, Datasource datasource)
Creates a new DbConnection instance and binds it to a
Datasource and a regular JDBC Connection. |
| Method Summary | |
| public boolean | beginTransaction()
Warning: only use the raw transaction methods if
you really know what you're doing. | | void | cleanup()
Cleans up all the resources that are used by this
DbConnection instance. | | public Object | clone()
Simply clones the instance with the default clone method. | | public void | close()
Releases all the resources that are being used by this connection. | | public boolean | commit()
Warning: only use the raw transaction methods if
you really know what you're doing. | | public DbStatement | createStatement()
Creates a new DbStatement instance for this connection. | | public DbStatement | createStatement(int resultSetType, int resultSetConcurrency)
Creates a new DbStatement instance for this connection with
the given type and concurrency. | | public DbStatement | createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)
Creates a new DbStatement instance for this connection with
the given type, concurrency, and holdability.. | | void | detectCleanup()
This method is used to check if this DbConnection instance
has been cleaned up before using the underlying JDBC connection. | | protected void | finalize()
Ensures that this DbConnection is correctly cleaned-up
when it's garbage collected. | | public Datasource | getDatasource()
Retrieves the datasource this connection has been obtained from. | | public DatabaseMetaData | getMetaData()
Retrieves a DatabaseMetaData object that contains metadata
about the database to which this DbConnection object
represents a connection. | | public DbPreparedStatement | getPreparedStatement(String sql)
Creates a new DbPreparedStatement instance for this
connection from a regular SQL query string. | | public DbPreparedStatement | getPreparedStatement(String sql, int autoGeneratedKeys)
Creates a new DbPreparedStatement instance for this
connection from a Query instance that has the capability
to retrieve auto-generated keys. | | public DbPreparedStatement | getPreparedStatement(Query query)
Creates a new DbPreparedStatement instance for this
connection from a Query instance. | | public DbPreparedStatement | getPreparedStatement(Query query, int autoGeneratedKeys)
Creates a new DbPreparedStatement instance for this
connection from a Query instance that has the capability
to retrieve auto-generated keys. | | public DbPreparedStatement | getPreparedStatement(Query query, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
Creates a new DbPreparedStatement instance for this
connection from a Query instance that will generate
ResultSet objects with the given type, concurrency,
and holdability.
This method is the same as the getPreparedStatement method
above, but it allows the default result set
type, concurrency, and holdability to be overridden.
Thanks to the additional meta-data that's stored in a
Query object, it's possible to use the additional features
that the DbPreparedStatement provides on top of regular
JDBC methods.
The new statement will be registered and automatically closed when
this DbConnection cleans up. | | void | handleException()
Performs the cleanup logic in case an exception is thrown during
execution. | | boolean | isCleanedUp()
Indicates whether this DbConnection instance has been
cleaned up or not. | | public boolean | isClosed()
Indicates whether this DbConnection's connection to the
database is closed.
If an exception is thrown, this DbConnection is
automatically cleaned up. | | public boolean | isFree()
Indicates whether this DbConnection is free to execute
statements for the current thread. | | public boolean | isTransactionValidForThread()
Indicates whether the current thread has a valid transaction going on
for the execution of statements. | | void | releaseStatement(DbStatement statement)
Removes a DbStatement instance from the collection of
managed statements. | | public boolean | rollback()
Warning: only use the raw transaction methods if
you really know what you're doing. | | public void | setTransactionIsolation(int level)
Attempts to change the transaction isolation level for this
DbConnection object to the one given. | | public boolean | supportsTransactions()
Indicates whether the Datasource of this
DbConnection supports transactions or not.
This information is only retrieved once and cached for the rest of
the lifetime of this connection.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. |
| DbConnection | | DbConnection(Connection connection, Datasource datasource)(Code) | | Creates a new DbConnection instance and binds it to a
Datasource and a regular JDBC Connection.
Parameters:
connection - the JDBC Connection that will be used
Parameters:
datasource - the Datasource this connection beenobtained from
since:
1.0 |
| cleanup | | void cleanup() throws DatabaseException(Code) | | Cleans up all the resources that are used by this
DbConnection instance. This is mainly used to correctly
clean up in case of errors during execution.
exception:
DatabaseException - if an error occurred during the closing ofan ongoing transaction, or if an error occurred during the closing ofthe opened statements,
since:
1.0 |
| clone | | public Object clone()(Code) | | Simply clones the instance with the default clone method. This creates
a shallow copy of all fields and the clone will in fact just be another
reference to the same underlying data. The independence of each cloned
instance is consciously not respected since they rely on resources that
can't be cloned.
since:
1.0 |
| close | | public void close() throws DatabaseException(Code) | | Releases all the resources that are being used by this connection. If
the connection has been obtained from a pooled datasource, it will not
be closed, but reused later. If the datasource isn't pooled, the
connection itself will be closed as expected.
Any ongoing transactions will be automatically rolled-back.
All open statements will be closed and if a transaction is active,
it will be automatically rolled back and unregistered.
exception:
DatabaseException - if a database access error occurs, or ifan error occurred during the closing of an ongoing transaction, or ifan error occurred during the closing of the opened statements, or if anerror occurred during the closing of the underlying JDBC connection.
since:
1.0 |
| createStatement | | public DbStatement createStatement() throws DatabaseException(Code) | | Creates a new DbStatement instance for this connection. It
will be registered and automatically closed when this
DbConnection cleans up. It is recommended though to
manually close the statement when it's not needed anymore for sensible
resource preservation.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
a new DbStatement instance
exception:
DatabaseException - when an exception has occurred during thecreation of the DbStatement instance
See Also: com.uwyn.rife.database.DbStatement
See Also: DbConnection.getPreparedStatement(String)
See Also: DbConnection.getPreparedStatement(Query)
since:
1.0 |
| createStatement | | public DbStatement createStatement(int resultSetType, int resultSetConcurrency) throws DatabaseException(Code) | | Creates a new DbStatement instance for this connection with
the given type and concurrency. It
will be registered and automatically closed when this
DbConnection cleans up. It is recommended though to
manually close the statement when it's not needed anymore for sensible
resource preservation.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
Parameters:
resultSetType - a result set type; one of ResultSet.TYPE_FORWARD_ONLY,ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
Parameters:
resultSetConcurrency - a concurrency type; one ofResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE a new DbStatement instance
exception:
DatabaseException - when an exception has occurred during thecreation of the DbStatement instance
See Also: com.uwyn.rife.database.DbStatement
See Also: DbConnection.getPreparedStatement(String)
See Also: DbConnection.getPreparedStatement(Query)
since:
1.0 |
| createStatement | | public DbStatement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws DatabaseException(Code) | | Creates a new DbStatement instance for this connection with
the given type, concurrency, and holdability.. It
will be registered and automatically closed when this
DbConnection cleans up. It is recommended though to
manually close the statement when it's not needed anymore for sensible
resource preservation.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
Parameters:
resultSetType - a result set type; one of ResultSet.TYPE_FORWARD_ONLY,ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
Parameters:
resultSetConcurrency - a concurrency type; one ofResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
Parameters:
resultSetHoldability - one of the following ResultSet constants:ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT a new DbStatement instance
exception:
DatabaseException - when an exception has occurred during thecreation of the DbStatement instance
See Also: com.uwyn.rife.database.DbStatement
See Also: DbConnection.getPreparedStatement(String)
See Also: DbConnection.getPreparedStatement(Query)
since:
1.0 |
| detectCleanup | | void detectCleanup() throws SQLException(Code) | | This method is used to check if this DbConnection instance
has been cleaned up before using the underlying JDBC connection.
exception:
SQLException - when it has been cleaned up. |
| finalize | | protected void finalize() throws Throwable(Code) | | Ensures that this DbConnection is correctly cleaned-up
when it's garbage collected.
exception:
Throwable - if an error occurred during the finalization
since:
1.0 |
| getDatasource | | public Datasource getDatasource()(Code) | | Retrieves the datasource this connection has been obtained from.
the Datasource instance this connection has beenobtained from
since:
1.0 |
| getMetaData | | public DatabaseMetaData getMetaData() throws DatabaseException(Code) | | Retrieves a DatabaseMetaData object that contains metadata
about the database to which this DbConnection object
represents a connection. The metadata includes information about the
database's tables, its supported SQL grammar, its stored procedures,
the capabilities of this connection, and so on.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
a DatabaseMetaData object for thisDbConnection instance; or null if the DbConnection instance is notconnected.
exception:
DatabaseException - if a database access error occurs
|
| getPreparedStatement | | public DbPreparedStatement getPreparedStatement(String sql) throws DatabaseException(Code) | | Creates a new DbPreparedStatement instance for this
connection from a regular SQL query string. Since the statement is
created from a String and not a
ParametrizedQuery instance, information is lacking to be
able to fully use the features of the resulting
DbPreparedStatement instance. It's recommended to use the
DbConnection.getPreparedStatement(Query) method instead if this is
possible.
The new statement will be registered and automatically closed when
this DbConnection cleans up. It is recommended though to
manually close the statement when it's not needed anymore for sensible
resource preservation.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
Parameters:
sql - a String instance with the SQL that is used toset up the prepared statement a new DbPreparedStatement instance
exception:
DatabaseException - when an exception has occurred during thecreation of the DbPreparedStatement instance
See Also: com.uwyn.rife.database.DbPreparedStatement
See Also: DbConnection.createStatement()
See Also: DbConnection.getPreparedStatement(Query)
since:
1.0 |
| getPreparedStatement | | public DbPreparedStatement getPreparedStatement(String sql, int autoGeneratedKeys) throws DatabaseException(Code) | | Creates a new DbPreparedStatement instance for this
connection from a Query instance that has the capability
to retrieve auto-generated keys. The given constant tells the driver
whether it should make auto-generated keys available for retrieval.
This parameter is ignored if the SQL statement is not an INSERT
statement.
Since the statement is created from a String and not a
ParametrizedQuery instance, information is lacking to be
able to fully use the features of the resulting
DbPreparedStatement instance. It's recommended to use the
DbConnection.getPreparedStatement(Query) method instead if this is
possible.
The new statement will be registered and automatically closed when
this DbConnection cleans up. It is recommended though to
manually close the statement when it's not needed anymore for sensible
resource preservation.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
Parameters:
sql - a String instance with the SQL that is used toset up the prepared statement
Parameters:
autoGeneratedKeys - a flag indicating whether auto-generated keysshould be returned; one of Statement.RETURN_GENERATED_KEYSor Statement.NO_GENERATED_KEYS a new DbPreparedStatement instance
exception:
DatabaseException - when an exception has occurred during thecreation of the DbPreparedStatement instance
See Also: com.uwyn.rife.database.DbPreparedStatement
See Also: DbConnection.createStatement()
See Also: DbConnection.getPreparedStatement(Query)
since:
1.0 |
| getPreparedStatement | | public DbPreparedStatement getPreparedStatement(Query query) throws DatabaseException(Code) | | Creates a new DbPreparedStatement instance for this
connection from a Query instance. Thanks to the additional
meta-data that's stored in a Query object, it's possible
to use the additional features that the
DbPreparedStatement provides on top of regular JDBC
methods.
The new statement will be registered and automatically closed when
this DbConnection cleans up. It is recommended though to
manually close the statement when it's not needed anymore for sensible
resource preservation.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
Parameters:
query - a Query instance that is used to set up theprepared statement a new DbPreparedStatement instance
exception:
DatabaseException - when an exception has occurred during thecreation of the DbPreparedStatement instance
See Also: com.uwyn.rife.database.DbPreparedStatement
See Also: DbConnection.createStatement()
See Also: DbConnection.getPreparedStatement(String)
since:
1.0 |
| getPreparedStatement | | public DbPreparedStatement getPreparedStatement(Query query, int autoGeneratedKeys) throws DatabaseException(Code) | | Creates a new DbPreparedStatement instance for this
connection from a Query instance that has the capability
to retrieve auto-generated keys. The given constant tells the driver
whether it should make auto-generated keys available for retrieval.
This parameter is ignored if the SQL statement is not an INSERT
statement.
Thanks to the additional meta-data that's stored in a
Query object, it's possible to use the additional features
that the DbPreparedStatement provides on top of regular
JDBC methods.
The new statement will be registered and automatically closed when
this DbConnection cleans up. It is recommended though to
manually close the statement when it's not needed anymore for sensible
resource preservation.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
Parameters:
query - a Query instance that is used to set up theprepared statement
Parameters:
autoGeneratedKeys - a flag indicating whether auto-generated keysshould be returned; one of Statement.RETURN_GENERATED_KEYSor Statement.NO_GENERATED_KEYS a new DbPreparedStatement instance
exception:
DatabaseException - when an exception has occurred during thecreation of the DbPreparedStatement instance
See Also: com.uwyn.rife.database.DbPreparedStatement
See Also: DbConnection.createStatement()
See Also: DbConnection.getPreparedStatement(String)
since:
1.0 |
| getPreparedStatement | | public DbPreparedStatement getPreparedStatement(Query query, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws DatabaseException(Code) | | Creates a new DbPreparedStatement instance for this
connection from a Query instance that will generate
ResultSet objects with the given type, concurrency,
and holdability.
This method is the same as the getPreparedStatement method
above, but it allows the default result set
type, concurrency, and holdability to be overridden.
Thanks to the additional meta-data that's stored in a
Query object, it's possible to use the additional features
that the DbPreparedStatement provides on top of regular
JDBC methods.
The new statement will be registered and automatically closed when
this DbConnection cleans up. It is recommended though to
manually close the statement when it's not needed anymore for sensible
resource preservation.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
Parameters:
query - a Query instance that is used to set up theprepared statement
Parameters:
resultSetType - one of the following ResultSet constants:ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, orResultSet.TYPE_SCROLL_SENSITIVE
Parameters:
resultSetConcurrency - one of the following ResultSet constants:ResultSet.CONCUR_READ_ONLY orResultSet.CONCUR_UPDATABLE
Parameters:
resultSetHoldability - one of the following ResultSet constants:ResultSet.HOLD_CURSORS_OVER_COMMIT orResultSet.CLOSE_CURSORS_AT_COMMIT a new DbPreparedStatement instance, that will generateResultSet objects with the given type,concurrency, and holdability
exception:
DatabaseException - when an exception has occurred during thecreation of the DbPreparedStatement instance
See Also: com.uwyn.rife.database.DbPreparedStatement
See Also: DbConnection.createStatement()
See Also: DbConnection.getPreparedStatement(String)
since:
1.2 |
| handleException | | void handleException() throws DatabaseException(Code) | | Performs the cleanup logic in case an exception is thrown during
execution. If the connection is part of a pooled datasource, all
connections in the pool will be closed and the whole pool will be setup
cleanly again. If the connection isn't pooled, it will be cleaned up
properly.
exception:
DatabaseException - when an error occurs during the cleanup ofthe connection, or when an error occurs when the pool is set up again. |
| isCleanedUp | | boolean isCleanedUp()(Code) | | Indicates whether this DbConnection instance has been
cleaned up or not.
true if it has been cleaned up; orfalse otherwise.
|
| isClosed | | public boolean isClosed() throws DatabaseException(Code) | | Indicates whether this DbConnection's connection to the
database is closed.
If an exception is thrown, this DbConnection is
automatically cleaned up. Also, any ongoing transaction will be
rolled-back automatically.
true when this DbConnection isclosed; or false if it's connected.
exception:
DatabaseException - when an error occurred during theverification of the JDBC connection's closed status
since:
1.0
|
| isTransactionValidForThread | | public boolean isTransactionValidForThread()(Code) | | Indicates whether the current thread has a valid transaction going on
for the execution of statements.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again.
true if a transaction is active that can be usedby the current thread; or false if the connection is closed, doesn't supporttransactions, has no active transaction or has a transaction that wasstarted by another thread.
exception:
DatabaseException - when errors occurred during theverification of the connection's open status and support fortransactions
See Also: DbConnection.supportsTransactions()
See Also: DbConnection.beginTransaction()
See Also: DbConnection.commit()
See Also: DbConnection.rollback()
See Also: DbConnection.isFree()
since:
1.0
|
| releaseStatement | | void releaseStatement(DbStatement statement)(Code) | | Removes a DbStatement instance from the collection of
managed statements. If the statement is not present, no error or
exception is thrown.
Parameters:
statement - the DbStatement that has to be removed.
since:
1.0 |
| setTransactionIsolation | | public void setTransactionIsolation(int level) throws DatabaseException(Code) | | Attempts to change the transaction isolation level for this
DbConnection object to the one given. The constants
defined in the interface Connection are the possible
transaction isolation levels.
Parameters:
level - transaction isolation level constant defined in the java.sql.Connection Connection interface
exception:
DatabaseException - if a database access error occurs
See Also: java.sql.Connection |
| supportsTransactions | | public boolean supportsTransactions() throws DatabaseException(Code) | | Indicates whether the Datasource of this
DbConnection supports transactions or not.
This information is only retrieved once and cached for the rest of
the lifetime of this connection.
If an exception is thrown, this DbConnection is
automatically closed and if it's part of a pool, all the other
connections are closed too and the pool is set up again. Also, any
ongoing transaction will be rolled-back automatically.
true if the Datasource supportstransactions; or false if the Datasource doesn't supporttransactions.
exception:
DatabaseException - when an error occurred during theverification of the transaction support
See Also: DbConnection.beginTransaction()
See Also: DbConnection.commit()
See Also: DbConnection.rollback()
See Also: DbConnection.isFree()
See Also: DbConnection.isTransactionValidForThread()
since:
1.0
|
|
|