ConnectionHolder (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jdbc.datasource

## Class ConnectionHolder

- java.lang.Object
- - org.springframework.transaction.support.ResourceHolderSupport
  - - org.springframework.jdbc.datasource.ConnectionHolder

- All Implemented Interfaces:
    ResourceHolder

      public class ConnectionHolder
      extends ResourceHolderSupport

  Connection holder, wrapping a JDBC Connection. `DataSourceTransactionManager` binds instances of this class to the thread, for a specific DataSource.

  Inherits rollback-only support for nested JDBC transactions and reference count functionality from the base class.

  Note: This is an SPI class, not intended to be used by applications.

  Since:
    06.05.2003
  Author:
    Juergen Hoeller
  See Also:
    `DataSourceTransactionManager`, `DataSourceUtils`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `SAVEPOINT_NAME_PREFIX`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConnectionHolder(Connection connection)` Create a new ConnectionHolder for the given JDBC Connection, wrapping it with a `SimpleConnectionHandle`, assuming that there is no ongoing transaction.
    `ConnectionHolder(Connection connection, boolean transactionActive)` Create a new ConnectionHolder for the given JDBC Connection, wrapping it with a `SimpleConnectionHandle`.
    `ConnectionHolder(ConnectionHandle connectionHandle)` Create a new ConnectionHolder for the given ConnectionHandle.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Clear the transactional state of this resource holder.
    `Savepoint` | `createSavepoint()` Create a new JDBC 3.0 Savepoint for the current Connection, using generated savepoint names that are unique for the Connection.
    `Connection` | `getConnection()` Return the current Connection held by this ConnectionHolder.
    `ConnectionHandle` | `getConnectionHandle()` Return the ConnectionHandle held by this ConnectionHolder.
    `protected boolean` | `hasConnection()` Return whether this holder currently has a Connection.
    `protected boolean` | `isTransactionActive()` Return whether this holder represents an active, JDBC-managed transaction.
    `void` | `released()` Releases the current Connection held by this ConnectionHolder.
    `protected void` | `setConnection(Connection connection)` Override the existing Connection handle with the given Connection.
    `protected void` | `setTransactionActive(boolean transactionActive)` Set whether this holder represents an active, JDBC-managed transaction.
    `boolean` | `supportsSavepoints()` Return whether JDBC 3.0 Savepoints are supported.

    - ### Methods inherited from class org.springframework.transaction.support.ResourceHolderSupport

      `getDeadline, getTimeToLiveInMillis, getTimeToLiveInSeconds, hasTimeout, isOpen, isRollbackOnly, isSynchronizedWithTransaction, isVoid, requested, reset, setRollbackOnly, setSynchronizedWithTransaction, setTimeoutInMillis, setTimeoutInSeconds, unbound`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SAVEPOINT_NAME_PREFIX

          public static final String SAVEPOINT_NAME_PREFIX

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ConnectionHolder

          public ConnectionHolder(ConnectionHandle connectionHandle)

      Create a new ConnectionHolder for the given ConnectionHandle.
      Parameters:
        `connectionHandle` - the ConnectionHandle to hold

    - #### ConnectionHolder

          public ConnectionHolder(Connection connection)

      Create a new ConnectionHolder for the given JDBC Connection, wrapping it with a `SimpleConnectionHandle`, assuming that there is no ongoing transaction.
      Parameters:
        `connection` - the JDBC Connection to hold
      See Also:
        `SimpleConnectionHandle`, `ConnectionHolder(java.sql.Connection, boolean)`

    - #### ConnectionHolder

          public ConnectionHolder(Connection connection,
                          boolean transactionActive)

      Create a new ConnectionHolder for the given JDBC Connection, wrapping it with a `SimpleConnectionHandle`.
      Parameters:
        `connection` - the JDBC Connection to hold
        `transactionActive` - whether the given Connection is involved in an ongoing transaction
      See Also:
        `SimpleConnectionHandle`

  - ### Method Detail

    - #### getConnectionHandle

          public ConnectionHandle getConnectionHandle()

      Return the ConnectionHandle held by this ConnectionHolder.

    - #### hasConnection

          protected boolean hasConnection()

      Return whether this holder currently has a Connection.

    - #### setTransactionActive

          protected void setTransactionActive(boolean transactionActive)

      Set whether this holder represents an active, JDBC-managed transaction.
      See Also:
        `DataSourceTransactionManager`

    - #### isTransactionActive

          protected boolean isTransactionActive()

      Return whether this holder represents an active, JDBC-managed transaction.

    - #### setConnection

          protected void setConnection(Connection connection)

      Override the existing Connection handle with the given Connection. Reset the handle if given `null`.

      Used for releasing the Connection on suspend (with a `null` argument) and setting a fresh Connection on resume.

    - #### getConnection

          public Connection getConnection()

      Return the current Connection held by this ConnectionHolder.

      This will be the same Connection until `released` gets called on the ConnectionHolder, which will reset the held Connection, fetching a new Connection on demand.

      See Also:
        `ConnectionHandle.getConnection()`, `released()`

    - #### supportsSavepoints

          public boolean supportsSavepoints()
                                     throws SQLException

      Return whether JDBC 3.0 Savepoints are supported. Caches the flag for the lifetime of this ConnectionHolder.
      Throws:
        `SQLException` - if thrown by the JDBC driver

    - #### createSavepoint

          public Savepoint createSavepoint()
                                    throws SQLException

      Create a new JDBC 3.0 Savepoint for the current Connection, using generated savepoint names that are unique for the Connection.
      Returns:
        the new Savepoint
      Throws:
        `SQLException` - if thrown by the JDBC driver

    - #### released

          public void released()

      Releases the current Connection held by this ConnectionHolder.

      This is necessary for ConnectionHandles that expect "Connection borrowing", where each returned Connection is only temporarily leased and needs to be returned once the data operation is done, to make the Connection available for other operations within the same transaction. This is the case with JDO 2.0 DataStoreConnections, for example.

      Overrides:
        `released` in class `ResourceHolderSupport`
      See Also:
        `DefaultJdoDialect.getJdbcConnection(javax.jdo.PersistenceManager, boolean)`

    - #### clear

          public void clear()

      Description copied from class: `ResourceHolderSupport`
      Clear the transactional state of this resource holder.
      Overrides:
        `clear` in class `ResourceHolderSupport`