org.springframework.jdbc.datasource
Class DataSourceUtils

java.lang.Object
  extended by org.springframework.jdbc.datasource.DataSourceUtils

public abstract class DataSourceUtils
extends java.lang.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

Nested Class Summary
private static class DataSourceUtils.ConnectionSynchronization
          Callback for resource cleanup at the end of a non-native JDBC transaction (e.g.
 
Field Summary
static int CONNECTION_SYNCHRONIZATION_ORDER
          Order value for TransactionSynchronization objects that clean up JDBC Connections.
private static Log logger
           
 
Constructor Summary
DataSourceUtils()
           
 
Method Summary
static void applyTimeout(java.sql.Statement stmt, javax.sql.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(java.sql.Statement stmt, javax.sql.DataSource dataSource)
          Apply the current transaction timeout, if any, to the given JDBC Statement object.
private static boolean connectionEquals(ConnectionHolder conHolder, java.sql.Connection passedInCon)
          Determine whether the given two Connections are equal, asking the target Connection in case of a proxy.
static java.sql.Connection doGetConnection(javax.sql.DataSource dataSource)
          Actually obtain a JDBC Connection from the given DataSource.
static void doReleaseConnection(java.sql.Connection con, javax.sql.DataSource dataSource)
          Actually close the given Connection, obtained from the given DataSource.
static java.sql.Connection getConnection(javax.sql.DataSource dataSource)
          Obtain a Connection from the given DataSource.
private static int getConnectionSynchronizationOrder(javax.sql.DataSource dataSource)
          Determine the connection synchronization order to use for the given DataSource.
static java.sql.Connection getTargetConnection(java.sql.Connection con)
          Return the innermost target Connection of the given Connection.
static boolean isConnectionTransactional(java.sql.Connection con, javax.sql.DataSource dataSource)
          Determine whether the given JDBC Connection is transactional, that is, bound to the current thread by Spring's transaction facilities.
static java.lang.Integer prepareConnectionForTransaction(java.sql.Connection con, TransactionDefinition definition)
          Prepare the given Connection with the given transaction semantics.
static void releaseConnection(java.sql.Connection con, javax.sql.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(java.sql.Connection con, java.lang.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

logger

private static final Log logger
Constructor Detail

DataSourceUtils

public DataSourceUtils()
Method Detail

getConnection

public static java.sql.Connection getConnection(javax.sql.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 java.sql.Connection doGetConnection(javax.sql.DataSource dataSource)
                                           throws java.sql.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:
java.sql.SQLException - if thrown by JDBC methods
See Also:
doReleaseConnection(java.sql.Connection, javax.sql.DataSource)

prepareConnectionForTransaction

public static java.lang.Integer prepareConnectionForTransaction(java.sql.Connection con,
                                                                TransactionDefinition definition)
                                                         throws java.sql.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:
java.sql.SQLException - if thrown by JDBC methods
See Also:
resetConnectionAfterTransaction(java.sql.Connection, java.lang.Integer)

resetConnectionAfterTransaction

public static void resetConnectionAfterTransaction(java.sql.Connection con,
                                                   java.lang.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(java.sql.Connection con,
                                                javax.sql.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(java.sql.Statement stmt,
                                           javax.sql.DataSource dataSource)
                                    throws java.sql.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:
java.sql.SQLException - if thrown by JDBC methods
See Also:
Statement.setQueryTimeout(int)

applyTimeout

public static void applyTimeout(java.sql.Statement stmt,
                                javax.sql.DataSource dataSource,
                                int timeout)
                         throws java.sql.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:
java.sql.SQLException - if thrown by JDBC methods
See Also:
Statement.setQueryTimeout(int)

releaseConnection

public static void releaseConnection(java.sql.Connection con,
                                     javax.sql.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(java.sql.Connection con,
                                       javax.sql.DataSource dataSource)
                                throws java.sql.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:
java.sql.SQLException - if thrown by JDBC methods
See Also:
doGetConnection(javax.sql.DataSource)

connectionEquals

private static boolean connectionEquals(ConnectionHolder conHolder,
                                        java.sql.Connection passedInCon)
Determine whether the given two Connections are equal, asking the target Connection in case of a proxy. Used to detect equality even if the user passed in a raw target Connection while the held one is a proxy.

Parameters:
conHolder - the ConnectionHolder for the held Connection (potentially a proxy)
passedInCon - the Connection passed-in by the user (potentially a target Connection without proxy)
Returns:
whether the given Connections are equal
See Also:
getTargetConnection(java.sql.Connection)

getTargetConnection

public static java.sql.Connection getTargetConnection(java.sql.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()

getConnectionSynchronizationOrder

private static int getConnectionSynchronizationOrder(javax.sql.DataSource dataSource)
Determine the connection synchronization order to use for the given DataSource. Decreased for every level of nesting that a DataSource has, checked through the level of DelegatingDataSource nesting.

Parameters:
dataSource - the DataSource to check
Returns:
the connection synchronization order to use
See Also:
CONNECTION_SYNCHRONIZATION_ORDER