org.springframework.jdbc.datasource
Class DataSourceUtils

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

public abstract class DataSourceUtils
extends Object

Helper class that provides static methods to obtain JDBC Connections from a DataSource, and to close Connections if necessary. Has special support for Spring-managed connections, e.g. for use with DataSourceTransactionManager.

Used internally by JdbcTemplate, 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, JdbcTemplate, org.springframework.jdbc.object

Field Summary
static int CONNECTION_SYNCHRONIZATION_ORDER
          Order value for TransactionSynchronization objects that clean up JDBC Connections.
 
Constructor Summary
DataSourceUtils()
           
 
Method Summary
static void applyTransactionTimeout(Statement stmt, DataSource dataSource)
          Apply the current transaction timeout, if any, to the given JDBC Statement object.
static void closeConnectionIfNecessary(Connection con, DataSource dataSource)
          Deprecated. in favor of releaseConnection
static Connection doGetConnection(DataSource dataSource)
          Actually get a JDBC Connection for the given DataSource.
static void doReleaseConnection(Connection con, DataSource dataSource)
          Actually release a JDBC Connection for the given DataSource.
static Connection getConnection(DataSource dataSource)
          Get a Connection from the given DataSource.
static Connection getTargetConnection(Connection con)
          Return the innermost target Connection of the given Connection.
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, created via the given DataSource, if it is not managed externally (i.e. 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
Get a Connection from the given DataSource. Changes any SQL exception 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. if in a JTA transaction).

Parameters:
dataSource - DataSource to get Connection from
Returns:
a JDBC Connection from the given DataSource
Throws:
CannotGetJdbcConnectionException - if the attempt to get a Connection failed
See Also:
TransactionSynchronizationManager, DataSourceTransactionManager

doGetConnection

public static Connection doGetConnection(DataSource dataSource)
                                  throws SQLException
Actually get a JDBC Connection for the given DataSource. Same as getConnection, 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 - DataSource to get Connection from
Returns:
a JDBC Connection from the given DataSource
Throws:
SQLException - if thrown by JDBC methods
See Also:
getConnection(DataSource), TransactionAwareDataSourceProxy

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)

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 - DataSource that the Connection came from
Throws:
SQLException
See Also:
Statement.setQueryTimeout(int)

closeConnectionIfNecessary

public static void closeConnectionIfNecessary(Connection con,
                                              DataSource dataSource)
Deprecated. in favor of releaseConnection

Close the given Connection if necessary, i.e. if it is not bound to the thread and it is not created by a SmartDataSource returning shouldClose=false.

See Also:
releaseConnection(java.sql.Connection, javax.sql.DataSource)

releaseConnection

public static void releaseConnection(Connection con,
                                     DataSource dataSource)
Close the given Connection, created via the given DataSource, if it is not managed externally (i.e. not bound to the thread). Will never close a Connection from a SmartDataSource returning shouldClose=false.

Parameters:
con - Connection to close if necessary (if this is null, the call will be ignored)
dataSource - DataSource that the Connection came from (can be null)
See Also:
SmartDataSource.shouldClose(java.sql.Connection)

doReleaseConnection

public static void doReleaseConnection(Connection con,
                                       DataSource dataSource)
                                throws SQLException
Actually release a JDBC Connection for the given DataSource. Same as releaseConnection, but throwing the original SQLException.

Directly accessed by TransactionAwareDataSourceProxy.

Parameters:
con - Connection to close if necessary (if this is null, the call will be ignored)
dataSource - DataSource that the Connection came from (can be null)
Throws:
SQLException - if thrown by JDBC methods
See Also:
releaseConnection(java.sql.Connection, javax.sql.DataSource), TransactionAwareDataSourceProxy

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. Else, 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()


Copyright (c) 2002-2005 The Spring Framework Project.