| Class to provide access and management for multiple connection pools
defined in a properties file or object.
Clients get access to each defined instance through one of the
static getInstance() methods and can then check-out and check-in
database connections from the pools defined by that manager.
Each successful call to a getInstance() method also increments
an internal counter which keeps a record of the number of clients which hold
a reference to that particular pool manager. When each client has finished
using a pool manager it should call the release() method to
let the manager know that it is no longer needed by that client, so it can
clean up it's resources as necessary. The resources will not be released
until the clients counter has reached zero. It is therefore necessary to
allocate and release your pool manager references carefully.
Properties for a manager can be specified in three different ways.
- Properties file located in CLASSPATH
- Properties file referenced explicitly (with a File object)
- Properties object
- A CLASSPATH located properties file can simply be accessed using the
method getInstance(name) where name is the name of the
properties file specified as a string.
- To specify a properties file which is not in the CLASSPATH use the
method getInstance(File). This same file handle must be used
each time you want to obtain the instance in this way.
- To specify the pools using a Properties object a call must be made to
the createInstance(Properties) method. This method creates the
ConnectionPoolManager instance and makes it available via the getInstance()
method.
Note: The getInstance() method can return one of two
possible instances depending on the previous calls made to the pool manager.
If the createInstance(Properties) method has previously been
called successfully then it will return this manually created instance.
Otherwise it will attempt to return an instance relating to the default
properties file (dbpool.properties) within the CLASSPATH, if it exists.
The properties given to the manager specify which JDBC drivers to use to
access the relevant databases, and also defines the characteristics of each
connection pool. The properties required/allowed are as follows
(those marked with * are mandatory):
drivers* Class names of required JDBC Drivers (comma/space delimited)
logfile* Filename of logfile
<poolname>.url* The JDBC URL for the database
<poolname>.user Database username for login
<poolname>.password Database password for login
<poolname>.maxpool The maximum number of pooled connections (0 if none)
<poolname>.maxconn The maximum number of possible connections (0 if no limit)
<poolname>.expiry The connection expiry time in seconds (0 if no expiry)
<poolname>.init The initial number of connections to create (default:0)
<poolname>.validator Class name of connection validator (optional)
<poolname>.decoder Class name of password decoder (optional)
<poolname>.cache Whether to cache Statements (optional, default:true)
<poolname>.debug Whether to log debug info (optional, default:false)
<poolname>.prop.XXX Passes property XXX and it's value to the JDBC driver
<poolname>.async Whether to use asynchronous connection destruction (optional, default:false)
<poolname>.logfile Filename of logfile for this pool (optional)
<poolname>.dateformat SimpleDateFormat formatting string for log entries (optional)
Multiple pools can be specified provided they each use a different pool name.
The validator property optionally specifies the name of a
class to be used for validating the database connections. The default
connection validation simply performs a test using Connection.isClosed().
This test is not 100% reliable as the Java API documentation specifies that
it only returns true if the connection has been explicitly closed.
If more rigorous connection validation is required you can either use the
provided class snaq.db.AutoCommitValidator or write your own
validation class which should implement the ConnectionValidator
interface.
See Also: snaq.db.AutoCommitValidator
See Also: snaq.db.ConnectionValidator
author:
Giles Winstanley | 