net.sourceforge.esw.util.database
Class DBConnectionPool

java.lang.Object
  |
  +--net.sourceforge.esw.util.database.DBConnectionPool

public class DBConnectionPool

extends java.lang.Object

A pool of java.sql.Connection instances to optimize connection to a JDBC data source.

A database connection pool greatly simplifies many of the common tasks associated with JDBC database access. It lets you use the connections without worrying about the maintainance or scalability of your database access. The DBConnectionPool instance lets you interact with your JDBC connections as standard java.sql.Connection instances, instead of making you use some non-standard api for interaction. This allows the developer to have greater flexibility for implemention by reducing the overhead for learning and integrating.

A DBConnectionPool instance has a URL and, if required, a UserID that can be used to uniquely identify the source data that the connection represents. Some databases allow the UserID and/or Password to be specified in the URL. Some do not require secure access, so neither the UserID or Password is required to use a DBConnectionPool instance.

A DBConnectionPool instance does not initialize the database driver directly, but the DBConnectionPoolManager has a method to initialize the driver for you called initializeDriver( aDriver ). You can also follow the JDBC standard method for registering your JDBC driver in the Java VM using the DriverManager. You should only need to register a unique driver once during a Java VM session.

To use a DBConnectionPool instance, see the getPool method of the DBConnectionPoolManager singleton.

Examples:

   DBConnectionPoolManager.initializeDriver( aDriver );
   DBConnectionPool pl = DBConnectionPoolManager.getInstance().getPool( getURL(),
                                                                        getUserID() );
   pl.setDatabasePassword( getPassword() );
   connection = pl.getDBConnection();

   PreparedStatement ps = connection.prepareStatement( getSQLStatement );
 

Field Summary

protected java.util.ArrayList	availDBConnections The ArrayList instance that holds the availibleConnections.
protected boolean	bHoldUntilConnectionAvailable Specifies whether the getDBConnection method should wait when the maximum number of allowed connections is reached.
protected boolean	bLogging Specifies if database calls are logged to DriverManager's LogWriter.
protected boolean	bWaitingForConnection Specifies if a client is waiting for an availiable connection.
protected java.lang.String	databaseURL The URL used for database access.
protected java.lang.String	defaultDatabasePassword The password used for database access.
protected java.util.Properties	defaultDatabaseProperties The properties used for database access.
protected java.lang.String	defaultDatabaseUserID The UserID used for database access.
protected int	maxSize The maximum number of database connections to allow opened at once.
protected int	preferredSize The optimal number of database connections to be opened at once.
protected java.util.ArrayList	usedDBConnections The ArrayList instance that holds the usedConnections.

Constructor Summary

DBConnectionPool(java.lang.String dbURL)
Creates a new DBConnectionPool instance.

DBConnectionPool(java.lang.String dbURL, java.util.Properties dbProp)
Creates a new DBConnectionPool instance.

DBConnectionPool(java.lang.String dbURL, java.util.Properties dbProp, boolean startup)
Creates a new DBConnectionPool instance.

DBConnectionPool(java.lang.String dbURL, java.lang.String userid, java.lang.String passwd)
Creates a new DBConnectionPool instance.

DBConnectionPool(java.lang.String dbURL, java.lang.String userid, java.lang.String passwd, boolean startup)
Creates a new DBConnectionPool instance.

DBConnectionPool(java.lang.String dbURL, java.lang.String userid, java.lang.String passwd, java.util.Properties dbProp, boolean startup)
Creates a new DBConnectionPool instance.

Method Summary

protected void	closeConnection(java.sql.Connection conn) Closes a Connection instance.
void	closeCurrentConnections() Closes all current available and used Database Connections.
protected java.sql.Connection	createDatabaseConnection() Creates a new Connection instance, wrapping the connection in an adapter to provide all the pooled connection abilites.
int	getAvailablePoolSize() Returns the number of available Database Connections.
boolean	getDatabaseLogging() Returns if database logging is enabled.
java.lang.String	getDatabasePassword() Returns the JDBC Database Connection Password Value.
java.util.Properties	getDatabaseProperties() Returns the JDBC Database Connection Properties Value.
java.lang.String	getDatabaseURL() Returns the JDBC Database Connection URL value.
java.lang.String	getDatabaseUserID() Returns the JDBC Database Connection User ID Value.
java.sql.Connection	getDBConnection() Returns a java.sql.Connection instance from the DBConnectionPool instance.
protected java.sql.Connection	getDirectDatabaseConnection() Creates a new Connection instance, directly connected to the database.
boolean	getHoldUntilConnectionAvailable() Returns whether this DBConnectionPool will cause the client to wait when a request is made for a new database connection, but there are none available to return and the maximum size has been reached.
int	getMaxSize() Returns the Maximum Size for this DBConnectionPool.
int	getPreferredSize() Returns the preferred number of connections in the pool for this DBConnectionPool.
int	getUsedPoolSize() Returns the number of used Database Connections.
void	releaseDBConnection(java.sql.Connection theConnection) Releases a Connection instance back into the pool.
void	setDatabaseLogging(boolean value) Turning on Database Logging causes all calls by Statements against the database to log to DriverManager's LogWriter
void	setDatabasePassword(java.lang.String value) Sets the value for the Password used for database access.
void	setDatabaseProperties(java.util.Properties value) Sets the value for the Properties used for database access.
void	setDatabaseURL(java.lang.String value) Sets the value for the URL used for database access.
void	setDatabaseUserID(java.lang.String value) Sets the value for the UserID used for database access.
void	setHoldUntilConnectionAvailable(boolean value) Sets a value for checks to see if the DBConnectionPool instance should always wait to return a available connection from a call to getDBConnection().
void	setMaxSize(int value) Sets the maximum number of concurrent connections to the database from this DBConnectionPool intstance.
void	setPreferredSize(int value) Sets the optimal number of concurrent connections to the database from this DBConnectionPool instance.
void	startupDatabaseConnections() Initializes all the database connections, up to the preferred size size setting.

Methods inherited from class java.lang.Object

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

Field Detail

availDBConnections

protected java.util.ArrayList availDBConnections

The ArrayList instance that holds the availibleConnections.

usedDBConnections

protected java.util.ArrayList usedDBConnections

The ArrayList instance that holds the usedConnections.

databaseURL

protected java.lang.String databaseURL

The URL used for database access. Required for access to the database.

defaultDatabaseUserID

protected java.lang.String defaultDatabaseUserID

The UserID used for database access. Optional.

defaultDatabasePassword

protected java.lang.String defaultDatabasePassword

The password used for database access. Optional.

defaultDatabaseProperties

protected java.util.Properties defaultDatabaseProperties

The properties used for database access. Optional.

maxSize

protected int maxSize

The maximum number of database connections to allow opened at once. The default is Integer.MAX_VALUE.

preferredSize

protected int preferredSize

The optimal number of database connections to be opened at once. The default value is 1.

bHoldUntilConnectionAvailable

protected boolean bHoldUntilConnectionAvailable

Specifies whether the getDBConnection method should wait when the maximum number of allowed connections is reached.

bWaitingForConnection

protected boolean bWaitingForConnection

Specifies if a client is waiting for an availiable connection.

bLogging

protected boolean bLogging

Specifies if database calls are logged to DriverManager's LogWriter.

Constructor Detail

DBConnectionPool

public DBConnectionPool(java.lang.String dbURL)
                 throws java.sql.SQLException

Creates a new DBConnectionPool instance.

Parameters:

dbURL - The URL used for database access.

Throws:

java.sql.SQLException - If a connection to the database can't be made.

DBConnectionPool

public DBConnectionPool(java.lang.String dbURL,
                        java.util.Properties dbProp)
                 throws java.sql.SQLException

Creates a new DBConnectionPool instance.

Parameters:

dbURL - The URL used for database access.

dbProp - The properties used for database access.

Throws:

java.sql.SQLException - If a connection to the database can't be made.

DBConnectionPool

public DBConnectionPool(java.lang.String dbURL,
                        java.util.Properties dbProp,
                        boolean startup)
                 throws java.sql.SQLException

Creates a new DBConnectionPool instance.

Parameters:

dbURL - The URL used for database access.

dbProp - The properties used for database access.

startup - If the connections should be initialized.

Throws:

java.sql.SQLException - If a connection to the database can't be made.

DBConnectionPool

public DBConnectionPool(java.lang.String dbURL,
                        java.lang.String userid,
                        java.lang.String passwd)
                 throws java.sql.SQLException

Creates a new DBConnectionPool instance.

Parameters:

dbURL - The URL used for database access.

userid - The UserID used for database access.

passwd - The password used for database access.

Throws:

java.sql.SQLException - If a connection to the database can't be made.

DBConnectionPool

public DBConnectionPool(java.lang.String dbURL,
                        java.lang.String userid,
                        java.lang.String passwd,
                        boolean startup)
                 throws java.sql.SQLException

Creates a new DBConnectionPool instance.

Parameters:

dbURL - The URL used for database access.

userid - The UserID used for database access.

passwd - The password used for database access.

startup - If the connections should be initialized.

Throws:

java.sql.SQLException - If a connection to the database can't be made.

DBConnectionPool

public DBConnectionPool(java.lang.String dbURL,
                        java.lang.String userid,
                        java.lang.String passwd,
                        java.util.Properties dbProp,
                        boolean startup)
                 throws java.sql.SQLException

Creates a new DBConnectionPool instance.

Parameters:

dbURL - The URL used for database access.

userid - The UserID used for database access.

passwd - The password used for database access.

dbProp - The properties used for database access.

startup - If the connections should be initialized.

Throws:

java.sql.SQLException - If a connection to the database can't be made.

Method Detail

setDatabaseURL

public void setDatabaseURL(java.lang.String value)

Sets the value for the URL used for database access.

Parameters:

value - The new database URL value.

setDatabaseUserID

public void setDatabaseUserID(java.lang.String value)

Sets the value for the UserID used for database access.

Parameters:

value - The new Default Database UserID value to use.

setDatabasePassword

public void setDatabasePassword(java.lang.String value)

Sets the value for the Password used for database access.

Parameters:

value - The new defaultDatabasePassword value to use.

setDatabaseProperties

public void setDatabaseProperties(java.util.Properties value)

Sets the value for the Properties used for database access.

Parameters:

value - The new defaultDatabaseProperties value to use.

setMaxSize

public void setMaxSize(int value)

Sets the maximum number of concurrent connections to the database from this DBConnectionPool intstance. If maximum size is lower than preferred size, then the preferred size will be reduced to match maximum size.

Parameters:

value - The new maximum size value to use.

setPreferredSize

public void setPreferredSize(int value)

Sets the optimal number of concurrent connections to the database from this DBConnectionPool instance. If the number of connections exceeds this value, then returned connections will be closed. The maximum size of the Pool overrides this value, if maximum size is lower than the preferred size, then the preferred size will be reduced to match maximum size.

Parameters:

value - The new preferred size value to use.

setHoldUntilConnectionAvailable

public void setHoldUntilConnectionAvailable(boolean value)

Sets a value for checks to see if the DBConnectionPool instance should always wait to return a available connection from a call to getDBConnection().

Parameters:

value - The new hold until a connection is available value.

setDatabaseLogging

public void setDatabaseLogging(boolean value)

Turning on Database Logging causes all calls by Statements against the database to log to DriverManager's LogWriter

Parameters:

value - The new logging value.

getDatabaseURL

public java.lang.String getDatabaseURL()

Returns the JDBC Database Connection URL value.

Returns:

The JDBC Database Connection URL value.

getDatabaseUserID

public java.lang.String getDatabaseUserID()

Returns the JDBC Database Connection User ID Value.

Returns:

The JDBC Database Connection User ID Value.

getDatabasePassword

public java.lang.String getDatabasePassword()

Returns the JDBC Database Connection Password Value.

Returns:

The JDBC Database Connection Password Value.

getDatabaseProperties

public java.util.Properties getDatabaseProperties()

Returns the JDBC Database Connection Properties Value.

Returns:

The JDBC Database Connection Properties Value.

getMaxSize

public int getMaxSize()

Returns the Maximum Size for this DBConnectionPool. When new connections are created, the total number of connections in the pool will never exceed the Maximum Size.

Returns:

The Maximum Size for this DBConnectionPool.

getPreferredSize

public int getPreferredSize()

Returns the preferred number of connections in the pool for this DBConnectionPool. When the connections are initialized, the number of connections created will equal the preferred size. When connections are returned to the pool, the pool will close any connections returned when the pool size has already reached the preferred size.

Returns:

The preferred number of connections in the pool for this DBConnectionPool.

getHoldUntilConnectionAvailable

public boolean getHoldUntilConnectionAvailable()

Returns whether this DBConnectionPool will cause the client to wait when a request is made for a new database connection, but there are none available to return and the maximum size has been reached.

Returns:

If this DBConnectionPool will block the client thread until a connection is available.

getDatabaseLogging

public boolean getDatabaseLogging()

Returns if database logging is enabled. Turning on Database Logging causes all calls by Statements against the database to log the DriverManager LogWriter.

Returns:

If database logging is enabled.

getDBConnection

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

Returns a java.sql.Connection instance from the DBConnectionPool instance. If there are available database connections, then a connection from the available pool is returned. If there are no available connections, then a connection is created, until the database reaches the maximum size. Once the maxSize is reached, then the behavior depends on if HoldUntilConnectionAvailable is set to true or false. If true, it will hold until a connection is ready, then a call to this method won't return until there is an available connection. Otherwide, it will return a null value.

Returns:

a Connection instance, or null if the number of connections is at maxSize and HoldUntilConnectionAvailable is set to false.

Throws:

java.sql.SQLException - If unable to make a connection if a new Connection instance needs to be created or if the number of connections is at maxSize and HoldUntilConnectionAvailable is set to false.

getAvailablePoolSize

public int getAvailablePoolSize()

Returns the number of available Database Connections.

Returns:

The number of available Database Connections.

getUsedPoolSize

public int getUsedPoolSize()

Returns the number of used Database Connections.

Returns:

The number of used Database Connections.

releaseDBConnection

public void releaseDBConnection(java.sql.Connection theConnection)

Releases a Connection instance back into the pool.

Parameters:

theConnection - The Connection instance to be returned.

closeCurrentConnections

public void closeCurrentConnections()

Closes all current available and used Database Connections.

startupDatabaseConnections

public void startupDatabaseConnections()
                                throws java.sql.SQLException

Initializes all the database connections, up to the preferred size size setting.

Throws:

java.sql.SQLException - Indicates there is a problem creating the connection.

closeConnection

protected void closeConnection(java.sql.Connection conn)
                        throws java.sql.SQLException

Closes a Connection instance. If it is a pooled connection, closes the contained connection.

Throws:

java.sql.SQLException - Indicates there is a problem closing the connection.

createDatabaseConnection

protected java.sql.Connection createDatabaseConnection()
                                                throws java.sql.SQLException

Creates a new Connection instance, wrapping the connection in an adapter to provide all the pooled connection abilites.

Returns:

A connection to the database.

Throws:

java.sql.SQLException - Indicates there is a problem creating the connection.

getDirectDatabaseConnection

protected java.sql.Connection getDirectDatabaseConnection()
                                                   throws java.sql.SQLException

Creates a new Connection instance, directly connected to the database.

Returns:

A connection to the database.

Throws:

java.sql.SQLException - Indicates there is a problem creating the connection.