Top Description Inners Fields Constructors Methods
org.springframework.jdbc.datasource

public abstract Class DataSourceUtils

extends Object
Class Inheritance
Imports
java.sql.Connection, .SQLException, .Statement, javax.sql.DataSource, org.apache.commons.logging.Log, .LogFactory, org.springframework.jdbc.CannotGetJdbcConnectionException, org.springframework.lang.Nullable, org.springframework.transaction.TransactionDefinition, org.springframework.transaction.support.TransactionSynchronization, .TransactionSynchronizationManager, org.springframework.util.Assert

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

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

Authors
Rod Johnson, Juergen Hoeller
See Also
getConnection, releaseConnection, org.springframework.jdbc.core.JdbcTemplate, org.springframework.jdbc.support.JdbcTransactionManager, org.springframework.transaction.jta.JtaTransactionManager, org.springframework.transaction.support.TransactionSynchronizationManager

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
DataSourceUtils.ConnectionSynchronization

Callback for resource cleanup at the end of a non-native JDBC transaction (e.g. when participating in a JtaTransactionManager transaction).

Field Summary

Modifier and TypeField and Description
public static final int
CONNECTION_SYNCHRONIZATION_ORDER

Order value for TransactionSynchronization objects that clean up JDBC Connections.

private static final Log

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public static void
applyTimeout(Statement
the JDBC Statement object
stmt
,
DataSource
the DataSource that the Connection was obtained from
dataSource
,
int
the timeout to apply (or 0 for no timeout outside of a transaction)
timeout
)

Apply the specified timeout - overridden by the current transaction timeout, if any - to the given JDBC Statement object.

public static void
applyTransactionTimeout(Statement
the JDBC Statement object
stmt
,
DataSource
the DataSource that the Connection was obtained from
dataSource
)

Apply the current transaction timeout, if any, to the given JDBC Statement object.

private static boolean

Returns:

whether the given Connections are equal
connectionEquals
(ConnectionHolder
the ConnectionHolder for the held Connection (potentially a proxy)
conHolder
,
Connection
the Connection passed-in by the user (potentially a target Connection without proxy)
passedInCon
)

Determine whether the given two Connections are equal, asking the target Connection in case of a proxy.

public static void
doCloseConnection(Connection
the Connection to close if necessary
con
,
DataSource
the DataSource that the Connection was obtained from
dataSource
)

Close the Connection, unless a SmartDataSource doesn't want us to.

public static Connection

Returns:

a JDBC Connection from the given DataSource
doGetConnection
(DataSource
the DataSource to obtain Connections from
dataSource
)

Actually obtain a JDBC Connection from the given DataSource.

public static void
doReleaseConnection(Connection
the Connection to close if necessary (if this is null, the call will be ignored)
con
,
DataSource
the DataSource that the Connection was obtained from (may be null)
dataSource
)

Actually close the given Connection, obtained from the given DataSource.

private static Connection

Returns:

a JDBC Connection from the given DataSource (never null)
fetchConnection
(DataSource
the DataSource to obtain Connections from
dataSource
)

Actually fetch a Connection from the given DataSource, defensively turning an unexpected null return value from DataSource#getConnection() into an IllegalStateException.

public static Connection

Returns:

a JDBC Connection from the given DataSource
getConnection
(DataSource
the DataSource to obtain Connections from
dataSource
)

Obtain a Connection from the given DataSource.

private static int

Returns:

the connection synchronization order to use
getConnectionSynchronizationOrder
(DataSource
the DataSource to check
dataSource
)

Determine the connection synchronization order to use for the given DataSource.

public static Connection

Returns:

the innermost target Connection, or the passed-in one if no proxy
getTargetConnection
(Connection
the Connection proxy to unwrap
con
)

Return the innermost target Connection of the given Connection.

public static boolean

Returns:

whether the Connection is transactional
isConnectionTransactional
(Connection
the Connection to check
con
,
DataSource
the DataSource that the Connection was obtained from (may be null)
dataSource
)

Determine whether the given JDBC Connection is transactional, that is, bound to the current thread by Spring's transaction facilities.

public static Integer

Returns:

the previous isolation level, if any
prepareConnectionForTransaction
(Connection
the Connection to prepare
con
,
TransactionDefinition
the transaction definition to apply
definition
)

Prepare the given Connection with the given transaction semantics.

public static void
releaseConnection(Connection
the Connection to close if necessary (if this is null, the call will be ignored)
con
,
DataSource
the DataSource that the Connection was obtained from (may be null)
dataSource
)

Close the given Connection, obtained from the given DataSource, if it is not managed externally (that is, not bound to the thread).

public static void
resetConnectionAfterTransaction(Connection
the Connection to reset
con
,
Integer
the isolation level to restore, if any
previousIsolationLevel
,
boolean
whether to reset the connection's read-only flag
resetReadOnly
)

Reset the given Connection after a transaction, regarding read-only flag and isolation level.

public static void
resetConnectionAfterTransaction(Connection
the Connection to reset
con
,
Integer
the isolation level to restore, if any
previousIsolationLevel
)

Reset the given Connection after a transaction, regarding read-only flag and isolation level.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

CONNECTION_SYNCHRONIZATION_ORDERback to summary
public static final int CONNECTION_SYNCHRONIZATION_ORDER

Order value for TransactionSynchronization objects that clean up JDBC Connections.

loggerback to summary
private static final Log logger

Constructor Detail

DataSourceUtilsback to summary
public DataSourceUtils()

Method Detail

applyTimeoutback to summary
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:Statement

the JDBC Statement object

dataSource:DataSource

the DataSource that the Connection was obtained from

timeout:int

the timeout to apply (or 0 for no timeout outside of a transaction)

Exceptions
SQLException:
if thrown by JDBC methods
See Also
java.sql.Statement#setQueryTimeout
applyTransactionTimeoutback to summary
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:Statement

the JDBC Statement object

dataSource:DataSource

the DataSource that the Connection was obtained from

Exceptions
SQLException:
if thrown by JDBC methods
See Also
java.sql.Statement#setQueryTimeout
connectionEqualsback to summary
private static boolean connectionEquals(ConnectionHolder conHolder, 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:ConnectionHolder

the ConnectionHolder for the held Connection (potentially a proxy)

passedInCon:Connection

the Connection passed-in by the user (potentially a target Connection without proxy)

Returns:boolean

whether the given Connections are equal

See Also
getTargetConnection
doCloseConnectionback to summary
public static void doCloseConnection(Connection con, DataSource dataSource) throws SQLException

Close the Connection, unless a SmartDataSource doesn't want us to.

Parameters
con:Connection

the Connection to close if necessary

dataSource:DataSource

the DataSource that the Connection was obtained from

Exceptions
SQLException:
if thrown by JDBC methods
See Also
Connection#close(), SmartDataSource#shouldClose(Connection)
doGetConnectionback to summary
public static Connection doGetConnection(DataSource dataSource) throws SQLException

Actually obtain a JDBC Connection from 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

the DataSource to obtain Connections from

Returns:Connection

a JDBC Connection from the given DataSource

Exceptions
SQLException:
if thrown by JDBC methods
See Also
doReleaseConnection
doReleaseConnectionback to summary
public static void doReleaseConnection(Connection con, DataSource dataSource) throws SQLException

Actually close the given Connection, obtained from the given DataSource. Same as releaseConnection, but throwing the original SQLException.

Directly accessed by TransactionAwareDataSourceProxy.

Parameters
con:Connection

the Connection to close if necessary (if this is null, the call will be ignored)

dataSource:DataSource

the DataSource that the Connection was obtained from (may be null)

Exceptions
SQLException:
if thrown by JDBC methods
See Also
doGetConnection
fetchConnectionback to summary
private static Connection fetchConnection(DataSource dataSource) throws SQLException

Actually fetch a Connection from the given DataSource, defensively turning an unexpected null return value from DataSource#getConnection() into an IllegalStateException.

Parameters
dataSource:DataSource

the DataSource to obtain Connections from

Returns:Connection

a JDBC Connection from the given DataSource (never null)

Exceptions
SQLException:
if thrown by JDBC methods
IllegalStateException:
if the DataSource returned a null value
See Also
DataSource#getConnection()
getConnectionback to summary
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:DataSource

the DataSource to obtain Connections from

Returns:Connection

a JDBC Connection from the given DataSource

Exceptions
CannotGetJdbcConnectionException:
if the attempt to get a Connection failed
See Also
releaseConnection(Connection, DataSource), isConnectionTransactional(Connection, DataSource)
getConnectionSynchronizationOrderback to summary
private static int getConnectionSynchronizationOrder(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:DataSource

the DataSource to check

Returns:int

the connection synchronization order to use

See Also
CONNECTION_SYNCHRONIZATION_ORDER
getTargetConnectionback to summary
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:Connection

the Connection proxy to unwrap

Returns:Connection

the innermost target Connection, or the passed-in one if no proxy

See Also
ConnectionProxy#getTargetConnection()
isConnectionTransactionalback to summary
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:Connection

the Connection to check

dataSource:DataSource

the DataSource that the Connection was obtained from (may be null)

Returns:boolean

whether the Connection is transactional

See Also
getConnection(DataSource)
prepareConnectionForTransactionback to summary
public static Integer prepareConnectionForTransaction(Connection con, TransactionDefinition definition) throws SQLException

Prepare the given Connection with the given transaction semantics.

Parameters
con:Connection

the Connection to prepare

definition:TransactionDefinition

the transaction definition to apply

Returns:Integer

the previous isolation level, if any

Annotations
@Nullable
Exceptions
SQLException:
if thrown by JDBC methods
See Also
resetConnectionAfterTransaction, Connection#setTransactionIsolation, Connection#setReadOnly
releaseConnectionback to summary
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:Connection

the Connection to close if necessary (if this is null, the call will be ignored)

dataSource:DataSource

the DataSource that the Connection was obtained from (may be null)

See Also
getConnection
resetConnectionAfterTransactionback to summary
public static void resetConnectionAfterTransaction(Connection con, Integer previousIsolationLevel, boolean resetReadOnly)

Reset the given Connection after a transaction, regarding read-only flag and isolation level.

Parameters
con:Connection

the Connection to reset

previousIsolationLevel:Integer

the isolation level to restore, if any

resetReadOnly:boolean

whether to reset the connection's read-only flag

Since
5.2.1
See Also
prepareConnectionForTransaction, Connection#setTransactionIsolation, Connection#setReadOnly
resetConnectionAfterTransactionback to summary
public static void resetConnectionAfterTransaction(Connection con, Integer previousIsolationLevel)

Reset the given Connection after a transaction, regarding read-only flag and isolation level.

Parameters
con:Connection

the Connection to reset

previousIsolationLevel:Integer

the isolation level to restore, if any

Annotations
@Deprecated
org.springframework.jdbc.datasource back to summary

private Class DataSourceUtils.ConnectionSynchronization

extends Object
implements TransactionSynchronization
Class Inheritance
  • java.lang.Object
  • org.springframework.jdbc.datasource.DataSourceUtils.ConnectionSynchronization
All Implemented Interfaces
org.springframework.transaction.support.TransactionSynchronization, java.io.Flushable, org.springframework.core.Ordered

Callback for resource cleanup at the end of a non-native JDBC transaction (e.g. when participating in a JtaTransactionManager transaction).
See Also
org.springframework.transaction.jta.JtaTransactionManager

Field Summary

Modifier and TypeField and Description
private final ConnectionHolder
private final DataSource
private boolean
private final int

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public void
afterCompletion(int
completion status according to the STATUS_* constants
status
)

Overrides default org.springframework.transaction.support.TransactionSynchronization.afterCompletion.

Invoked after transaction commit/rollback.

public void
beforeCompletion()

Overrides default org.springframework.transaction.support.TransactionSynchronization.beforeCompletion.

Invoked before transaction commit/rollback.

public int
getOrder()

Overrides default org.springframework.transaction.support.TransactionSynchronization.getOrder.

Return the execution order for this transaction synchronization.

public void
public void
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

connectionHolderback to summary
private final ConnectionHolder connectionHolder
dataSourceback to summary
private final DataSource dataSource
holderActiveback to summary
private boolean holderActive
orderback to summary
private final int order

Constructor Detail

ConnectionSynchronizationback to summary
public ConnectionSynchronization(ConnectionHolder connectionHolder, DataSource dataSource)

Method Detail

afterCompletionback to summary
public void afterCompletion(int status)

Overrides default org.springframework.transaction.support.TransactionSynchronization.afterCompletion.

Doc from org.springframework.transaction.support.TransactionSynchronization.afterCompletion.

Invoked after transaction commit/rollback. Can perform resource cleanup after transaction completion.

Note

The transaction will have been committed or rolled back already, but the transactional resources might still be active and accessible. As a consequence, any data access code triggered at this point will still "participate" in the original transaction, allowing to perform some cleanup (with no commit following anymore!), unless it explicitly declares that it needs to run in a separate transaction. Hence: Use PROPAGATION_REQUIRES_NEW for any transactional operation that is called from here.

Parameters
status:int

completion status according to the STATUS_* constants

Annotations
@Override
beforeCompletionback to summary
public void beforeCompletion()

Overrides default org.springframework.transaction.support.TransactionSynchronization.beforeCompletion.

Doc from org.springframework.transaction.support.TransactionSynchronization.beforeCompletion.

Invoked before transaction commit/rollback. Can perform resource cleanup before transaction completion.

This method will be invoked after beforeCommit, even when beforeCommit threw an exception. This callback allows for closing resources before transaction completion, for any outcome.

Annotations
@Override
getOrderback to summary
public int getOrder()

Overrides default org.springframework.transaction.support.TransactionSynchronization.getOrder.

Doc from org.springframework.transaction.support.TransactionSynchronization.getOrder.

Return the execution order for this transaction synchronization.

Default is Ordered#LOWEST_PRECEDENCE.

Returns:int

Doc from org.springframework.core.Ordered.getOrder.

the order value

Annotations
@Override
resumeback to summary
public void resume()

Overrides default org.springframework.transaction.support.TransactionSynchronization.resume.

Doc from org.springframework.transaction.support.TransactionSynchronization.resume.

Resume this synchronization. Supposed to rebind resources to TransactionSynchronizationManager if managing any.

Annotations
@Override
suspendback to summary
public void suspend()

Overrides default org.springframework.transaction.support.TransactionSynchronization.suspend.

Doc from org.springframework.transaction.support.TransactionSynchronization.suspend.

Suspend this synchronization. Supposed to unbind resources from TransactionSynchronizationManager if managing any.

Annotations
@Override