org.pajes.db
Class ConnectionPool

java.lang.Object
  org.pajes.db.ConnectionPool

All Implemented Interfaces:

java.lang.Runnable

public class ConnectionPool

extends java.lang.Object

implements java.lang.Runnable

Opens and maintains a thread-safe pool of JDBC connections. The ConnectionPool will open initially open a specified number of database connections. Connections are issued from the pool by the getConnection() method and returned to the pool by calling the close method on the Connection. Should all connections be in use when a request for a connection is made, an additional connection will be opened unless the maximum number of connections has been reached, in which case the connectionPool will wait for a connection to be released. The connection pool monitors free connections for their viability via a low priority daemon thread. If the check fails, the connection is removed from the pool.

Constructor Summary

ConnectionPool(java.lang.String jdbcDriverClass, java.lang.String dbServerURL, int numInitialConnections, int maxConnections, java.lang.String user, java.lang.String password, long connectionTimeout, long retryInterval)
Create a connection pool.

Method Summary

protected void	destroy() Shuts down this connection pool by closing all connections and terminating the background thread.
java.sql.Connection	getConnection() Retrieves a free connection from the connection pool.
java.sql.Connection	getConnection(java.lang.String user, java.lang.String password) Creates a new connection that is NOT pooled.
long	getConnectionTimeout() Returns the maximum number of milliseconds to wait for a free connection to become available.
java.lang.String	getDatabaseServerURL() Obtain the URL of the database server serving this pool.
int	getFreeConnectionCount() Determine the number of free connections in the free pool.
protected long	getFreeConnectionRetryInterval() Returns the number of millseconds that will be allowed to elapse before an another attempt is made to obtain a connection from the free pool, after an attempt was made and the free pool was empty.
protected long	getFreeConnectionTimeOut() Returns the number of millseconds that will be allowed to elapse before no more attempts are made to obtain a connection from an empty free pool.
java.sql.Driver	getJDBCDriver() Obtain the JDBC driver for this pool.
protected java.sql.Driver	getJDBCDriver(boolean newInstance) Obtain the JDBC driver for this pool.
java.lang.String	getJDBCDriverClassName() Obtain the URL of the JDBC driver for this pool.
int	getMaxConnections() Returns the maximum number of connections that will be simultaneously allowed to access the database server.
long	getMaxUnusedTime() Returns the maximum number of milliseconds that a connection may remain on the free pool without being used before it is physically closed.
int	getMaxUsageCount() Returns the maximum number of times a physical connection may be re-used before it becomes stale and is physically closed.
int	getOpenConnectionCount() Returns the number of currently open connections.
long	getRetryInterval() Returns the number of milliseconds between checking for a free connection.
protected void	init() Opens the initial connections and starts the background thread.
protected boolean	releaseConnection(org.pajes.db.ConnectionWrapper dbConnection) Called by ConnectionWrapper#close to remove itself from the open pool, and either release it to the free pool, or to flag it as stale and requiring to be physically closed.
protected boolean	releaseConnection(java.lang.Thread thread) Releases all connections opened by a Thread back to the free pool.
void	run() Runs as a low priority daemon thread, checking free connections to ensure that they are still viable, and if not, removes them from the free pool.
void	setConnectionTimeout(long milliseconds) Sets the maximum number of milliseconds to wait for a free connection to become available.
void	setDestroySQL(java.lang.String sql) Sets the SQL that will be called during pool destruction processing.
void	setMaxConnections(int max) Sets the maximum number of connections that this pool may simultaneously open.
void	setMaxUnusedTime(long milliseconds) Sets the maximum number of milliseconds that a connection may remain on the free pool without being used before it is physically closed.
void	setMaxUsageCount(int max) Sets the maximum number of times a physical connection may be re-used before it becomes stale and is physically closed.
void	setRetryInterval(long milliseconds) Sets the number of milliseconds between checking for a free connection.
java.lang.String	toString() Returns a String representation of this connection pool.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionPool

public ConnectionPool(java.lang.String jdbcDriverClass,
                      java.lang.String dbServerURL,
                      int numInitialConnections,
                      int maxConnections,
                      java.lang.String user,
                      java.lang.String password,
                      long connectionTimeout,
                      long retryInterval)
               throws java.lang.ClassNotFoundException,
                      java.sql.SQLException

Create a connection pool. After the pool has been created, it must be initialised. Pools are normally created via the ConnectionManagercreatePool() methods.

Parameters:

jdbcDriverClass - The jdbc driver class name.

dbServerURL - The address of a jdbc data source.

numInitialConnections - The number of connections to initially open and cache.

maxConnections - The maximum number of connections to open.

user - The database userid to use to open connections.

password - The database password to use to open connections.

connectionTimeout - The number of milliseconds to wait for a free connection to become available.

retryInterval - The number of milliseconds between checking for a free connection.

Throws:

java.lang.ClassNotFoundException - if the specified JDBC Driver class cannot be found.

java.sql.SQLException - if an exception occurs accessing the database.

Method Detail

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException

Retrieves a free connection from the connection pool.

Returns:

the Connection object on which commands may be executed.

Throws:

java.sql.SQLException - if an exception occurs accessing the database.

ConnectionPoolTimeOutException - if a connection is not obtained within the time-out period.

getConnection

public java.sql.Connection getConnection(java.lang.String user,
                                         java.lang.String password)
                                  throws java.sql.SQLException

Creates a new connection that is NOT pooled. When the connection is closed, it will NOT be returned to the pool.

Parameters:

user - The database userid to use to open the connection.

password - The database password to use to open the connection.

Returns:

the Connection object on which commands may be executed.

Throws:

java.sql.SQLException - if an exception occurs accessing the database.

setConnectionTimeout

public void setConnectionTimeout(long milliseconds)

Sets the maximum number of milliseconds to wait for a free connection to become available.

Parameters:

milliseconds - the maximum number of milliseconds to wait for a free connection to become available.

getConnectionTimeout

public long getConnectionTimeout()

Returns the maximum number of milliseconds to wait for a free connection to become available.

Returns:

the maximum number of milliseconds to wait for a free connection to become available.

getDatabaseServerURL

public java.lang.String getDatabaseServerURL()

Obtain the URL of the database server serving this pool.

Returns:

the URL of the database server serving this pool.

setDestroySQL

public void setDestroySQL(java.lang.String sql)

Sets the SQL that will be called during pool destruction processing.

Parameters:

sql - the String of SQL to be executed before the pool is destroyed.

getFreeConnectionCount

public int getFreeConnectionCount()

Determine the number of free connections in the free pool.

Returns:

the number of free connections in the free pool.

getJDBCDriver

public java.sql.Driver getJDBCDriver()
                              throws java.sql.SQLException

Obtain the JDBC driver for this pool.

Returns:

the URL of the JDBC driver for this pool.

Throws:

java.sql.SQLException - if an exception occurs accessing the database.

getJDBCDriverClassName

public java.lang.String getJDBCDriverClassName()

Obtain the URL of the JDBC driver for this pool.

Returns:

the URL of the JDBC driver for this pool.

setMaxConnections

public void setMaxConnections(int max)

Sets the maximum number of connections that this pool may simultaneously open.

Parameters:

max - the maximum number of connections that this pool may simultaneously open.

getMaxConnections

public int getMaxConnections()

Returns the maximum number of connections that will be simultaneously allowed to access the database server.

Returns:

the maximum number of connections that will be simultaneously allowed to access the database server.

setMaxUnusedTime

public void setMaxUnusedTime(long milliseconds)

Sets the maximum number of milliseconds that a connection may remain on the free pool without being used before it is physically closed.

Parameters:

milliseconds - the maximum number of milliseconds that a connection may remain on the free pool without being used.

getMaxUnusedTime

public long getMaxUnusedTime()

Returns the maximum number of milliseconds that a connection may remain on the free pool without being used before it is physically closed.

Returns:

the maximum number of milliseconds that a connection may remain on the free pool without being used.

setMaxUsageCount

public void setMaxUsageCount(int max)

Sets the maximum number of times a physical connection may be re-used before it becomes stale and is physically closed.

Parameters:

max - the maximum number of connections times a physical connection may be re-used.

getMaxUsageCount

public int getMaxUsageCount()

Returns the maximum number of times a physical connection may be re-used before it becomes stale and is physically closed.

Returns:

the maximum number of connections times a physical connection may be re-used.

getOpenConnectionCount

public int getOpenConnectionCount()

Returns the number of currently open connections.

Returns:

the number of currently open connections.

setRetryInterval

public void setRetryInterval(long milliseconds)

Sets the number of milliseconds between checking for a free connection.

Parameters:

milliseconds - the number of milliseconds between checking for a free connection.

getRetryInterval

public long getRetryInterval()

Returns the number of milliseconds between checking for a free connection.

Returns:

the number of milliseconds between checking for a free connection.

run

public void run()

Runs as a low priority daemon thread, checking free connections to ensure that they are still viable, and if not, removes them from the free pool. Also removes any additional connections that have been opened (above the initial allocation) that have not been used for a period of time.

Specified by:

run in interface java.lang.Runnable

toString

public java.lang.String toString()

Returns a String representation of this connection pool.

Returns:

A String representation of this connection pool.

getFreeConnectionRetryInterval

protected long getFreeConnectionRetryInterval()

Returns the number of millseconds that will be allowed to elapse before an another attempt is made to obtain a connection from the free pool, after an attempt was made and the free pool was empty.

Returns:

the number of milliseconds.

getFreeConnectionTimeOut

protected long getFreeConnectionTimeOut()

Returns the number of millseconds that will be allowed to elapse before no more attempts are made to obtain a connection from an empty free pool.

Returns:

the number of milliseconds.

getJDBCDriver

protected java.sql.Driver getJDBCDriver(boolean newInstance)
                                 throws java.lang.ClassNotFoundException,
                                        java.sql.SQLException

Obtain the JDBC driver for this pool.

Parameters:

newInstance - true if any existing instance of the driver is to be replaced with a new instance, or false to return the existing instance.

Returns:

the URL of the JDBC driver for this pool.

Throws:

java.lang.ClassNotFoundException - if the specified JDBC driver class cannot be found.

java.sql.SQLException - if an exception occurs accessing the database.

destroy

protected void destroy()
                throws java.sql.SQLException

Shuts down this connection pool by closing all connections and terminating the background thread. Any SQL specified via setDestroySQL(java.lang.String) is executed on a new connection after all other connections have been closed.

Sub-classes MUST ensure that super.destroy() is called to correctly close all open connections and clean up the pool.

Called by ConnectionManager.destroyPool(java.lang.String).

Throws:

java.sql.SQLException - if an exception occurs accessing the database.

init

protected void init()

Opens the initial connections and starts the background thread.

Sub-classes MUST ensure that super.init() is called to correctly initialise the pool.

Called by ConnectionManager.registerPool(java.lang.String, org.pajes.db.ConnectionPool, java.lang.String).

releaseConnection

protected boolean releaseConnection(java.lang.Thread thread)

Releases all connections opened by a Thread back to the free pool.

Parameters:

thread - the Thread which opened the connections.

Returns:

true if any connections were found to be released.

releaseConnection

protected boolean releaseConnection(org.pajes.db.ConnectionWrapper dbConnection)
                             throws java.sql.SQLException

Called by ConnectionWrapper#close to remove itself from the open pool, and either release it to the free pool, or to flag it as stale and requiring to be physically closed.

Parameters:

dbConnection - the connection object.

Returns:

true if the connection was released back to the free pool, or false if the connection is stale and should be physically closed.

Throws:

java.sql.SQLException - if an exception occurs accessing the database.

ConnectionPoolException - if the connection could not be removed from the open pool.