com.uwyn.rife.database
Class DbConnection

java.lang.Object
  com.uwyn.rife.database.DbConnection

public class DbConnection
extends Object

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.

Since:

1.0

Version:

$Revision: 3634 $

Author:

Geert Bevin (gbevin[remove] at uwyn dot com)

See Also:

Datasource.getConnection(), DbStatement, DbPreparedStatement

Method Summary

boolean	beginTransaction() Warning: only use the raw transaction methods if you really know what you're doing.
Object	clone() Simply clones the instance with the default clone method.
void	close() Releases all the resources that are being used by this connection.
boolean	commit() Warning: only use the raw transaction methods if you really know what you're doing.
DbStatement	createStatement() Creates a new DbStatement instance for this connection.
DbStatement	createStatement(int resultSetType, int resultSetConcurrency) Creates a new DbStatement instance for this connection with the given type and concurrency.
DbStatement	createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) Creates a new DbStatement instance for this connection with the given type, concurrency, and holdability..
protected void	finalize() Ensures that this DbConnection is correctly cleaned-up when it's garbage collected.
Datasource	getDatasource() Retrieves the datasource this connection has been obtained from.
DatabaseMetaData	getMetaData() Retrieves a DatabaseMetaData object that contains metadata about the database to which this DbConnection object represents a connection.
DbPreparedStatement	getPreparedStatement(Query query) Creates a new DbPreparedStatement instance for this connection from a Query instance.
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.
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.
DbPreparedStatement	getPreparedStatement(String sql) Creates a new DbPreparedStatement instance for this connection from a regular SQL query string.
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.
boolean	isClosed() Indicates whether this DbConnection's connection to the database is closed.
boolean	isFree() Indicates whether this DbConnection is free to execute statements for the current thread.
boolean	isTransactionValidForThread() Indicates whether the current thread has a valid transaction going on for the execution of statements.
boolean	rollback() Warning: only use the raw transaction methods if you really know what you're doing.
void	setTransactionIsolation(int level) Attempts to change the transaction isolation level for this DbConnection object to the one given.
boolean	supportsTransactions() Indicates whether the Datasource of this DbConnection supports transactions or not.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDatasource

public Datasource getDatasource()

Retrieves the datasource this connection has been obtained from.

Returns:

the Datasource instance this connection has been obtained from

Since:

1.0

close

public void close()
           throws DatabaseException

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.

Throws:

DatabaseException - if a database access error occurs, or if an error occurred during the closing of an ongoing transaction, or if an error occurred during the closing of the opened statements, or if an error occurred during the closing of the underlying JDBC connection.

Since:

1.0

createStatement

public DbStatement createStatement()
                            throws DatabaseException

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.

Returns:

a new DbStatement instance

Throws:

DatabaseException - when an exception has occurred during the creation of the DbStatement instance

Since:

1.0

See Also:

DbStatement, getPreparedStatement(String), getPreparedStatement(Query)

createStatement

public DbStatement createStatement(int resultSetType,
                                   int resultSetConcurrency)
                            throws DatabaseException

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

resultSetConcurrency - a concurrency type; one of ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE

Returns:

a new DbStatement instance

Throws:

DatabaseException - when an exception has occurred during the creation of the DbStatement instance

Since:

1.0

See Also:

DbStatement, getPreparedStatement(String), getPreparedStatement(Query)

createStatement

public DbStatement createStatement(int resultSetType,
                                   int resultSetConcurrency,
                                   int resultSetHoldability)
                            throws DatabaseException

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

resultSetConcurrency - a concurrency type; one of ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE

resultSetHoldability - one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT

Returns:

a new DbStatement instance

Throws:

DatabaseException - when an exception has occurred during the creation of the DbStatement instance

Since:

1.0

See Also:

DbStatement, getPreparedStatement(String), getPreparedStatement(Query)

getPreparedStatement

public DbPreparedStatement getPreparedStatement(String sql)
                                         throws DatabaseException

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 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 to set up the prepared statement

Returns:

a new DbPreparedStatement instance

Throws:

DatabaseException - when an exception has occurred during the creation of the DbPreparedStatement instance

Since:

1.0

See Also:

DbPreparedStatement, createStatement(), getPreparedStatement(Query)

getPreparedStatement

public DbPreparedStatement getPreparedStatement(String sql,
                                                int autoGeneratedKeys)
                                         throws DatabaseException

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 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 to set up the prepared statement

autoGeneratedKeys - a flag indicating whether auto-generated keys should be returned; one of Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS

Returns:

a new DbPreparedStatement instance

Throws:

DatabaseException - when an exception has occurred during the creation of the DbPreparedStatement instance

Since:

1.0

See Also:

DbPreparedStatement, createStatement(), getPreparedStatement(Query)

getPreparedStatement

public DbPreparedStatement getPreparedStatement(Query query)
                                         throws DatabaseException

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 the prepared statement

Returns:

a new DbPreparedStatement instance

Throws:

DatabaseException - when an exception has occurred during the creation of the DbPreparedStatement instance

Since:

1.0

See Also:

DbPreparedStatement, createStatement(), getPreparedStatement(String)

getPreparedStatement

public DbPreparedStatement getPreparedStatement(Query query,
                                                int autoGeneratedKeys)
                                         throws DatabaseException

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 the prepared statement

autoGeneratedKeys - a flag indicating whether auto-generated keys should be returned; one of Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS

Returns:

a new DbPreparedStatement instance

Throws:

DatabaseException - when an exception has occurred during the creation of the DbPreparedStatement instance

Since:

1.0

See Also:

DbPreparedStatement, createStatement(), getPreparedStatement(String)

getPreparedStatement

public DbPreparedStatement getPreparedStatement(Query query,
                                                int resultSetType,
                                                int resultSetConcurrency,
                                                int resultSetHoldability)
                                         throws DatabaseException

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 the prepared statement

resultSetType - one of the following ResultSet constants: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE

resultSetConcurrency - one of the following ResultSet constants: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE

resultSetHoldability - one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT

Returns:

a new DbPreparedStatement instance, that will generate ResultSet objects with the given type, concurrency, and holdability

Throws:

DatabaseException - when an exception has occurred during the creation of the DbPreparedStatement instance

Since:

1.2

See Also:

DbPreparedStatement, createStatement(), getPreparedStatement(String)

supportsTransactions

public boolean supportsTransactions()
                             throws DatabaseException

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.

Returns:

true if the Datasource supports transactions; or

false if the Datasource doesn't support transactions.

Throws:

DatabaseException - when an error occurred during the verification of the transaction support

Since:

1.0

See Also:

beginTransaction(), commit(), rollback(), isFree(), isTransactionValidForThread()

beginTransaction

public boolean beginTransaction()
                         throws DatabaseException

Warning: only use the raw transaction methods if you really know what you're doing. It's almost always better to use the inTransaction method of the DbQueryManager class instead.

Starts a new transaction if the Datasource supports it.

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.

Returns:

true if the transaction was successfully started; or

false if the Datasource doesn't support transactions, or if a transaction is already active on this DbConnection.

Throws:

DatabaseException - when an error occurred during the creation of the new transaction, or when the active transaction has timed-out.

Since:

1.0

See Also:

DbQueryManager.inTransaction(DbTransactionUser), supportsTransactions(), commit(), rollback(), isFree(), isTransactionValidForThread()

commit

public boolean commit()
               throws DatabaseException

Warning: only use the raw transaction methods if you really know what you're doing. It's almost always better to use the inTransaction method of the DbQueryManager class instead.

Commits an active transaction.

All transaction-related resources are cleared and all the threads that are waiting for the transaction to terminate are woken up.

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.

Returns:

true if the transaction was successfully committed; or

false if the Datasource doesn't support transactions, or when no transaction is active on this DbConnection, or when the executing thread isn't the thread that began the transaction.

Throws:

DatabaseException - when an error occurred during the commit of the active transaction, or when the active transaction has timed-out.

Since:

1.0

See Also:

DbQueryManager.inTransaction(DbTransactionUser), supportsTransactions(), beginTransaction(), rollback(), isFree(), isTransactionValidForThread()

rollback

public boolean rollback()
                 throws DatabaseException

Warning: only use the raw transaction methods if you really know what you're doing. It's almost always better to use the inTransaction method of the DbQueryManager class instead.

Rolls-back an active transaction.

All transaction-related resources are cleared and all the threads that are waiting for the transaction to terminate are woken up.

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.

Returns:

true if the transaction was successfully rolled-back; or

false if the Datasource doesn't support transactions, or when no transaction is active on this DbConnection, or when the executing thread isn't the thread that began the transaction.

Throws:

DatabaseException - when an error occurred during the rollback of the active transaction, or when the active transaction has timed-out.

Since:

1.0

See Also:

DbQueryManager.inTransaction(DbTransactionUser), supportsTransactions(), beginTransaction(), commit(), isFree(), isTransactionValidForThread()

isFree

public boolean isFree()

Indicates whether this DbConnection is free to execute statements for the current thread.

Returns:

true if a statement can be executed by the current thread on this DbConnection; or

false if the connection is closed or when a transaction is already active on this DbConnection for another thread.

Since:

1.0

See Also:

supportsTransactions(), beginTransaction(), commit(), rollback(), isTransactionValidForThread()

isTransactionValidForThread

public boolean isTransactionValidForThread()

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.

Returns:

true if a transaction is active that can be used by the current thread; or

false if the connection is closed, doesn't support transactions, has no active transaction or has a transaction that was started by another thread.

Throws:

DatabaseException - when errors occurred during the verification of the connection's open status and support for transactions

Since:

1.0

See Also:

supportsTransactions(), beginTransaction(), commit(), rollback(), isFree()

isClosed

public boolean isClosed()
                 throws DatabaseException

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.

Returns:

true when this DbConnection is closed; or

false if it's connected.

Throws:

DatabaseException - when an error occurred during the verification of the JDBC connection's closed status

Since:

1.0

getMetaData

public DatabaseMetaData getMetaData()
                             throws DatabaseException

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.

Returns:

a DatabaseMetaData object for this DbConnection instance; or

null if the DbConnection instance is not connected.

Throws:

DatabaseException - if a database access error occurs

setTransactionIsolation

public void setTransactionIsolation(int level)
                             throws DatabaseException

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 Connection interface

Throws:

DatabaseException - if a database access error occurs

See Also:

Connection

finalize

protected void finalize()
                 throws Throwable

Ensures that this DbConnection is correctly cleaned-up when it's garbage collected.

Overrides:

finalize in class Object

Throws:

Throwable - if an error occurred during the finalization

Since:

1.0

clone

public Object clone()

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.

Overrides:

clone in class Object

Since:

1.0