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

org.springframework.jdbc.datasource

## Class DataSourceUtils

- java.lang.Object
- - org.springframework.jdbc.datasource.DataSourceUtils

-     public abstract class DataSourceUtils
      extends Object

  Helper class that provides static methods for obtaining JDBC Connections from a `DataSource`. Includes special support for Spring-managed transactional Connections, e.g. managed by `DataSourceTransactionManager` or `JtaTransactionManager`.

  Used internally by Spring's `JdbcTemplate`, Spring's JDBC operation objects and the JDBC `DataSourceTransactionManager`. Can also be used directly in application code.

  Author:
    Rod Johnson, Juergen Hoeller
  See Also:
    `getConnection(javax.sql.DataSource)`, `releaseConnection(java.sql.Connection, javax.sql.DataSource)`, `DataSourceTransactionManager`, `JtaTransactionManager`, `TransactionSynchronizationManager`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CONNECTION_SYNCHRONIZATION_ORDER` Order value for TransactionSynchronization objects that clean up JDBC Connections.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataSourceUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `applyTimeout(Statement stmt, DataSource dataSource, int timeout)` Apply the specified timeout - overridden by the current transaction timeout, if any - to the given JDBC Statement object.
    `static void` | `applyTransactionTimeout(Statement stmt, DataSource dataSource)` Apply the current transaction timeout, if any, to the given JDBC Statement object.
    `static void` | `doCloseConnection(Connection con, DataSource dataSource)` Close the Connection, unless a `SmartDataSource` doesn't want us to.
    `static Connection` | `doGetConnection(DataSource dataSource)` Actually obtain a JDBC Connection from the given DataSource.
    `static void` | `doReleaseConnection(Connection con, DataSource dataSource)` Actually close the given Connection, obtained from the given DataSource.
    `static Connection` | `getConnection(DataSource dataSource)` Obtain a Connection from the given DataSource.
    `static Connection` | `getTargetConnection(Connection con)` Return the innermost target Connection of the given Connection.
    `static boolean` | `isConnectionTransactional(Connection con, DataSource dataSource)` Determine whether the given JDBC Connection is transactional, that is, bound to the current thread by Spring's transaction facilities.
    `static Integer` | `prepareConnectionForTransaction(Connection con, TransactionDefinition definition)` Prepare the given Connection with the given transaction semantics.
    `static void` | `releaseConnection(Connection con, DataSource dataSource)` Close the given Connection, obtained from the given DataSource, if it is not managed externally (that is, not bound to the thread).
    `static void` | `resetConnectionAfterTransaction(Connection con, Integer previousIsolationLevel)` Reset the given Connection after a transaction, regarding read-only flag and isolation level.

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

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

- - ### Field Detail

    - #### CONNECTION_SYNCHRONIZATION_ORDER

          public static final int CONNECTION_SYNCHRONIZATION_ORDER

      Order value for TransactionSynchronization objects that clean up JDBC Connections.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DataSourceUtils

          public DataSourceUtils()

  - ### Method Detail

    - #### getConnection

          public static Connection getConnection(DataSource dataSource)
                                          throws CannotGetJdbcConnectionException

      Obtain a Connection from the given DataSource. Translates SQLExceptions into the Spring hierarchy of unchecked generic data access exceptions, simplifying calling code and making any exception that is thrown more meaningful.

      Is aware of a corresponding Connection bound to the current thread, for example when using `DataSourceTransactionManager`. Will bind a Connection to the thread if transaction synchronization is active, e.g. when running within a `JTA` transaction).

      Parameters:
        `dataSource` - the DataSource to obtain Connections from
      Returns:
        a JDBC Connection from the given DataSource
      Throws:
        `CannotGetJdbcConnectionException` - if the attempt to get a Connection failed
      See Also:
        `releaseConnection(java.sql.Connection, javax.sql.DataSource)`

    - #### doGetConnection

          public static Connection doGetConnection(DataSource dataSource)
                                            throws SQLException

      Actually obtain a JDBC Connection from the given DataSource. Same as `getConnection(javax.sql.DataSource)`, but throwing the original SQLException.

      Is aware of a corresponding Connection bound to the current thread, for example when using `DataSourceTransactionManager`. Will bind a Connection to the thread if transaction synchronization is active (e.g. if in a JTA transaction).

      Directly accessed by `TransactionAwareDataSourceProxy`.

      Parameters:
        `dataSource` - the DataSource to obtain Connections from
      Returns:
        a JDBC Connection from the given DataSource
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `doReleaseConnection(java.sql.Connection, javax.sql.DataSource)`

    - #### prepareConnectionForTransaction

          public static Integer prepareConnectionForTransaction(Connection con,
                                                TransactionDefinition definition)
                                                         throws SQLException

      Prepare the given Connection with the given transaction semantics.
      Parameters:
        `con` - the Connection to prepare
        `definition` - the transaction definition to apply
      Returns:
        the previous isolation level, if any
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `resetConnectionAfterTransaction(java.sql.Connection, java.lang.Integer)`

    - #### resetConnectionAfterTransaction

          public static void resetConnectionAfterTransaction(Connection con,
                                             Integer previousIsolationLevel)

      Reset the given Connection after a transaction, regarding read-only flag and isolation level.
      Parameters:
        `con` - the Connection to reset
        `previousIsolationLevel` - the isolation level to restore, if any
      See Also:
        `prepareConnectionForTransaction(java.sql.Connection, org.springframework.transaction.TransactionDefinition)`

    - #### isConnectionTransactional

          public static boolean isConnectionTransactional(Connection con,
                                          DataSource dataSource)

      Determine whether the given JDBC Connection is transactional, that is, bound to the current thread by Spring's transaction facilities.
      Parameters:
        `con` - the Connection to check
        `dataSource` - the DataSource that the Connection was obtained from (may be `null`)
      Returns:
        whether the Connection is transactional

    - #### applyTransactionTimeout

          public static void applyTransactionTimeout(Statement stmt,
                                     DataSource dataSource)
                                              throws SQLException

      Apply the current transaction timeout, if any, to the given JDBC Statement object.
      Parameters:
        `stmt` - the JDBC Statement object
        `dataSource` - the DataSource that the Connection was obtained from
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `Statement.setQueryTimeout(int)`

    - #### applyTimeout

          public static void applyTimeout(Statement stmt,
                          DataSource dataSource,
                          int timeout)
                                   throws SQLException

      Apply the specified timeout - overridden by the current transaction timeout, if any - to the given JDBC Statement object.
      Parameters:
        `stmt` - the JDBC Statement object
        `dataSource` - the DataSource that the Connection was obtained from
        `timeout` - the timeout to apply (or 0 for no timeout outside of a transaction)
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `Statement.setQueryTimeout(int)`

    - #### releaseConnection

          public static void releaseConnection(Connection con,
                               DataSource dataSource)

      Close the given Connection, obtained from the given DataSource, if it is not managed externally (that is, not bound to the thread).
      Parameters:
        `con` - the Connection to close if necessary (if this is `null`, the call will be ignored)
        `dataSource` - the DataSource that the Connection was obtained from (may be `null`)
      See Also:
        `getConnection(javax.sql.DataSource)`

    - #### doReleaseConnection

          public static void doReleaseConnection(Connection con,
                                 DataSource dataSource)
                                          throws SQLException

      Actually close the given Connection, obtained from the given DataSource. Same as `releaseConnection(java.sql.Connection, javax.sql.DataSource)`, but throwing the original SQLException.

      Directly accessed by `TransactionAwareDataSourceProxy`.

      Parameters:
        `con` - the Connection to close if necessary (if this is `null`, the call will be ignored)
        `dataSource` - the DataSource that the Connection was obtained from (may be `null`)
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `doGetConnection(javax.sql.DataSource)`

    - #### doCloseConnection

          public static void doCloseConnection(Connection con,
                               DataSource dataSource)
                                        throws SQLException

      Close the Connection, unless a `SmartDataSource` doesn't want us to.
      Parameters:
        `con` - the Connection to close if necessary
        `dataSource` - the DataSource that the Connection was obtained from
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `Connection.close()`, `SmartDataSource.shouldClose(Connection)`

    - #### getTargetConnection

          public static Connection getTargetConnection(Connection con)

      Return the innermost target Connection of the given Connection. If the given Connection is a proxy, it will be unwrapped until a non-proxy Connection is found. Otherwise, the passed-in Connection will be returned as-is.
      Parameters:
        `con` - the Connection proxy to unwrap
      Returns:
        the innermost target Connection, or the passed-in one if no proxy
      See Also:
        `ConnectionProxy.getTargetConnection()`