snaq.db
Class ConnectionPool

java.lang.Object
  snaq.util.ObjectPool<CacheConnection>
      snaq.db.ConnectionPool

All Implemented Interfaces:

Comparable<ObjectPool>

public class ConnectionPool
extends ObjectPool<CacheConnection>

Implementation of a database connection pool.

Author:

Giles Winstanley

See Also:

CacheConnection, CachedCallableStatement, CachedPreparedStatement

Field Summary

Fields inherited from class snaq.util.ObjectPool

logger

Constructor Summary

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

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.
int	getPoolSize() Deprecated. Use ObjectPool.getMaxPool() instead.
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.
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.
protected void	setPoolAccessFIFO() Sets the pool access method to FIFO (first-in, first-out: a queue).
protected void	setPoolAccessLIFO() Sets the pool access method to LIFO (last-in, first-out: a stack).
protected void	setPoolAccessRandom() Sets the pool access method to random (a random connection is selected for check-out).
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, getExpiryTime, getFreeCount, getHitRate, 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, preRelease, registerShutdownHook, release, releaseAsync, releaseForcibly, removeObjectPoolListener, removeShutdownHook, resetHitCounter, setAccessFIFO, setAccessLIFO, setAccessRandom, setAsyncDestroy, setLog, setParameters, setParameters, 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>

Throws:

SQLException

isValid

protected boolean isValid(CacheConnection cc)

Validates a CacheConnection object.

Specified by:

isValid in class ObjectPool<CacheConnection>

getPoolSize

@Deprecated
public final int getPoolSize()

Deprecated. Use ObjectPool.getMaxPool() instead.

Returns the maximum number of items that can be pooled. Moved from ObjectPool class to here, and maintained only for backwards-compatibility.

setValidator

public void setValidator(ConnectionValidator cv)

Sets the validator class for Connection instances.

getValidator

public ConnectionValidator getValidator()

Returns the current ConnectionValidator class.

setPasswordDecoder

public void setPasswordDecoder(PasswordDecoder pd)

Sets the PasswordDecoder class.

getPasswordDecoder

public PasswordDecoder getPasswordDecoder()

Returns the current PasswordDecoder class.

destroy

protected void destroy(CacheConnection cc)

Closes the specified CacheConnection object.

Specified by:

destroy in class ObjectPool<CacheConnection>

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().

Throws:

SQLException

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>

setCaching

public void setCaching(boolean b)

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

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.

isCachingPreparedStatements

public boolean isCachingPreparedStatements()

Returns whether the pool caches PreparedStatement instances for each connection.

isCachingCallableStatements

public boolean isCachingCallableStatements()

Returns whether the pool caches CallableStatement instances for each connection.

setPoolAccessFIFO

protected final void setPoolAccessFIFO()

Sets the pool access method to FIFO (first-in, first-out: a queue).

setPoolAccessLIFO

protected final void setPoolAccessLIFO()

Sets the pool access method to LIFO (last-in, first-out: a stack).

setPoolAccessRandom

protected final void setPoolAccessRandom()

Sets the pool access method to random (a random connection is selected for check-out).

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.

isRecycleAfterDelegateUse

public boolean isRecycleAfterDelegateUse()

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

getMinimumCleaningInterval

protected long getMinimumCleaningInterval()

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

Overrides:

getMinimumCleaningInterval in class ObjectPool<CacheConnection>

getMaximumCleaningInterval

protected long getMaximumCleaningInterval()

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

Overrides:

getMaximumCleaningInterval in class ObjectPool<CacheConnection>

addConnectionPoolListener

public final void addConnectionPoolListener(ConnectionPoolListener listener)

Adds a ConnectionPoolListener to the event notification list.

removeConnectionPoolListener

public final void removeConnectionPoolListener(ConnectionPoolListener listener)

Removes a ConnectionPoolListener from the event notification list.