org.apache.commons.scaffold.sql
Class ConnectionAdaptor

java.lang.Object
  org.apache.commons.scaffold.sql.ConnectionAdaptor

Direct Known Subclasses:

MockAdaptor, PoolmanAdaptor, ServletAdaptor

public class ConnectionAdaptor

extends java.lang.Object

Base class for SQL connection adaptors. May be used as-is or subclassed.

This object does not provide any type of connection pooling. It simply provides a standard means for obtaining a connection whatever connection pool your application needs. Scaffold classes in the SQL package call this object internally.

To use as-is, a DataSource compliant connection pool must be available as "DATA_SOURCE" via JNDI. A subclass can locate the pool under any name by any means necessary.

A ConnectionAdaptor can be instantiated once at start-up, either from main() or via a servlet, like the Scaffold ConnectionServlet. Objects needing a connection can then call the static method ConnectionAdaptor.getPool().getConnection().

Most implementations will expect callers to use and close the connections promptly, since they would usually be part of a pool.

Subclasses can provide their own resource name or getConnection() method, and a new constructor to set the protected pool field to their own instance. See PoolmanAdaptor for an example.

Version:

$Revision: 1.5 $ $Date: 2004/03/21 21:10:27 $

See Also:

ConnectionServlet, PoolmanAdaptor

Field Summary

static java.lang.String	DATA_SOURCE_KEY The default DataSource name.
protected static javax.sql.DataSource	datasource Field to store singleton reference to default datasource.
static java.lang.String	JNDI_CONTEXT_KEY The default JNDI context for applications.
protected static ConnectionAdaptor	pool Field to store singleton reference to adaptor pool.

Constructor Summary

ConnectionAdaptor()

Method Summary

java.sql.Connection	getConnection() Returns a JDBC connection from the default resource.
java.sql.Connection	getConnection(java.lang.String key) Returns a JDBC connection from a connection pool or other named resource, to be used and closed promptly.
protected javax.sql.DataSource	getDataSource(java.lang.String key) Return datasource using JNDI lookup.
java.lang.String	getKey() Return the attribute under which our datasource is stored.
protected java.lang.String	getMessage() Return a message for an exception if pool returns null.
static ConnectionAdaptor	getPool() Return adaptor instance to use in acquiring connection.
void	setKey(java.lang.String key) The attribute under which our datasource is stored.
protected void	setMessage(java.lang.String message) Set a message for an exception if pool returns null.

Methods inherited from class java.lang.Object

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

Field Detail

DATA_SOURCE_KEY

public static final java.lang.String DATA_SOURCE_KEY

The default DataSource name.

See Also:

Constant Field Values

JNDI_CONTEXT_KEY

public static final java.lang.String JNDI_CONTEXT_KEY

The default JNDI context for applications.

See Also:

Constant Field Values

datasource

protected static javax.sql.DataSource datasource

Field to store singleton reference to default datasource. TODO: Add Map to store reference to other datasoruces.

pool

protected static ConnectionAdaptor pool

Field to store singleton reference to adaptor pool. This would usually be private for a singleton, but adaptor subclasses may set the pool upon initialization.

if (null==pool) set pool = this.

Constructor Detail

ConnectionAdaptor

public ConnectionAdaptor()

Method Detail

getMessage

protected java.lang.String getMessage()

Return a message for an exception if pool returns null.

Returns:

Message for an exception if pool returns null

setMessage

protected void setMessage(java.lang.String message)

Set a message for an exception if pool returns null. Adaptor subclasses can call this from their constructor.

getKey

public java.lang.String getKey()

Return the attribute under which our datasource is stored. Subclasses may override this method to provide a different key, or set a new key at construction.

setKey

public void setKey(java.lang.String key)

The attribute under which our datasource is stored. Adaptor subclasses can call this method from a constructor to change the default resource name.

getDataSource

protected javax.sql.DataSource getDataSource(java.lang.String key)
                                      throws java.sql.SQLException

Return datasource using JNDI lookup. Subclasses may override this method to provide other means of obtaining a datasource reference.

Parameters:

key - The attribute name for the resource. If null is passed, null is returned.

Returns:

null or the datasource object related to "key" TODO: Add cache to store references to the datasources by key.

Throws:

java.sql.SQLException

getConnection

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

Returns a JDBC connection from the default resource. Calls getDatasource to return the resource associated with the default attribute name [getKey()].

The default datasource object is cached and reused in subsequent calls.

Returns:

JDBC connection from resource layer.

Throws:

java.sql.SQLException - on SQL or other errors. May wrap other exceptions depending on implementation. Will not return null.

getConnection

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

Returns a JDBC connection from a connection pool or other named resource, to be used and closed promptly.

Default implementation uses JNDI to lookup the resource named by getResource() ["DATASOURCE"]. Will not return null.

Returns:

JDBC connection from resource layer.

Throws:

java.sql.SQLException - on SQL or other errors. May wrap other exceptions depending on implementation.

java.sql.SQLException - On any SQL error or if pool returns null

getPool

public static ConnectionAdaptor getPool()

Return adaptor instance to use in acquiring connection.

This is the main entry method to the object. Client's should call:
Adaptor.getPool().getConnection() to acquire a connection from the default pool.