snaq.db

Class ConnectionPool

java.lang.Object

snaq.util.ObjectPool<CacheConnection>

snaq.db.ConnectionPool

All Implemented Interfaces:

Comparable<ObjectPool<CacheConnection>>

public class ConnectionPool
extends ObjectPool<CacheConnection>

Implementation of a database connection pool.

Author:

Giles Winstanley

See Also:

CacheConnection, CachedCallableStatement, CachedPreparedStatement

Nested Class Summary

Nested classes/interfaces inherited from class snaq.util.ObjectPool

ObjectPool.Strategy

Field Summary

Fields inherited from class snaq.util.ObjectPool

log

Constructor Summary

Constructors

Constructor and Description
ConnectionPool(String name, int minPool, int maxPool, int maxSize, long idleTimeout, String url, Properties props) Creates a new ConnectionPool instance.
ConnectionPool(String name, int minPool, int maxPool, int maxSize, long idleTimeout, String url, String username, String password) Creates a new ConnectionPool instance.
ConnectionPool(String name, int maxPool, int maxSize, long idleTimeout, String url, Properties props) Creates a new ConnectionPool instance (with minPool=0).
ConnectionPool(String name, int maxPool, int maxSize, long idleTimeout, String url, String username, String password) Creates a new ConnectionPool instance (with minPool=0).

Method Summary

Modifier and Type	Method and Description
void	addConnectionPoolListener(ConnectionPoolListener listener) Adds a ConnectionPoolListener to the event notification list.
protected CacheConnection	create() Creates a new Connection object.
protected void	destroy(CacheConnection cc) Closes the specified CacheConnection object.
protected void	freeConnection(Connection c) Returns a Connection to the pool (for internal use only).
Connection	getConnection() Gets a Connection from the pool.
Connection	getConnection(long timeout) Gets a Connection from the pool, waiting a maximum of timeout milliseconds for one to become available, returning null if not.
protected float	getIdleTimeoutMultiplier() Returns the multiplier for adjusting the idle timeout unit.
protected long	getMaximumCleaningInterval() Specifies the maximum time interval between cleaning attempts of the Cleaner thread.
protected long	getMinimumCleaningInterval() Specifies the minimum time interval between cleaning attempts of the Cleaner thread.
PasswordDecoder	getPasswordDecoder() Returns the current PasswordDecoder class.
ConnectionValidator	getValidator() Returns the current ConnectionValidator class.
boolean	isCachingCallableStatements() Returns whether the pool caches CallableStatement instances for each connection.
boolean	isCachingPreparedStatements() Returns whether the pool caches PreparedStatement instances for each connection.
boolean	isCachingStatements() Returns whether the pool caches Statement instances for each connection.
boolean	isRecycleAfterDelegateUse() Returns whether connections may be recycled if the underlying raw/delegate connection has been used.
protected boolean	isValid(CacheConnection cc) Validates a CacheConnection object.
protected void	postRelease() Method to give a sub-class the opportunity to cleanup resources after the pool is officially released.
protected void	preRelease() Method to give a sub-class the opportunity to cleanup resources before the pool is officially released.
void	registerMBean() Registers this pool with the platform MBean server.
void	removeConnectionPoolListener(ConnectionPoolListener listener) Removes a ConnectionPoolListener from the event notification list.
void	setCaching(boolean b) Determines whether to perform statement caching.
void	setCaching(boolean ss, boolean ps, boolean cs) Determines whether to perform statement caching.
void	setPasswordDecoder(PasswordDecoder pd) Sets the PasswordDecoder class.
void	setRecycleAfterDelegateUse(boolean b) Sets whether the connection may be recycled if the underlying raw/delegate connection has been used (default: false).
void	setValidator(ConnectionValidator cv) Sets the validator class for Connection instances.
void	unregisterMBean() Removes this pool from the platform MBean server registration list.

Methods inherited from class snaq.util.ObjectPool

addObjectPoolListener, checkIn, checkOut, checkOut, compareTo, equals, flush, getCheckedOut, getCustomLogger, getFreeCount, getIdleTimeout, getIdleTimeoutUnadjusted, getMaxPool, getMaxSize, getMinPool, getName, getParametersString, getPoolClass, getPoolHitRate, getPoolMissRate, getRequestCount, getSize, hashCode, init, init, isAsyncDestroy, isReleased, log_debug, log_debug, log_error, log_error, log_info, log_info, log_trace, log_trace, log_warn, log_warn, registerShutdownHook, release, release, releaseAsync, releaseAsync, releaseForcibly, releaseImmediately, removeObjectPoolListener, removeShutdownHook, resetHitCounter, setAsyncDestroy, setLog, setParameters, setParameters, setSelectionStrategy, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ConnectionPool

public ConnectionPool(String name,
                      int minPool,
                      int maxPool,
                      int maxSize,
                      long idleTimeout,
                      String url,
                      String username,
                      String password)

Creates a new ConnectionPool instance.

Parameters:

name - pool name

minPool - minimum number of pooled connections, or 0 for none

maxPool - maximum number of pooled connections, or 0 for none

maxSize - maximum number of possible connections, or 0 for no limit

idleTimeout - idle timeout (seconds) for idle pooled connections, or 0 for no timeout

url - JDBC connection URL

username - database username

password - password for the database username supplied

ConnectionPool

public ConnectionPool(String name,
                      int maxPool,
                      int maxSize,
                      long idleTimeout,
                      String url,
                      String username,
                      String password)

Creates a new ConnectionPool instance (with minPool=0).

Parameters:

name - pool name

maxPool - maximum number of pooled connections, or 0 for none

maxSize - maximum number of possible connections, or 0 for no limit

idleTimeout - idle timeout (seconds) for idle pooled connections, or 0 for no timeout

url - JDBC connection URL

username - database username

password - password for the database username supplied

ConnectionPool

public ConnectionPool(String name,
                      int minPool,
                      int maxPool,
                      int maxSize,
                      long idleTimeout,
                      String url,
                      Properties props)

Creates a new ConnectionPool instance.

Parameters:

name - pool name

minPool - minimum number of pooled connections, or 0 for none

maxPool - maximum number of pooled connections, or 0 for none

maxSize - maximum number of possible connections, or 0 for no limit

idleTimeout - idle timeout (seconds) for idle pooled connections, or 0 for no timeout

url - JDBC connection URL

props - connection properties

ConnectionPool

public ConnectionPool(String name,
                      int maxPool,
                      int maxSize,
                      long idleTimeout,
                      String url,
                      Properties props)

Creates a new ConnectionPool instance (with minPool=0).

Parameters:

name - pool name

maxPool - maximum number of pooled connections, or 0 for none

maxSize - maximum number of possible connections, or 0 for no limit

idleTimeout - idle timeout (seconds) for idle pooled connections, or 0 for no timeout

url - JDBC connection URL

props - connection properties

Method Detail

registerMBean

public void registerMBean()

Registers this pool with the platform MBean server. Once this method has been called, each pool instance is accessible as an MBean using the javax.management API.

unregisterMBean

public void unregisterMBean()

Removes this pool from the platform MBean server registration list. Once this method has been called, each pool instance is accessible as an MBean using the javax.management API.

create

protected CacheConnection create()
                          throws SQLException

Creates a new Connection object.

Specified by:

create in class ObjectPool<CacheConnection>

Returns:

A new CacheConnection instance

Throws:

SQLException - if thrown while attempting to create connection

isValid

protected boolean isValid(CacheConnection cc)

Validates a CacheConnection object.

Specified by:

isValid in class ObjectPool<CacheConnection>

Parameters:

cc - connection to validate

Returns:

true if cc is valid, false otherwise

setValidator

public void setValidator(ConnectionValidator cv)

Sets the validator class for Connection instances.

Parameters:

cv - ConnectionValidator instance to use for this pool

getValidator

public ConnectionValidator getValidator()

Returns the current ConnectionValidator class.

Returns:

The current ConnectionValidator class

setPasswordDecoder

public void setPasswordDecoder(PasswordDecoder pd)

Sets the PasswordDecoder class.

Parameters:

pd - PasswordDecoder instance to use for this pool

getPasswordDecoder

public PasswordDecoder getPasswordDecoder()

Returns the current PasswordDecoder class.

Returns:

The current PasswordDecoder class

destroy

protected void destroy(CacheConnection cc)

Closes the specified CacheConnection object.

Specified by:

destroy in class ObjectPool<CacheConnection>

Parameters:

cc - connection to destroy

getConnection

public Connection getConnection()
                         throws SQLException

Gets a Connection from the pool.

Returns:

a connection from the pool, or null if nothing available

Throws:

SQLException - if there is an error creating a new connection

getConnection

public Connection getConnection(long timeout)
                         throws SQLException

Gets a Connection from the pool, waiting a maximum of timeout milliseconds for one to become available, returning null if not.

Parameters:

timeout - timeout value in milliseconds

Returns:

item from the pool, or null if nothing available within timeout period

Throws:

SQLException - if there is an error getting a connection

freeConnection

protected void freeConnection(Connection c)
                       throws SQLException

Returns a Connection to the pool (for internal use only). Connections obtained from the pool should be returned by calling Connection.close().

Parameters:

c - connection to free back to the pool

Throws:

SQLException - if thrown while attempting to free connection

preRelease

protected void preRelease()

Description copied from class: ObjectPool

Method to give a sub-class the opportunity to cleanup resources before the pool is officially released. This method is called as the first thing before the remaining ObjectPool release implementation.

Overrides:

preRelease in class ObjectPool<CacheConnection>

postRelease

protected void postRelease()

Description copied from class: ObjectPool

Method to give a sub-class the opportunity to cleanup resources after the pool is officially released. This method is called as the last thing after the main ObjectPool release implementation. Be aware that the event-dispatch thread, cleaner thread, any init threads, and the custom log have all been terminated before this method is called.

Overrides:

postRelease in class ObjectPool<CacheConnection>

getIdleTimeoutMultiplier

protected float getIdleTimeoutMultiplier()

Description copied from class: ObjectPool

Returns the multiplier for adjusting the idle timeout unit. This is a convenience method for sub-classes to override if they want to adjust the time measurement for the idleTimeout parameter. By default it returns 1.0 which denotes milliseconds. A sub-class wanting to operate with seconds would override it to return 1000, or to operate in minutes, 60000.

Overrides:

getIdleTimeoutMultiplier in class ObjectPool<CacheConnection>

Returns:

The multiplier for adjusting the idle timeout unit

setCaching

public final void setCaching(boolean b)

Determines whether to perform statement caching. This applies to all types of statements (normal, prepared, callable).

Parameters:

b - Whether to perform statement caching

setCaching

public void setCaching(boolean ss,
                       boolean ps,
                       boolean cs)

Determines whether to perform statement caching.

Parameters:

ss - whether to cache Statement objects

ps - whether to cache PreparedStatement objects

cs - whether to cache CallableStatement objects

isCachingStatements

public boolean isCachingStatements()

Returns whether the pool caches Statement instances for each connection.

Returns:

true if pool is caching Statement instances, false otherwise

isCachingPreparedStatements

public boolean isCachingPreparedStatements()

Returns whether the pool caches PreparedStatement instances for each connection.

Returns:

true if pool is caching PreparedStatement instances, false otherwise

isCachingCallableStatements

public boolean isCachingCallableStatements()

Returns whether the pool caches CallableStatement instances for each connection.

Returns:

true if pool is caching CallableStatement instances, false otherwise

setRecycleAfterDelegateUse

public final void setRecycleAfterDelegateUse(boolean b)

Sets whether the connection may be recycled if the underlying raw/delegate connection has been used (default: false).

Each CacheConnection instance tracks whether a call to CacheConnection.getDelegateConnection() has been made, and by default prevents recycling of the connection if so, in order to help maintain integrity of the pool. In certain circumstances it may be beneficial in terms of performance to enable such recycling, provided the raw connections are not compromised in any way, and the CacheConnection.close() method is called on each CacheConnection instance and NOT the raw connection.

Parameters:

b - whether connections are recycled after use of underlying delegate connection

isRecycleAfterDelegateUse

public boolean isRecycleAfterDelegateUse()

Returns whether connections may be recycled if the underlying raw/delegate connection has been used.

Returns:

true if connections are recycled after delegate connection use, false otherwise

getMinimumCleaningInterval

protected long getMinimumCleaningInterval()

Specifies the minimum time interval between cleaning attempts of the Cleaner thread.

Overrides:

getMinimumCleaningInterval in class ObjectPool<CacheConnection>

Returns:

The minimum time interval between cleaning attempts of the Cleaner thread

getMaximumCleaningInterval

protected long getMaximumCleaningInterval()

Specifies the maximum time interval between cleaning attempts of the Cleaner thread.

Overrides:

getMaximumCleaningInterval in class ObjectPool<CacheConnection>

Returns:

The maximum time interval between cleaning attempts of the Cleaner thread

addConnectionPoolListener

public final void addConnectionPoolListener(ConnectionPoolListener listener)

Adds a ConnectionPoolListener to the event notification list.

Parameters:

listener - listener to add

removeConnectionPoolListener

public final void removeConnectionPoolListener(ConnectionPoolListener listener)

Removes a ConnectionPoolListener from the event notification list.

Parameters:

listener - listener to remove