com.protomatter.jdbc.pool
Class JdbcConnectionPool

java.lang.Object
  |
  +--com.protomatter.pool.SimpleObjectPool
        |
        +--com.protomatter.pool.GrowingObjectPool
              |
              +--com.protomatter.jdbc.pool.JdbcConnectionPool

All Implemented Interfaces:

ObjectPool, SyslogChannelAware

public class JdbcConnectionPool

extends GrowingObjectPool

implements SyslogChannelAware

Provides a pool of pre-opened JDBC connections. The configuration hashtable can contain the following:

pool.initialSize (Integer)

The initial pool size (default is 0).

pool.maxSize (Integer)

The max pool size (default is -1). If the max pool size is -1, the pool grows infinitely.

pool.growBlock (Integer)

The grow size (default is 1). When a new object is needed, this many are created.

pool.createWaitTime (Integer)

The time (in ms) to sleep between pool object creates (default is 0). This is useful for database connection pools where it's possible to overload the database by trying to make too many connections too quickly.

jdbc.driver (String)

The name of the JDBC driver class to use

jdbc.URL (String)

The URL to use for the underlying. JDBC connections.

jdbc.properties (java.util.Properties)

Properties for the connection. Should include at least "user" and "password" -- see DriverManager.getConnection(String, Properties) for what the properties should include. Each underlying JDBC driver has it's own properties that it pays attention to, so you may need to consult the driver's documentation.

jdbc.validityCheckStatement (String)

A SQL statement that is guaranteed to return at least 1 row. For Oracle, this is "select 1 from dual" and for Sybase it is "select 1". This statement is used as a means of checking that a connection is indeed working.

pool.useSyslog (Boolean)

When writing warnings, errors, etc, should the pool use Syslog, or the PrintWriter returned from DriverManager.getLogWriter()? Default is true.

pool.syslogChannelList (String)

A comma-separated list of channel names to log messages to. The symbolic names Syslog.DEFAULT_CHANNEL and Syslog.ALL_CHANNEL are understood. This is ignored if pool.useSyslog is false.

pool.validateOnCheckout (Boolean)

Determine if we should only hand out validated connections or not. If set to true, each connection is tested with the pool.validityCheckStatement prior to being returned. Default is false. If this option is used, you must specify the jdbc.validityCheckStatement option also.

pool.maxCheckoutRefreshAttempts (Integer)

Determines the number of times to attempt to refresh a connection on checkout before giving up. Default is 5, and setting it to -1 will cause the pool to keep trying forever. This setting only comes into play if pool.validateOnCheckout is set to true.

pool.checkoutRefreshWaitTime (Integer)

The number of milliseconds to wait between attempts to refresh a connection when checking it out from the pool. The default is 500ms. Setting this to 0 will cause no delay. This setting only comes into play if pool.validateOnCheckout is set to true.

pool.refreshThreadCheckInterval (Integer)

If present and > 0, this is the number of seconds for a low-priority thread to sleep between calls to refreshConnections() on this pool. If this option is used, you must specify the jdbc.validityCheckStatement option also.

pool.verboseRefresh (Boolean)

If present and true, the refresh thread will write messages when it refreshes connections.

pool.verboseValidate (Boolean)

If present and true, operations while validating connections before checkout will be logged.

pool.maxConnectionIdleTime (Integer)

If this property is present, and the pool.maidThreadCheckInterval property is also present, then a thread will be created that looks for connections that have been idle for more than pool.maxConnectionIdleTime seconds. When this thread finds them, it closed the connection and logs a warning with a stack trace of when the connection was checked out of the pool. This is primarily here as a debugging aid for finding places where connections are not getting close, and should not be used in a production environment.

pool.maidThreadCheckInterval (Integer)

This is the number of seconds between attempts by the maid thread (if present) to find idle connections.

See Also:

java.sql.DriverManager, JdbcConnectionPoolDriver, JdbcConnectionPoolConnection

Fields inherited from class com.protomatter.pool.SimpleObjectPool

sync

Constructor Summary

JdbcConnectionPool(java.lang.String name)
Create a new JDBC connection pool with the given name.

JdbcConnectionPool(java.lang.String name, java.util.Map args)
Create a new JDBC connection pool with the given name, and the given initialization parameters.

JdbcConnectionPool(java.lang.String name, java.util.Properties props)
Create a connection pool from properties.

Method Summary

void	closeAllConnections() Shutdown all the connections that this pool has open and checked in.
protected ObjectPoolObject	createObjectPoolObject() Used internally for growing the pool.
static java.util.List	createPools(java.util.Properties props) Create pools from a properties object.
java.lang.String	getName() Get the name of this pool.
java.lang.Object	getSyslogChannel() Get the channel(s) to log messages to.
java.lang.String	getValidityCheckStatement() Get the statement set as the validity check statement.
void	init(java.util.Map args) Initialize the pool.
void	refreshConnections() Performs a non-verbose refresh of the connections.
void	refreshConnections(boolean verbose) Refresh the connections.
void	setSyslogChannel(java.lang.String channelName) Set the channel that messages will be logged to.
void	setSyslogChannelList(java.util.List channelList) Set the list of channels that messages will be logged to.
void	unRegisterPool() Remove this pool from the JdbcConnectionPoolDriver's list of known pools.

Methods inherited from class com.protomatter.pool.GrowingObjectPool

checkinPoolObject, getCreateWaitTime, getCurrentPoolSize, getInitialObjectPoolSize, getMaxObjectPoolSize, getNextPoolObject, getObjectPoolGrowSize, getObjectPoolSize, getPool, reInitializeObjectPool, setMaxObjectPoolSize

Methods inherited from class com.protomatter.pool.SimpleObjectPool

checkin, checkout, getCheckedOutObjects, getNumWaiters, getObjectsInUse, getSyncObject

Methods inherited from class java.lang.Object

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

Constructor Detail

JdbcConnectionPool

public JdbcConnectionPool(java.lang.String name,
                          java.util.Map args)
                   throws java.lang.Exception

Create a new JDBC connection pool with the given name, and the given initialization parameters.

Parameters:

name - The name of the pool.

args - Initialization arguments.

Throws:

java.lang.Exception - If there is a problem initializing the pool.

See Also:

init(java.util.Map)

JdbcConnectionPool

public JdbcConnectionPool(java.lang.String name,
                          java.util.Properties props)
                   throws java.lang.Exception

Create a connection pool from properties. Looks for properties in the following form:

  ##
  ## Pool initialization parameters.  These each
  ## correspond to parameters passed into the
  ## init(ht) method -- the values are each
  ## converted to the appropriate type.  The
  ## "jdbc.properties" option is not specified
  ## here.
  ##
  com.protomatter.jdbc.pool.POOLNAME=\
    jdbc.driver=driverclass,\
    jdbc.URL=connection_URL,\
    jdbc.validityCheckStatement=driverclass,\
    pool.maxCheckoutRefreshAttempts=num_attempts,\
    pool.checkoutRefreshWaitTime=num_milliseconds,\
    pool.refreshThreadCheckInterval=num_seconds,\
    pool.verboseRefresh=true or false,\
    pool.verboseValidate=true or false,\
    pool.initialSize=initial_pool_size,\
    pool.maxSize=max_pool_size,\
    pool.growBlock=pool_grow_block_size,\
    pool.createWaitTime=pool_create_wait_time,\
    pool.maidThreadCheckInterval=num_seconds,\
    pool.maxConnectionIdleTime=num_seconds,\
    pool.validateOnCheckout=true or false,\
    pool.syslogChannelList=list-of-channel-names

  ##
  ## Connection properties for the underlying driver.
  ## These correspond to the properties that are
  ## placed in the configuraton hashtable with the
  ## key "jdbc.properties".  These will be passed as
  ## the second argument to DriverManager.getConnection().
  ## Usually it just contains a usename and a password, but
  ## many drivers allow you to specify other options here.
  ##
  com.protomatter.jdbc.pool.POOLNAME.jdbcProperties=\
    user=username,\
    password=password,\
    key=val
  

Each value specified in the properties is converted to the correct type (for instance, the "pool.initialSize" property's value is converted to an Integer). The "POOLNAME" that appears above must match the "name" parameter passed to this method -- this allows to the same properties object to be passed into this constructor multiple times (each with a different "name" parameter) to create multiple pools.

Parameters:

name - The name of the pool.

props - Properties describing pools.

See Also:

init(java.util.Map)

JdbcConnectionPool

public JdbcConnectionPool(java.lang.String name)

Create a new JDBC connection pool with the given name. You must call init(...) before using it.

Parameters:

name - The name of the pool.

See Also:

init(java.util.Map)

Method Detail

getSyslogChannel

public java.lang.Object getSyslogChannel()

Get the channel(s) to log messages to.

Specified by:

getSyslogChannel in interface SyslogChannelAware

See Also:

SyslogChannelAware

setSyslogChannel

public void setSyslogChannel(java.lang.String channelName)

Set the channel that messages will be logged to.

See Also:

SyslogChannelAware

setSyslogChannelList

public void setSyslogChannelList(java.util.List channelList)

Set the list of channels that messages will be logged to.

See Also:

SyslogChannelAware

createPools

public static java.util.List createPools(java.util.Properties props)
                                  throws java.lang.Exception

Create pools from a properties object. This method looks for all the properties matching the constraints in the JdbcConnectionPool(String, Properties) constructor, and creates a connection pool for each. The resulting pools are placed in a List and returned.

See Also:

JdbcConnectionPool(String, Properties)

unRegisterPool

public void unRegisterPool()

Remove this pool from the JdbcConnectionPoolDriver's list of known pools.

getName

public java.lang.String getName()

Get the name of this pool.

closeAllConnections

public void closeAllConnections()

Shutdown all the connections that this pool has open and checked in. This should only be done as part of a system shutdown of some kind.

refreshConnections

public void refreshConnections(boolean verbose)
                        throws java.sql.SQLException

Refresh the connections. This will call refresh() on all the connections that are currently checked-in. If there are SQLExceptions thrown while refreshing connections, the last one is thrown back. Any of the connections that fail the refresh are removed from the pool. If verbose is true, messages are written to Syslog about the refresh operation.

Throws:

java.sql.SQLException - If there is a problem refreshing connections.

See Also:

JdbcConnectionPoolConnection.refresh(boolean)

refreshConnections

public void refreshConnections()
                        throws java.sql.SQLException

Performs a non-verbose refresh of the connections.

See Also:

refreshConnections(boolean)

init

public void init(java.util.Map args)
          throws java.lang.Exception

Initialize the pool. Reads the following from the Map:

jdbc.driver (String)

The name of the JDBC driver class to use

jdbc.URL (String)

The URL to use for the underlying. JDBC connections.

jdbc.properties (java.util.Properties)

Properties for the connection. Should include at least "user" and "password" -- see DriverManager.getConnection(String, Properties) for what the properties should include.

pool.syslogChannelList (String)

A comma-separated list of channel names to log messages to. The symbolic names Syslog.DEFAULT_CHANNEL and Syslog.ALL_CHANNEL are understood.

jdbc.validityCheckStatement (String)

A SQL statement that is guaranteed to return at least 1 row. For Oracle, this is "select 1 from dual" and for Sybase it is "select 1". This statement is used as a means of checking that a connection is indeed working.

pool.refreshThreadCheckInterval (Integer)

If present and > 0, this is the number of seconds for a low-priority thread to sleep between calls to refreshConnections() on this pool. If this option is used, you must specify the jdbc.validityCheckStatement option also.

pool.verboseRefresh (Boolean)

If present and true, the refresh thread will write messages using Syslog when it refreshes connections.

pool.verboseValidate (Boolean)

If present and true, operations while validating connections before checkout will be logged to Syslog.

pool.maxConnectionIdleTime (Integer)

If this property is present, and the pool.maidThreadCheckInterval property is also present, then a thread will be created that looks for connections that have been idle for more than pool.maxConnectionIdleTime seconds. When this thread finds them, it closed the connection and logs a warning using the Syslog service with a stack trace of when the connection was checked out of the pool. This is primarily here as a debugging aid for finding places where connections are not getting close, and should not be used in a production environment.

pool.maidThreadCheckInterval (Integer)

This is the number of seconds between attempts by the maid thread (if present) to find idle connections.

pool.validateOnCheckout (Boolean)

Determine if we should only hand out validated connections or not. If set to true, each connection is tested with the pool.validityCheckStatement prior to being returned. Default is false.

pool.checkoutRefreshWaitTime (Integer)

The number of milliseconds to wait between attempts to refresh a connection when checking it out from the pool. The default is 500ms. Setting this to 0 will cause no delay. This setting only comes into play if pool.validateOnCheckout is set to true.

pool.refreshThreadCheckInterval (Integer)

If present and > 0, this is the number of seconds for a low-priority thread to sleep between calls to refreshConnections() on this pool. If this option is used, you must specify the jdbc.validityCheckStatement option also.

The other options listed above are read by this class's superclass, com.protomatter.pool.GrowingObjectPool.

This method is called by the constructor that takes a String and a Map. Calling this method multiple times will have no effect on the pool since all but the first call are ignored.

Overrides:

init in class GrowingObjectPool

Throws:

java.lang.Exception - If there is a problem initializing the pool.

See Also:

GrowingObjectPool.init(java.util.Map)

createObjectPoolObject

protected ObjectPoolObject createObjectPoolObject()
                                           throws java.sql.SQLException

Used internally for growing the pool.

Overrides:

createObjectPoolObject in class SimpleObjectPool

Throws:

java.sql.SQLException - If there is a problem creating a new connection.

getValidityCheckStatement

public java.lang.String getValidityCheckStatement()

Get the statement set as the validity check statement.

See Also:

init(java.util.Map)