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 to obtain connections from JNDI and close connections if necessary. Has support for thread-bound connections, e.g. for use with DataSourceTransactionManager.

Note: The getDataSourceFromJndi methods are targetted at applications that do not use a Spring BeanFactory. With the latter, it is preferable to preconfigure your beans or even JdbcTemplate instances in the factory: JndiObjectFactoryBean can be used to fetch a DataSource from JNDI and pass the DataSource bean reference to other beans. Switching to another DataSource is just a matter of configuration then: For example, you can replace the definition of the JndiObjectFactoryBean with a local DataSource (like a Commons DBCP BasicDataSource).

Author:

Rod Johnson, Juergen Hoeller

See Also:

getDataSourceFromJndi(java.lang.String), JndiObjectFactoryBean, getConnection(javax.sql.DataSource), DataSourceTransactionManager

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) 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.
protected static void	doCloseConnectionIfNecessary(Connection con, DataSource dataSource) Actually close a JDBC Connection for the given DataSource.
protected static Connection	doGetConnection(DataSource dataSource, boolean allowSynchronization) Actually get a JDBC Connection for the given DataSource.
static Connection	getConnection(DataSource dataSource) Get a Connection from the given DataSource.
static Connection	getConnection(DataSource dataSource, boolean allowSynchronization) Get a Connection from the given DataSource.
static DataSource	getDataSourceFromJndi(String jndiName) Deprecated. in favor of managing a DataSource via dependency injection, i.e. using a JndiObjectFactoryBean for a JNDI DataSource and pass a bean reference to a setDataSource(DataSource) method or the like
static DataSource	getDataSourceFromJndi(String jndiName, boolean resourceRef) Deprecated. in favor of managing a DataSource via dependency injection, i.e. using a JndiObjectFactoryBean for a JNDI DataSource and pass a bean reference to a setDataSource(DataSource) method or the like
static Integer	prepareConnectionForTransaction(Connection con, TransactionDefinition definition) Prepare the given Connection with the given transaction semantics.
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

getDataSourceFromJndi

public static DataSource getDataSourceFromJndi(String jndiName)
                                        throws CannotGetJdbcConnectionException

Deprecated. in favor of managing a DataSource via dependency injection, i.e. using a JndiObjectFactoryBean for a JNDI DataSource and pass a bean reference to a setDataSource(DataSource) method or the like

Look up the specified DataSource in JNDI, assuming that the lookup occurs in a J2EE container, i.e. adding the prefix "java:comp/env/" to the JNDI name if it doesn't already contain it.

Use getDataSourceFromJndi(jndiName,false) in case of a custom JNDI name.

Parameters:

jndiName - jndiName of the DataSource

Returns:

the DataSource

Throws:

CannotGetJdbcConnectionException - if the data source cannot be located

See Also:

getDataSourceFromJndi(String, boolean), JndiObjectFactoryBean

getDataSourceFromJndi

public static DataSource getDataSourceFromJndi(String jndiName,
                                               boolean resourceRef)
                                        throws CannotGetJdbcConnectionException

Deprecated. in favor of managing a DataSource via dependency injection, i.e. using a JndiObjectFactoryBean for a JNDI DataSource and pass a bean reference to a setDataSource(DataSource) method or the like

Look up the specified DataSource in JNDI, explicitly specifying if the lookup occurs in a J2EE container.

Parameters:

jndiName - jndiName of the DataSource

resourceRef - if the lookup occurs in a J2EE container, i.e. if the prefix "java:comp/env/" needs to be added if the JNDI name doesn't already contain it.

Returns:

the DataSource

Throws:

CannotGetJdbcConnectionException - if the data source cannot be located

See Also:

JndiObjectFactoryBean

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 this DataSource

Throws:

CannotGetJdbcConnectionException - if the attempt to get a Connection failed

See Also:

TransactionSynchronizationManager, DataSourceTransactionManager

getConnection

public static Connection getConnection(DataSource dataSource,
                                       boolean allowSynchronization)
                                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

allowSynchronization - if a new JDBC Connection is supposed to be registered with transaction synchronization (if synchronization is active). This will always be true for typical data access code.

Returns:

a JDBC Connection from this DataSource

Throws:

CannotGetJdbcConnectionException - if the attempt to get a Connection failed

See Also:

doGetConnection(javax.sql.DataSource, boolean), TransactionSynchronizationManager, DataSourceTransactionManager

doGetConnection

protected static Connection doGetConnection(DataSource dataSource,
                                            boolean allowSynchronization)
                                     throws SQLException

Actually get a JDBC Connection for the given DataSource. Same as getConnection, but throwing the original SQLException.

Directly accessed by TransactionAwareDataSourceProxy.

Parameters:

dataSource - DataSource to get Connection from

allowSynchronization - if a new JDBC Connection is supposed to be registered with transaction synchronization (if synchronization is active). This will always be true for typical data access code.

Returns:

a JDBC Connection from this DataSource

Throws:

SQLException - if thrown by JDBC methods

See Also:

getConnection(DataSource, boolean), 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)

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.

Parameters:

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

dataSource - DataSource that the Connection came from

See Also:

SmartDataSource.shouldClose(java.sql.Connection)

doCloseConnectionIfNecessary

protected static void doCloseConnectionIfNecessary(Connection con,
                                                   DataSource dataSource)
                                            throws SQLException

Actually close a JDBC Connection for the given DataSource. Same as closeConnectionIfNecessary, 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

Throws:

SQLException - if thrown by JDBC methods

See Also:

closeConnectionIfNecessary(java.sql.Connection, javax.sql.DataSource), TransactionAwareDataSourceProxy