edu.ucsb.adl.bucket99
Class ConnectionPool

java.lang.Object
  |
  +--edu.ucsb.adl.bucket99.ConnectionPool

public final class ConnectionPool

extends java.lang.Object

A pool of database connections. Connections are held by the pool and can be reserved for use. The number of connections in the pool fluctuates, but is kept within specified bounds. Connections are created on demand; connections that have been idle for a specified period of time are closed by a separate "reaper" thread. Connections are tested before they are reserved; a single attempt is made to replace a bad connection.

This class is multithread-safe.

Version:

$Header: /export/home/gjanee/bucket99/edu/ucsb/adl/bucket99/RCS/ConnectionPool.java,v 1.5 2004/09/13 23:55:36 gjanee Exp $

$Log: ConnectionPool.java,v $ Revision 1.5 2004/09/13 23:55:36 gjanee
Improved an error message.

Revision 1.4 2004/03/17 19:36:06 gjanee
Reworked the handling of the pool's status. The pool's status is now stored as a separate object, with separate synchronization, to allow the status to be obtained even if the pool itself is hung due to the database being hung.

Revision 1.3 2002/09/26 15:35:08 gjanee
Added support for a separate Java properties file containing database connection properties.

Revision 1.2 2001/01/05 00:07:38 gjanee
Bug fix: all threads waiting on the connection pool are now awakened when an exception is thrown by reserveConnection. This fix solves a rare problem that occurs when the database fails while there are more threads waiting on the connection pool than there are connections. In this situation, as connections are returned to the pool, threads, equal in number to the number of connections, attempt to reserve a connection and then receive an exception. Before this fix, the remaining waiting threads were left waiting forever, but now they, too, receive an exception.

Revision 1.1 2000/04/27 21:09:26 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

Nested Class Summary

static class

ConnectionPool.Status Describes the status of a connection pool.

Constructor Summary

ConnectionPool(java.lang.String connectionURL, java.util.Properties connectionProperties, java.lang.String testQuery, int minimumConnections, int maximumConnections, long cycleTime, long lifetime)
Creates a ConnectionPool.

Method Summary

void	destroy() Destroys the pool.
ConnectionPool.Status	getStatus() Returns the status of the pool.
java.sql.Connection	reserveConnection() Reserves a connection in the pool.
void	returnConnection(java.sql.Connection c) Returns a previously-reserved connection to the pool.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionPool

public ConnectionPool(java.lang.String connectionURL,
                      java.util.Properties connectionProperties,
                      java.lang.String testQuery,
                      int minimumConnections,
                      int maximumConnections,
                      long cycleTime,
                      long lifetime)

Creates a ConnectionPool.

Parameters:

connectionURL - The connection URL.

connectionProperties - A property list of database connection properties, or null. The pool takes ownership of this object.

testQuery - The query used to test connections, e.g., "select 1 from dual".

minimumConnections - The minimum number of connections to attempt to maintain in the pool.

maximumConnections - The maximum size of the pool.

cycleTime - The duration of the connection reaper's cycle in milliseconds.

lifetime - The lifetime of connections in milliseconds.

Throws:

java.lang.NullPointerException - If connectionURL or testQuery are null.

java.lang.IllegalArgumentException - If minimumConnections, cycleTime, or lifetime are negative, or if maximumConnections is nonpositive or less than minimumConnections.

Method Detail

getStatus

public ConnectionPool.Status getStatus()

Returns the status of the pool.

Returns:

The status.

reserveConnection

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

Reserves a connection in the pool. The calling thread may be forced to wait for a connection to become available. The connection should be returned to the pool, still open, before the pool is destroyed.

Returns:

A connection.

Throws:

java.sql.SQLException - If a new connection cannot be opened.

returnConnection

public void returnConnection(java.sql.Connection c)

Returns a previously-reserved connection to the pool. The calling thread should cease to use or reference the connection. The connection should still be open.

Parameters:

c - The connection.

Throws:

java.lang.IllegalArgumentException - If the connection is not a member of the pool.

java.lang.IllegalStateException - If the connection has not been reserved.

destroy

public void destroy()

Destroys the pool. Connections currently in use are left untouched; they may be returned to the pool in the future, at which time they will be closed. All other connections are immediately closed.