Package rife.database

Class DbConnection

java.lang.Object
rife.database.DbConnection
All Implemented Interfaces:
AutoCloseable
public class DbConnection extends Object implements AutoCloseable
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
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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(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.
    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.
    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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

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

      Specified by:
      close in interface AutoCloseable
      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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.0
      See Also:

    • 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

      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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 {@link java.sql.Connection Connection} interface
      Throws:
      DatabaseException - if a database access error occurs
      See Also:

    • 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