org.pajes.db
Class ConnectionManager

java.lang.Object
  org.pajes.servlet.PajesContextListener
      org.pajes.db.ConnectionManager

All Implemented Interfaces:

java.util.EventListener, javax.servlet.ServletContextListener

public class ConnectionManager
extends PajesContextListener

Manages named connection pools and the retrieval of database connections from them.

The connection manager maintains a cache of one or more connection pools, each registered under a unique pool name.

The ConnectionManager should be defined as a <listener> in the web application deployment descriptor.

See Also:

ConnectionPool

Field Summary

static java.lang.String

DB_XML The path of the database.xml file, relative to the servlet context root.

Constructor Summary

ConnectionManager()
Creates a new ConnectionManager.

Method Summary

void	contextDestroyed(javax.servlet.ServletContextEvent sce) Notification that the servlet context is about to be shut down.
void	contextInitialized(javax.servlet.ServletContextEvent sce) Notification that the web application is ready to process requests.
ConnectionPool	createPool(ConnectionPoolDefinition defn) Creates and registers a new connection pool.
protected ConnectionPool	createPool(java.lang.String jdbcDriverClass, java.lang.String dbServerURL, int numInitialConnections, int maxConnections, java.lang.String user, java.lang.String password, long connectionTimeout, long retryInterval) Creates a new connection pool.
ConnectionPool	createPool(java.lang.String poolName, java.lang.String jdbcDriverClass, java.lang.String dbServerURL, int numInitialConnections, int maxConnections, java.lang.String user, java.lang.String password, long connectionTimeout, long retryInterval) Creates and registers a new connection pool.
void	destroyPool(java.lang.String poolName) Calls the specified pools destroy() method, and removes the pool from the list of available pools.
protected ConnectionPoolConfiguration	getConnectionPoolConfiguration(javax.servlet.ServletContext context) Returns the ConnectionPoolConfiguration object.
java.lang.String	getLinkedPool(java.lang.String poolName) Returns the pool to which the nominated pool is linked, or null if the pool is not managed by this instance, or the pool name does not exist.
ConnectionPool	getPool() Returns the default connection pool.
ConnectionPool	getPool(java.lang.String poolName) Return a connection pool with the specified name.
java.util.Enumeration<java.lang.String>	getPoolNames() Get the names of the registered connection pools.
protected void	init(javax.servlet.ServletContext context) Called by contextInitialized(javax.servlet.ServletContextEvent).
void	registerPool(java.lang.String poolName, ConnectionPool connectionPool, java.lang.String linkedPoolName) Registers a connection pool under a specified name with this connection manager, and then initialises it.
boolean	releaseConnections(java.lang.Thread thread) Release all connections that may have been left open by a Thread.
void	removePool(java.lang.String poolName) Removes the pool from management by this connection manager.
void	setDefaultPool(java.lang.String poolName) Sets the default connection pool.
void	shutdown() Destroys all registered pools and shuts down the manager.
java.lang.String	toString() Over-rides toString() from Object.

Methods inherited from class org.pajes.servlet.PajesContextListener

getContext

Methods inherited from class java.lang.Object

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

Field Detail

DB_XML

public static final java.lang.String DB_XML

The path of the database.xml file, relative to the servlet context root.

See Also:

Constant Field Values

Constructor Detail

ConnectionManager

public ConnectionManager()

Creates a new ConnectionManager.

Method Detail

contextDestroyed

public void contextDestroyed(javax.servlet.ServletContextEvent sce)

Notification that the servlet context is about to be shut down.

Specified by:

contextDestroyed in interface javax.servlet.ServletContextListener

Overrides:

contextDestroyed in class PajesContextListener

Parameters:

sce - the event class for notifications about changes to the servlet context of a web application.

contextInitialized

public void contextInitialized(javax.servlet.ServletContextEvent sce)

Notification that the web application is ready to process requests.

Sub-classes that over-ride this MUST call super.contextInitialized(sce) to complete PAJES initialisation before performing any application-specific processing.

Specified by:

contextInitialized in interface javax.servlet.ServletContextListener

Overrides:

contextInitialized in class PajesContextListener

Parameters:

sce - the event class for notifications about changes to the servlet context of a web application.

createPool

public ConnectionPool createPool(ConnectionPoolDefinition defn)
                          throws java.lang.ClassNotFoundException,
                                 java.sql.SQLException

Creates and registers a new connection pool.

Parameters:

defn - The ConnectionPoolDefinition object.

Returns:

the newly created connection pool

Throws:

java.lang.ClassNotFoundException - if the JDBC driver class could not be found.

java.sql.SQLException - if an error occurs creating the connection pool.

createPool

public ConnectionPool createPool(java.lang.String poolName,
                                 java.lang.String jdbcDriverClass,
                                 java.lang.String dbServerURL,
                                 int numInitialConnections,
                                 int maxConnections,
                                 java.lang.String user,
                                 java.lang.String password,
                                 long connectionTimeout,
                                 long retryInterval)
                          throws java.lang.ClassNotFoundException,
                                 java.sql.SQLException

Creates and registers a new connection pool.

Parameters:

poolName - The name to register the connection pool under

jdbcDriverClass - The JDBC driver class name

dbServerURL - The address of a JDBC data source

numInitialConnections - The number of connections to initially open

maxConnections - The maximum number of connections to open

user - The database userid

password - The database password

connectionTimeout - The number of milliseconds to wait for a free connection to become available

retryInterval - The number of milliseconds between checking for a free connection

Returns:

the newly created connection pool

Throws:

java.lang.ClassNotFoundException - if the JDBC driver class could not be found.

java.sql.SQLException - if an error occurs creating the connection pool.

destroyPool

public void destroyPool(java.lang.String poolName)
                 throws java.sql.SQLException

Calls the specified pools destroy() method, and removes the pool from the list of available pools.

Parameters:

poolName - the name of the connection pool to destroy.

Throws:

java.sql.SQLException - if an error occurs accessing the database.

ConnectionPoolException - if the specified pool was not found.

getLinkedPool

public java.lang.String getLinkedPool(java.lang.String poolName)

Returns the pool to which the nominated pool is linked, or null if the pool is not managed by this instance, or the pool name does not exist.

Parameters:

poolName - the name of the pool for which the linked pool is to be retrieved

Returns:

the name of the linked connection pool.

getPool

public ConnectionPool getPool()

Returns the default connection pool.

Returns:

the specified connection pool.

getPool

public ConnectionPool getPool(java.lang.String poolName)

Return a connection pool with the specified name.

Parameters:

poolName - the name of the connection pool to get.

Returns:

the specified connection pool.

Throws:

ConnectionPoolException - if the specified pool was not found.

getPoolNames

public java.util.Enumeration<java.lang.String> getPoolNames()

Get the names of the registered connection pools.

Returns:

an Enumeration of the pool names.

registerPool

public void registerPool(java.lang.String poolName,
                         ConnectionPool connectionPool,
                         java.lang.String linkedPoolName)

Registers a connection pool under a specified name with this connection manager, and then initialises it.

Parameters:

poolName - the name to register the connection pool under.

connectionPool - the connection pool to be registered.

linkedPoolName - the name of the pool to which this pool is linked. If null, the pool is not linked.

Throws:

ConnectionPoolException - if the specified pool already exists.

See Also:

ConnectionPool

releaseConnections

public boolean releaseConnections(java.lang.Thread thread)

Release all connections that may have been left open by a Thread.

Parameters:

thread - the Thread object that may have opened a connection.

Returns:

true if any connections were found to be released.

removePool

public void removePool(java.lang.String poolName)

Removes the pool from management by this connection manager.

Parameters:

poolName - the connection pool to remove

setDefaultPool

public void setDefaultPool(java.lang.String poolName)

Sets the default connection pool. If not explicitly defined, the first pool registered is the default pool.

Parameters:

poolName - the default connection pool name

shutdown

public void shutdown()

Destroys all registered pools and shuts down the manager.

toString

public java.lang.String toString()

Over-rides toString() from Object.

Overrides:

toString in class java.lang.Object

Returns:

the description of the Connection Pool Manager.

createPool

protected ConnectionPool createPool(java.lang.String jdbcDriverClass,
                                    java.lang.String dbServerURL,
                                    int numInitialConnections,
                                    int maxConnections,
                                    java.lang.String user,
                                    java.lang.String password,
                                    long connectionTimeout,
                                    long retryInterval)
                             throws java.lang.ClassNotFoundException,
                                    java.sql.SQLException

Creates a new connection pool.

Parameters:

jdbcDriverClass - The JDBC driver class name

dbServerURL - The address of a JDBC data source

numInitialConnections - The number of connections to initially open

maxConnections - The maximum number of connections to open

user - The database userid

password - The database password

connectionTimeout - The number of milliseconds to wait for a free connection to become available

retryInterval - The number of milliseconds between checking for a free connection

Returns:

the newly created connection pool

Throws:

java.lang.ClassNotFoundException - if the JDBC driver class could not be found.

java.sql.SQLException - if an error occurs creating the connection pool.

getConnectionPoolConfiguration

protected ConnectionPoolConfiguration getConnectionPoolConfiguration(javax.servlet.ServletContext context)
                                                              throws java.io.IOException

Returns the ConnectionPoolConfiguration object.

Parameters:

context - the servlet context.

Returns:

the ConnectionPoolConfiguration object, or null if no WEB-INF/database.xml file can be located.

Throws:

java.io.IOException - if an error occurs reading the deployment descriptor.

init

protected void init(javax.servlet.ServletContext context)

Called by contextInitialized(javax.servlet.ServletContextEvent).

Sub-classes that over-ride this MUST call super.init(context) to complete PAJES initialisation.

Parameters:

context - the servlet context.