com.buzzsurf.sql
Class DataSourceManager

java.lang.Object
  com.buzzsurf.sql.DataSourceManager

public final class DataSourceManager
extends java.lang.Object

DataSource Manager handles loading javax.sql.DataSource objects from a JNDI naming context. This is done intelligently by examining any existing naming context. All database connections obtained automatically by BuzzSQL come from DataSource bound in a JNDI naming context

Note: DataSource Manager does not need to be used exclusively with BuzzSQL objects. It can be a valuable stand-alone tool for obtaining database connections. This is particularly true in a J2SE environment where no JNDI naming context is available. DataSource Manager will create a naming context for you and load and bind your dataSources conveniently.

Author:

Paul Cowan (www.buzzsurf.com/sql)

See Also:

initialize(), isInitialized(), initializationFailed()

Field Summary

static java.lang.String	CONFIG_RESOURCE_NAME
static java.lang.String	DEFAULT_DS_NAME

Method Summary

static java.sql.Connection	getConnection() Get a java.sql.Connection object from the default dataSource.
static java.sql.Connection	getConnection(java.lang.String dataSourceName) DataSources are made available to BuzzSQL using a name that is based on the JNDI path.
static java.lang.String	getDefaultDataSourceName() Get the name of the default dataSource
static boolean	initializationFailed() Check the status if initialization.
static boolean	initialize() DataSource Manager uses "lazy initialization" to create/lookup/load dataSource from the JNDI naming context.
static boolean	isInitialized() Check the status if initialization.
static java.util.Collection<java.lang.String>	listDataSourceNames() Get a collection of all available dataSource names
static void	releaseConnection(java.sql.Connection con) Release the JDBC connection
static void	releaseConnection(java.lang.String dataSourceName, java.sql.Connection con) Release the JDBC connection to the specified dataSource

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_DS_NAME

public static final java.lang.String DEFAULT_DS_NAME

See Also:

Constant Field Values

CONFIG_RESOURCE_NAME

public static final java.lang.String CONFIG_RESOURCE_NAME

See Also:

Constant Field Values

Method Detail

initialize

public static boolean initialize()

DataSource Manager uses "lazy initialization" to create/lookup/load dataSource from the JNDI naming context. This can caused a problem in some cases, as the first request may be delayed as resources are loaded. To prevent this, a single simple call to the static method DataSourceManager.initialize() will result in pre-loading of all dataSources. You can query DataSource Manager on the status of initialization using the DataSourceManager.isInitialized() and DataSourceManager.initializationFailed() methods. These methods allow your application is determine if DataSource Manager is correctly initialized. All errors during initialization will be written to the common logging system. See BuzzSQL Logging for more information on DataSource Manager logging.

isInitialized

public static boolean isInitialized()

Check the status if initialization.

Returns:

true if DataSourceManager is initialized correctly.

initializationFailed

public static boolean initializationFailed()

Check the status if initialization. You can query the initialization state of DataSource Manager by calling DataSouceManager.initializationFailed(). initializationFailed will return true if a FATAL error was detected.

Returns:

true if there was an error detected during initialization.

getDefaultDataSourceName

public static java.lang.String getDefaultDataSourceName()

Get the name of the default dataSource

Returns:

The default dataSource name

getConnection

public static java.sql.Connection getConnection()
                                         throws java.sql.SQLException

Get a java.sql.Connection object from the default dataSource.

Returns:

The JDBC connection

Throws:

java.sql.SQLException - If DataSourceManager failed to initialize correctly or the DataSource was unable to connect to the database.

getConnection

public static java.sql.Connection getConnection(java.lang.String dataSourceName)
                                         throws java.sql.SQLException

DataSources are made available to BuzzSQL using a name that is based on the JNDI path. For example, a dataSource bound in your JNDI naming context at java:comp/env/jdbc/testDB would be named testDB, since java:comp/env/jdbc/ is the default root namespace search path.

All dataSources found under the root namespace are made available in DataSource Manager. This can create a problem if you have multiple dataSource bound in JNDI; the default dataSource is non-deterministic when there are multiple dataSources available. To fix this problem, you must either always specify a dataSourceName in the constructor of your BuzzSQL objects, call setDataSourceName(String) on your BuzzSQL objects, or include the buzzsql.properties file with the defaultDataSourceName property.

Parameters:

dataSourceName - The name of the dataSource as loaded by DataSourceManager based on the bound JNDI name.

Returns:

The JDBC connection

Throws:

java.sql.SQLException - If DataSourceManager failed to initialize correctly or the DataSource was unable to connect to the database.

releaseConnection

public static void releaseConnection(java.sql.Connection con)

Release the JDBC connection

Parameters:

con -

releaseConnection

public static void releaseConnection(java.lang.String dataSourceName,
                                     java.sql.Connection con)

Release the JDBC connection to the specified dataSource

Parameters:

dataSourceName -

con -

listDataSourceNames

public static java.util.Collection<java.lang.String> listDataSourceNames()

Get a collection of all available dataSource names

Returns:

An unmodifiable collection of Strings