org.springframework.jdbc.datasource
Class DataSourceUtils

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

public abstract class DataSourceUtils

extends java.lang.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 BeanFactory resp. an ApplicationContext. 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 give the DataSource bean reference to other beans. Switching to another DataSource is just a matter of configuration then: You can even replace the definition of the FactoryBean with a non-JNDI DataSource!

Version:

$Id: DataSourceUtils.java,v 1.9 2004/03/18 02:46:05 trisberg Exp $

Author:

Rod Johnson, Juergen Hoeller

See Also:

DataSourceTransactionManager, JndiObjectFactoryBean

Constructor Summary

DataSourceUtils()

Method Summary

static void	applyTransactionTimeout(java.sql.Statement stmt, javax.sql.DataSource ds) Apply the current transaction timeout, if any, to the given JDBC Statement object.
static void	closeConnectionIfNecessary(java.sql.Connection con, javax.sql.DataSource ds) Close the given connection if necessary, i.e.
static java.sql.Connection	getConnection(javax.sql.DataSource ds) Get a connection from the given DataSource.
static java.sql.Connection	getConnection(javax.sql.DataSource ds, boolean allowSynchronization)
static javax.sql.DataSource	getDataSourceFromJndi(java.lang.String jndiName) Look up the specified DataSource in JNDI, assuming that the lookup occurs in a J2EE container, i.e.
static javax.sql.DataSource	getDataSourceFromJndi(java.lang.String jndiName, boolean resourceRef) Look up the specified DataSource in JNDI, explicitly specifying if the lookup occurs in a J2EE container.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataSourceUtils

public DataSourceUtils()

Method Detail

getDataSourceFromJndi

public static javax.sql.DataSource getDataSourceFromJndi(java.lang.String jndiName)
                                                  throws CannotGetJdbcConnectionException

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)

getDataSourceFromJndi

public static javax.sql.DataSource getDataSourceFromJndi(java.lang.String jndiName,
                                                         boolean resourceRef)
                                                  throws CannotGetJdbcConnectionException

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

getConnection

public static java.sql.Connection getConnection(javax.sql.DataSource ds)
                                         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 respective 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:

ds - 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 java.sql.Connection getConnection(javax.sql.DataSource ds,
                                                boolean allowSynchronization)
                                         throws CannotGetJdbcConnectionException

Throws:

CannotGetJdbcConnectionException

applyTransactionTimeout

public static void applyTransactionTimeout(java.sql.Statement stmt,
                                           javax.sql.DataSource ds)
                                    throws java.sql.SQLException

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

Parameters:

stmt - the JDBC Statement object

ds - DataSource that the connection came from

Throws:

java.sql.SQLException

closeConnectionIfNecessary

public static void closeConnectionIfNecessary(java.sql.Connection con,
                                              javax.sql.DataSource ds)
                                       throws CannotCloseJdbcConnectionException

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)

ds - DataSource that the connection came from

Throws:

CannotCloseJdbcConnectionException - if the attempt to close the Connection failed

See Also:

SmartDataSource.shouldClose(java.sql.Connection)