com.iplanet.jato
Interface SQLConnectionManager

All Known Implementing Classes:
SQLConnectionManagerBase

public interface SQLConnectionManager

A factory for obtaining JDBC Connection objects in a standard way throughout JATO. The purpose of this class is to make the task of obtaining a JDBC Connection object easier for developers and the built-in JATO objects. The basic usage of the SQLConnectionManager is that callers ask it for a JDBC Connection using what's called a datasource name . This datasource name is an arbitrary, logical name for a pre-configured database connection. This class also standardizes this task regardless of the technique used to obtain the connection. Finally, the class provides a level of indirection that can be useful when switching between development, test, and deployment environments.

In standard Java applications, JDBC Connections are normally obtained via a call to the java.sql.DriverManager. Callers provide a JDBC URL specific to the database they wish to use, and the DriverManager matches an available JDBC driver with the specified URL, obtains a database connection from the driver, and returns it to the caller. The caller then uses the connection as long as it wishes before closing it.

In Web applications, the use of the DriverManager is highly inefficient because it requires a new database connection to be opened and initialized for each application request that requires database access. However, the JDBC 2.0 Standard Extension (the javax.sql package) defines a standard J2EE mechanism for database connection pooling. This allows connections to be reused over multiple requests, and avoids the inefficiency of repeatedly opening connections to the database.

The JDBC 2.0 Standard Extension provides a JNDI mechanism through which Web application developers can obtain a pooled JDBC Connection object. This mechanism consists of allocating a JNDI context and asking it for a datasource by name. This name, also called a datasource name, is of a standard form which begins with "jdbc/". The idea is that instead of embedding JDBC URLs directly in an application, the application deployer pre-configures a JDBC datasource with all the necessary information—host, protocol, username, password, etc.—and makes it available under a logical datasource name that begins with the prefix "jdbc/". Application developers only reference this logical datasource name, which they assume will be mapped appropriately in whatever container the application is deployed.

Unfortunately, not all containers provide this datasource mechanism, and/or they impose certain limitations on the datasource name. For example, one container may allow arbitrary names after the standard "jdbc/" prefix, where another container may require the addition of the application context name after the prefix. This might not be a problem with an application developed and deployed in the same container; however, it's fairly common for an application to be developed and deployed under different containers, making this situation a serious problem.

This is where SQLConnectionManager seeks to provide assistance. The base implementation of SQLConnectionManager in SQLConnectionManagerBase has its own datasource mapping mechanism, which allows the JATO developer to use truly arbitrary datasource names in their application, yet still allow these names to be operational within any given container. Additionally, the SQLConnectionManager allows mapping of datasource names to either JNDI datasource names or plain JDBC URLs. This feature allows a JATO application to run in a container that doesn't support the JDBC 2.0 Standard Extension, albeit without the benefit of connection pooling.

Version:
JATO/1.2.2 $Id: SQLConnectionManager.java,v 1.12 2002/03/16 03:26:28 todd Exp $
See Also:
RequestContext, SQLConnectionManagerBase

Method Summary
 java.sql.Connection getConnection(java.lang.String dataSource)
          Return a JDBC Connection for the specified datasource
 java.sql.Connection getConnection(java.lang.String dataSource, java.lang.String user, java.lang.String password)
          Return a JDBC Connection from the specified datasource with the provided user and password
 

Method Detail

getConnection

public java.sql.Connection getConnection(java.lang.String dataSource)
                                  throws java.sql.SQLException
Return a JDBC Connection for the specified datasource
Parameters:
dataSource - The desired datasource name. This parameter may either be the actual JNDI lookup string or an arbitrary logical name.
Returns:
The JDBC connection corresponding to the specified datasource
Throws:
java.sql.SQLException - Thrown if there is a problem getting a connection

getConnection

public java.sql.Connection getConnection(java.lang.String dataSource,
                                         java.lang.String user,
                                         java.lang.String password)
                                  throws java.sql.SQLException
Return a JDBC Connection from the specified datasource with the provided user and password
Parameters:
dataSource - The desired datasource name. This parameter may either be the actual JNDI lookup string or an arbitrary logical name.
user - The user ID for the desired connection
password - The password for the desired connection
Returns:
The JDBC connection corresponding to the specified datasource
Throws:
java.sql.SQLException - Thrown if there is a problem getting a connection