com.programix.sql
Class ConnectionPool

java.lang.Object
  com.programix.sql.ConnectionPool

All Implemented Interfaces:

ConnectionSource

public class ConnectionPool
extends Object
implements ConnectionSource

This implementation of ConnectionSource is a variable size pool of database Connection's.

This pool is not "bottomless" as the MAX_CONNECTION_COUNT_KEY is specified (when the max number of connections have be created, calls to getConnection() block waiting for an idle connection to be checked back into the pool.

This pool also has a HIGH_WATER_COUNT_KEY which specifies the preferred maximum number of idle connections the pool should hold. When there are more than this many idle connections for a period of time specified by SHRINK_DELAY_SECONDS_KEY, a connection is permanently removed from the pool and closed/destroyed.

A typical way to configure this pool is with a ValueMap with settings such as:

 # Settings specifically for the ConnectionPool:
 sql.connection.pool.max.connection.count=50
 sql.connection.pool.high.water.count=5
 sql.connection.pool.shrink.delay.seconds=5
 sql.connection.pool.health.check.query=SELECT max(1)

 # Settings for the DriverManagerConnectionSource used as the
 # underlying ConnectionSource for this ConnectionPool:
 sql.connection.driver=org.postgresql.Driver
 sql.connection.url=jdbc:postgresql://localhost:5432/andrewdb
 sql.connection.username=someone
 sql.connection.password=something
 sql.connection.extras.ssl=true
 sql.connection.extras.loginTimeout=90
 

Author:

Paul Hyde

Nested Class Summary

class

ConnectionPool.PooledConnection

Field Summary

static String	DEFAULT_HEALTH_CHECK_QUERY Default value used when the optional health check query parameter is not specified.
static int	DEFAULT_HIGH_WATER_COUNT Default value used when the optional high water count parameter is not specified.
static int	DEFAULT_MAX_CONNECTION_COUNT Default value used when the optional max connection count parameter is not specified.
static int	DEFAULT_SHRINK_DELAY_SECONDS Default value used when the optional shrink delay seconds parameter is not specified.
static String	HEALTH_CHECK_QUERY_KEY Optional configuration key specifying the query statement to use to confirm the health of a connection.
static String	HIGH_WATER_COUNT_KEY Optional configuration key specifying the "high water mark" which indicates the number of idle connections over which the pool will slowly drain.
static String	MAX_CONNECTION_COUNT_KEY Optional configuration key specifying the maximum number of connections that can exist in the pool—both idle and those currently being used.
static String	SHRINK_DELAY_SECONDS_KEY Optional configuration key specifying the number of seconds to pause between the closing of idle connections when the pool idle level is above the high water mark.

Constructor Summary

ConnectionPool(ConnectionSource underlyingSource)

ConnectionPool(ConnectionSource underlyingSource, int maxConnectionCount, int highWaterCount, int shrinkDelaySeconds)

ConnectionPool(ConnectionSource underlyingSource, int maxConnectionCount, int highWaterCount, int shrinkDelaySeconds, String healthCheckQuery)

ConnectionPool(ConnectionSource underlyingSource, int maxConnectionCount, int highWaterCount, int shrinkDelaySeconds, String healthCheckQuery, ExceptionHandler exceptionHandler)

ConnectionPool(ConnectionSource underlyingSource, int maxConnectionCount, int highWaterCount, int shrinkDelaySeconds, String healthCheckQuery, ExceptionHandler exceptionHandler, Object lockObject)

ConnectionPool(ConnectionSource underlyingSource, ValueMap config)

ConnectionPool(ConnectionSource underlyingSource, ValueMap config, ExceptionHandler exceptionHandler)

ConnectionPool(ValueMap config)

ConnectionPool(ValueMap config, ExceptionHandler exceptionHandler)

Method Summary

static ConnectionSource	createConnectionSource(ValueMap config) This method is used to create a ConnectionSource by analyzing the config ValueMap to determine which kind of ConnectionSource should be created.
Connection	getConnection() Returns a Connection (potentially from a shared resource pool).
Connection	getConnection(long msTimeout) Returns a Connection (potentially from a shared resource pool).
void	shutdown() Call this when done with the ConnectionSource to allow any underlying allocated resources to be released.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_CONNECTION_COUNT_KEY

public static final String MAX_CONNECTION_COUNT_KEY

Optional configuration key specifying the maximum number of connections that can exist in the pool—both idle and those currently being used. Calls to get a connection from the pool will block when there are no idle connections in the pool and this max has been reached. The value of this constant is always:

 sql.connection.pool.max.connection.count
 

See Also:

Constant Field Values

HIGH_WATER_COUNT_KEY

public static final String HIGH_WATER_COUNT_KEY

Optional configuration key specifying the "high water mark" which indicates the number of idle connections over which the pool will slowly drain. As long as the number of idle connections remains greater than this high water mark, the pool will close an idle connection every "shink delay seconds" (another configuration parameter). The value of this constant is always:

 sql.connection.pool.high.water.count
 

See Also:

Constant Field Values

SHRINK_DELAY_SECONDS_KEY

public static final String SHRINK_DELAY_SECONDS_KEY

Optional configuration key specifying the number of seconds to pause between the closing of idle connections when the pool idle level is above the high water mark. The value of this constant is always:

 sql.connection.pool.shrink.delay.seconds
 

See Also:

Constant Field Values

HEALTH_CHECK_QUERY_KEY

public static final String HEALTH_CHECK_QUERY_KEY

Optional configuration key specifying the query statement to use to confirm the health of a connection. This should be a SELECT statement that is very fast to execute. The value of this constant is always:

 sql.connection.pool.health.check.query
 

See Also:

Constant Field Values

DEFAULT_MAX_CONNECTION_COUNT

public static final int DEFAULT_MAX_CONNECTION_COUNT

Default value used when the optional max connection count parameter is not specified. The value of this constant is 50 connections.

See Also:

Constant Field Values

DEFAULT_HIGH_WATER_COUNT

public static final int DEFAULT_HIGH_WATER_COUNT

Default value used when the optional high water count parameter is not specified. The value of this constant is 5 connections.

See Also:

Constant Field Values

DEFAULT_SHRINK_DELAY_SECONDS

public static final int DEFAULT_SHRINK_DELAY_SECONDS

Default value used when the optional shrink delay seconds parameter is not specified. The value of this constant is 5 seconds.

See Also:

Constant Field Values

DEFAULT_HEALTH_CHECK_QUERY

public static final String DEFAULT_HEALTH_CHECK_QUERY

Default value used when the optional health check query parameter is not specified. The value of this constant is:

 SELECT max(1)
 

See Also:

Constant Field Values

Constructor Detail

ConnectionPool

public ConnectionPool(ConnectionSource underlyingSource,
                      int maxConnectionCount,
                      int highWaterCount,
                      int shrinkDelaySeconds,
                      String healthCheckQuery,
                      ExceptionHandler exceptionHandler,
                      Object lockObject)

ConnectionPool

public ConnectionPool(ConnectionSource underlyingSource,
                      int maxConnectionCount,
                      int highWaterCount,
                      int shrinkDelaySeconds,
                      String healthCheckQuery,
                      ExceptionHandler exceptionHandler)

ConnectionPool

public ConnectionPool(ConnectionSource underlyingSource,
                      int maxConnectionCount,
                      int highWaterCount,
                      int shrinkDelaySeconds,
                      String healthCheckQuery)

ConnectionPool

public ConnectionPool(ConnectionSource underlyingSource,
                      int maxConnectionCount,
                      int highWaterCount,
                      int shrinkDelaySeconds)

ConnectionPool

public ConnectionPool(ConnectionSource underlyingSource)

ConnectionPool

public ConnectionPool(ConnectionSource underlyingSource,
                      ValueMap config,
                      ExceptionHandler exceptionHandler)

ConnectionPool

public ConnectionPool(ConnectionSource underlyingSource,
                      ValueMap config)

ConnectionPool

public ConnectionPool(ValueMap config,
                      ExceptionHandler exceptionHandler)
               throws SQLException

Throws:

SQLException

ConnectionPool

public ConnectionPool(ValueMap config)
               throws SQLException

Throws:

SQLException

Method Detail

createConnectionSource

public static ConnectionSource createConnectionSource(ValueMap config)
                                               throws SQLException

This method is used to create a ConnectionSource by analyzing the config ValueMap to determine which kind of ConnectionSource should be created.

If DriverManagerConnectionSource.DRIVER_KEY is present, then a DriverManagerConnectionSource is created.

Throws:

SQLException

getConnection

public Connection getConnection(long msTimeout)
                         throws SQLTimedOutException,
                                SQLInterruptedException,
                                SQLShutdownException,
                                SQLException

Description copied from interface: ConnectionSource

Returns a Connection (potentially from a shared resource pool). This connection may be checked out from a shared pool of connections or may be from some other source. When done with a Connection, be sure to close it to potentially return it to a pool. Due to the fact that this Connection might be in a shared pool, you must ensure that after you have called close, your code does not do anything more with this Connection or anything it created (like a Statement, or a ResultSet).

Calls to this method may block while waiting for a Connection if there is a maximum number of connections allowed in an underlying resource pool.

Specified by:

getConnection in interface ConnectionSource

Parameters:

msTimeout - the maximum amount of time to wait for a connection to become available.

Throws:

SQLTimedOutException - if the specific maximum waiting time is exceeded and still no connection is available. Only some implementations (ones that support timeout detection) throw this specific SQLException. This is a subclass of SQLException so callers can optionally ignore this specific kind of exception by simply catching SQLException.

SQLInterruptedException - if calling thread is interrupted while waiting for a connection to become available. Only some implementations (ones that support interrupt detection) throw this specific SQLException. This is a subclass of SQLException so callers can optionally ignore this specific kind of exception by simple catching SQLException.

SQLException - if there is trouble getting a connection.

SQLShutdownException

getConnection

public Connection getConnection()
                         throws SQLInterruptedException,
                                SQLShutdownException,
                                SQLException

Description copied from interface: ConnectionSource

Returns a Connection (potentially from a shared resource pool). This connection may be checked out from a shared pool of connections or may be from some other source. When done with a Connection, be sure to close it to potentially return it to a pool. Due to the fact that this Connection might be in a shared pool, you must ensure that after you have called close, your code does not do anything more with this Connection or anything it created (like a Statement, or a ResultSet).

Calls to this method may block while waiting for a Connection if there is a maximum number of connections allowed in an underlying resource pool.

Specified by:

getConnection in interface ConnectionSource

Throws:

SQLInterruptedException - if calling thread is interrupted while waiting for a connection to become available. Only some implementations (ones that support interrupt detection) throw this specific SQLException. This is a subclass of SQLException so callers can optionally ignore this specific kind of exception by simple catching SQLException.

SQLException - if there is trouble getting a connection.

SQLShutdownException

shutdown

public void shutdown()

Description copied from interface: ConnectionSource

Call this when done with the ConnectionSource to allow any underlying allocated resources to be released.

Specified by:

shutdown in interface ConnectionSource