com.bristle.javalib.sql
Class ConnectionPool

java.lang.Object
  com.bristle.javalib.sql.ConnectionPool

Direct Known Subclasses:

DummyConnectionPool

public class ConnectionPool
extends Object

This class encapsulates pools of database connections.

Usage:
       - The typical scenario for using this class is:
         - Once, at startup:
             ConnectionPool pool = new ConnectionPool
                                         ("oracle.jdbc.driver.OracleDriver");
         - At each point where a connection is needed.
             Connection conn = pool.getConnection(objConfig);
             ... Use the connection ...
             pool.returnConnection(conn);
         - If an error occurs while using the connection, you can advise 
           the connection pool to close the connection and stop pooling it.
             Connection conn = pool.getConnection(objConfig);
             ... Try to use the connection, but decide that there is 
                 something wrong with the connection, so you need a
                 different one ...
             pool.returnConnection(conn, true);
             Connection conn = pool.getConnection(objConfig);
             ... Use the connection ...
             pool.returnConnection(conn);

   - See the source code of the inner Tester class for more examples.
  
Assumptions:
Effects:
       - Creates and manages database connections.
Anticipated Changes:
       - Add code to close and remove connections that have been held for 
         too long.  Client must have forgotten to return them to the pool.
         Should close them to conserve resources.  Don't just return them 
         to the pool.  May not be a good idea to let other clients use 
         them since we're not positive the current client is done.
       - Add code to limit the number of concurrent connections.
       - Could be rewritten to require the caller to create a separate 
         connection pool for each set of credentials, by moving the 
         credentials from getConnection() to the constructor.  Advantages?
Notes:
Implementation Notes:
Portability Issues:
Revision History:
   $Log$

Nested Class Summary

static interface	ConnectionPool.DBConfig This interface must be implemented by any class that expects to serve as a DBConfig object for use with ConnectionPool.
static class	ConnectionPool.SimpleDBConfig Sample class implementing the DBConfig interface.
static class	ConnectionPool.Tester Each class contains a Tester inner class with a main() for easier unit testing.

Constructor Summary

ConnectionPool(String strDBDriverClassName)
Constructor.

ConnectionPool(String strDBDriverClassName, int intMaxTimesToUse)
Constructor.

Method Summary

void	clear() Clear all connections from the pool, closing them.
void	clearAvailable() Clear all available connections from the pool, closing them.
void	clearIdle() Clear all available connections that have been idle too long from the pool, closing them.
int	getAvailableConnectionCount() Get the count of available connections in the pool.
Connection	getConnection(ConnectionPool.DBConfig objConfig) Get a connection from the pool.
int	getConnectionCount() Get the count of connections in the pool.
long	getMaxIdleMillisecs() Get the max number of milliseconds a database connection will sit idle in the pool before being closed.
int	getMaxTimesToUse() Get the max number of times to use the connection before closing it and opening a new one.
static ConnectionPool	getSingleton() Get the singleton ConnectionPool, if any.
void	returnConnection(Connection conn) Return a connection to the pool for reuse by others.
void	returnConnection(Connection conn, boolean blnClose) Return a connection to the pool, optionally closing it so it won't be used anymore.
void	setMaxIdleMillisecs(long lngVal) Set the max number of milliseconds a database connection will sit idle in the pool before being closed.
void	setMaxTimesToUse(int intVal) Set the max number of times to use the connection before closing it and opening a new one.
static void	setSingleton(ConnectionPool pool) Set the singleton ConnectionPool.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionPool

public ConnectionPool(String strDBDriverClassName)
               throws ClassNotFoundException,
                      InstantiationException,
                      IllegalAccessException

Constructor.

Parameters:

strDBDriverClassName - Name of the database JDBC driver class. Example: "oracle.jdbc.driver.OracleDriver"

Throws:

ClassNotFoundException - When driver class not installed.

InstantiationException - When driver class can't be instantiated.

IllegalAccessException - When driver class can't be accessed.

ConnectionPool

public ConnectionPool(String strDBDriverClassName,
                      int intMaxTimesToUse)
               throws ClassNotFoundException,
                      InstantiationException,
                      IllegalAccessException

Constructor.

Parameters:

strDBDriverClassName - Name of the database JDBC driver class. Example: "oracle.jdbc.driver.OracleDriver"

intMaxTimesToUse - Max times to reuse connection before closing and opening a new one.

Throws:

ClassNotFoundException - When driver class not installed.

InstantiationException - When driver class can't be instantiated.

IllegalAccessException - When driver class can't be accessed.

Method Detail

setMaxTimesToUse

public void setMaxTimesToUse(int intVal)

Set the max number of times to use the connection before closing it and opening a new one. Actually, the number of times to give it to an application via getConnection() for potentially multiple uses and accept it back via returnConnection() before closing it and opening a new one. This is useful for keeping connections from getting too old in case they leak resources of some sort by being used, or somehow become stale. It also offers the application a way to force a peak number of connections to be released in a controlled way. Setting it low will force each connection to release itself after the next use. Then set it high again.

Parameters:

intVal - The new value.

getMaxTimesToUse

public int getMaxTimesToUse()

Get the max number of times to use the connection before closing it and opening a new one. Actually, the number of times to give it to an application via getConnection() for potentially multiple uses and accept it back via returnConnection() before closing it and opening a new one.

Returns:

The max number.

setMaxIdleMillisecs

public void setMaxIdleMillisecs(long lngVal)

Set the max number of milliseconds a database connection will sit idle in the pool before being closed. This is especially useful with databases like MySQL that timeout idle connections after 8 hours, causing further attempts at using them to throw exceptions. Connections exceeding this idle time are closed and removed from the pool by a monitor thread. Connections dispensed to the application by getConnection() are not closed; only those returned to the pool by returnConnection(). The idle time for a connection is reset to zero milliseconds by returnConnection(). Note: The monitor thread runs no more than 10 times per max number of milliseconds, and never more than once per second, so connections may sit idle up to 1 second longer or even up to 10% longer than specified.

Parameters:

lngVal - The new value

getMaxIdleMillisecs

public long getMaxIdleMillisecs()

Get the max number of milliseconds a database connection will sit idle in the pool before being closed.

Returns:

The max number.

getConnection

public Connection getConnection(ConnectionPool.DBConfig objConfig)
                         throws SQLException

Get a connection from the pool.

Parameters:

objConfig - Configuration data needed to connect to the database.

Returns:

Database connection.

Throws:

SQLException - When unable to connect to the database.

returnConnection

public void returnConnection(Connection conn,
                             boolean blnClose)
                      throws SQLException

Return a connection to the pool, optionally closing it so it won't be used anymore.

Parameters:

conn - Connection to return.

blnClose - Boolean flag indicating whether to close the connection.

Throws:

SQLException - When unable to rollback the returned connection.

returnConnection

public void returnConnection(Connection conn)
                      throws SQLException

Return a connection to the pool for reuse by others.

Parameters:

conn - Connection to return.

Throws:

SQLException - When unable to rollback the returned connection.

clearAvailable

public void clearAvailable()

Clear all available connections from the pool, closing them.

clearIdle

public void clearIdle()

Clear all available connections that have been idle too long from the pool, closing them.

clear

public void clear()

Clear all connections from the pool, closing them.

Note:
      Dangerous.  Closes all database connections in the entire pool
      regardless of whether they are currently allocated by a client.
      Use clearAvailable() instead when appropriate.

getConnectionCount

public int getConnectionCount()

Get the count of connections in the pool.

Returns:

Count of connections.

getAvailableConnectionCount

public int getAvailableConnectionCount()

Get the count of available connections in the pool.

Returns:

Count of available connections.

setSingleton

public static void setSingleton(ConnectionPool pool)

Set the singleton ConnectionPool.

Parameters:

pool - The ConnectionPool instance to be stored as the singleton.

getSingleton

public static ConnectionPool getSingleton()

Get the singleton ConnectionPool, if any.

Returns:

The singleton ConnectionPool, or null.