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 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: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $

Author:

Ted Husted

See Also:

ConnectionServlet, PoolmanAdaptor

Field Summary

static String	DATA_SOURCE_KEY The default DataSource name.
protected static DataSource	datasource Field to store singleton reference to default datasource.
static 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

Connection	getConnection() Returns a JDBC connection from the default resource.
Connection	getConnection(String key) Returns a JDBC connection from a connection pool or other named resource, to be used and closed promptly.
protected DataSource	getDataSource(String key) Return datasource using JNDI lookup.
String	getKey() Return the attribute under which our datasource is stored.
protected 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(String key) The attribute under which our datasource is stored.
protected void	setMessage(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 String DATA_SOURCE_KEY

The default DataSource name.

See Also:

Constant Field Values

JNDI_CONTEXT_KEY

public static final String JNDI_CONTEXT_KEY

The default JNDI context for applications.

See Also:

Constant Field Values

datasource

protected static 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 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(String message)

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

Parameters:

Message - The message for an exception if pool returns null

getKey

public 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(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 DataSource getDataSource(String key)
                            throws 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:

SQLException

getConnection

public Connection getConnection()
                         throws 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:

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

getConnection

public Connection getConnection(String key)
                         throws 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.

Parameters:

resource - An attribute name for the resource to use for this connection or null to call getResource()

Returns:

JDBC connection from resource layer.

Throws:

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

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.