org.sadun.util.pool.connection
Class ConnectionPool

java.lang.Object
  org.sadun.util.pool.connection.ConnectionPool

public class ConnectionPool

extends java.lang.Object

A pool of SQL connections. The connections must not be closed before being returned to the pool, unless #isTestBeforeAcquiring() is true.

If that is the case, a test is performed on the connection before releasing it to the client code (when it invokes getConnection()). Note that this can impair performance if connections are requested often.

The pool can also be associated to a watchdog thread (by using setWatchDogEnabled(() and setWatchDogCheckPeriodTime(), which periodically checks the state of the pool by picking up a connection and testing it.

On termination, the pool should be destroyed by invoking destroy() which terminates the watchdog thread and closes the connections (see also org.sadun.util.pool.ObjectPool.destroy()).

Author:

Cristiano Sadun

Constructor Summary

ConnectionPool(int n, javax.sql.DataSource dataSource)
Create a pool of n connections to the given DataSource.

ConnectionPool(int n, java.lang.String jdbcUrl)
Create a pool of n connections to the given JDBC URL.

ConnectionPool(int n, java.lang.String jdbcUrl, java.util.Properties connectionProperties)
Create a pool of n connections to the given JDBC URL using the given connection properties.

Method Summary

void	addListener(WatchDog.Listener l) Register a listener for the watchdog thread, if enabled.
void	destroy(boolean waitForReleasedObject) Destroy any resource associated to the pool, closing all the pooled connections.
java.sql.Connection	getConnection() Retrieves a connection from the pool.
int	getFreeCount() Return the number of available connections in the pool
java.lang.String	getJdbcUrl() Return the JDBC url to which this pool connects.
int	getMaxGetRetry() Return the maximum number of retry attempts before getConnection() stops and returns null (applies only if isTestBeforeAcquiring() is true).
int	getSize() Return the size of the pool
int	getUsedCount() Return the number of used objects in the pool
long	getWatchDogCheckPeriodTime() Return the amount of time the watchdog waits between each check (if the watchdog is enabled).
boolean	isTestBeforeAcquiring() Return true if getConnection() tests the connection before returning it, else false.
boolean	isWatchDogEnabled()
void	releaseConnection(java.sql.Connection conn) Return the given connection to the pool.
void	removeListener(WatchDog.Listener l) Deregister a listener for the watchdog thread, if enabled.
void	setMaxGetRetry(int maxGetRetry) Set the maximum number of retry attempts before getConnection() stops and returns null (applies only if isTestBeforeAcquiring() is true).
void	setTestBeforeAcquiring(boolean testBeforeAcquiring) Set wether or not getConnection() tests the connection before returning it.
void	setWatchDogCheckPeriodTime(long watchDogCheckPeriodTime) Set the amount of time the watchdog waits between each check (if the watchdog is enabled).
void	setWatchDogEnabled(boolean v) Enable or disable the watchdog thread associated to this connection pool, which periodically checks the state of the pool.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionPool

public ConnectionPool(int n,
                      java.lang.String jdbcUrl,
                      java.util.Properties connectionProperties)

Create a pool of n connections to the given JDBC URL using the given connection properties.

Parameters:

n - the size of the pool

jdbcUrl - the JDBC URL for the connection

connectionProperties - the connection properties to use

Throws:

{@link - ObjectPool.ObjectPoolException ObjectPoolException} if the connections cannot be created

ConnectionPool

public ConnectionPool(int n,
                      java.lang.String jdbcUrl)

Create a pool of n connections to the given JDBC URL.

Parameters:

n - the size of the pool

jdbcUrl - the JDBC URL for the connection

Throws:

{@link - ObjectPool.ObjectPoolException ObjectPoolException} if the connections cannot be created

ConnectionPool

public ConnectionPool(int n,
                      javax.sql.DataSource dataSource)

Create a pool of n connections to the given DataSource.

Note that DataSource implementations often already pool connections.

Parameters:

n - the size of the pool

dataSource - the data source to use

Throws:

{@link - ObjectPool.ObjectPoolException ObjectPoolException} if the connections cannot be created

Method Detail

getConnection

public java.sql.Connection getConnection()
                                  throws ObjectPool.ObjectPoolException

Retrieves a connection from the pool.

If isTestBeforeAcquiring() is true doTest() is invoked before actually returning the connection object.

Returns:

a connection, or null if a working connection cannot be obtained.

Throws:

ObjectPool.ObjectPoolException

releaseConnection

public void releaseConnection(java.sql.Connection conn)

Return the given connection to the pool.

Parameters:

conn - the connection to return.

isTestBeforeAcquiring

public boolean isTestBeforeAcquiring()

Return true if getConnection() tests the connection before returning it, else false.

Returns:

true if getConnection() tests the connection before returning it, else false.

setTestBeforeAcquiring

public void setTestBeforeAcquiring(boolean testBeforeAcquiring)

Set wether or not getConnection() tests the connection before returning it.

Parameters:

testBeforeAcquiring - true if the connection has to be tested.

getMaxGetRetry

public int getMaxGetRetry()

Return the maximum number of retry attempts before getConnection() stops and returns null (applies only if isTestBeforeAcquiring() is true).

Returns:

the maximum number of retry attempts before getConnection() stops and returns null (applies only if isTestBeforeAcquiring() is true).

setMaxGetRetry

public void setMaxGetRetry(int maxGetRetry)

Set the maximum number of retry attempts before getConnection() stops and returns null (applies only if isTestBeforeAcquiring() is true).

Parameters:

maxGetRetry - the maximum number of retry attempts before getConnection() stops and returns null (applies only if isTestBeforeAcquiring() is true).

addListener

public void addListener(WatchDog.Listener l)

Register a listener for the watchdog thread, if enabled.

Parameters:

l - the WatchDog.Listener to register.

removeListener

public void removeListener(WatchDog.Listener l)

Deregister a listener for the watchdog thread, if enabled.

Parameters:

l - the WatchDog.Listener to deregister.

setWatchDogEnabled

public void setWatchDogEnabled(boolean v)

Enable or disable the watchdog thread associated to this connection pool, which periodically checks the state of the pool.

Parameters:

v - if true enables and starts the watchdog, else, disables it.

isWatchDogEnabled

public boolean isWatchDogEnabled()

getWatchDogCheckPeriodTime

public long getWatchDogCheckPeriodTime()

Return the amount of time the watchdog waits between each check (if the watchdog is enabled).

Returns:

the amount of time the watchdog waits between each check (if the watchdog is enabled).

setWatchDogCheckPeriodTime

public void setWatchDogCheckPeriodTime(long watchDogCheckPeriodTime)

Set the amount of time the watchdog waits between each check (if the watchdog is enabled).

Parameters:

watchDogCheckPeriodTime - the amount of time the watchdog waits between each check (if the watchdog is enabled).

getJdbcUrl

public java.lang.String getJdbcUrl()

Return the JDBC url to which this pool connects.

Returns:

the JDBC url to which this pool connects.

destroy

public void destroy(boolean waitForReleasedObject)

Destroy any resource associated to the pool, closing all the pooled connections.

Parameters:

waitForReleasedObject - if true the pool will wait until all connections are released before closing them.

getFreeCount

public int getFreeCount()

Return the number of available connections in the pool

Returns:

the number of available connections in the pool

getUsedCount

public int getUsedCount()

Return the number of used objects in the pool

Returns:

the number of used objects in the pool

getSize

public int getSize()

Return the size of the pool

Returns:

the size of the pool