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.
When the pool manager is no longer required the
release() method
should be called to ensure all associated resources are released.
Once called, that pool manager instance can no longer be used.
To facilitate easy release of any/all pool managers methods
#registerShutdownHook and
#registerGlobalShutdownHook are
provided, which when called adds a hook to the Java Virtual Machine to
release one/all pool manager instance(s) within the context of the same
ClassLoader.
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):
name Name of this pool manager instance (for log identification)
drivers* Class names of required JDBC Drivers (comma/space delimited)
logfile Specifies a custom log file for this pool manager
dateformat
SimpleDateFormat formatting string for custom log entries
<poolname>.url* JDBC URL for the database
<poolname>.user Database username for login
<poolname>.password Database password for login
<poolname>.minpool Minimum number of pooled connections (0 if none)
<poolname>.maxpool Maximum number of pooled connections (0 if none)
<poolname>.maxsize Maximum number of possible connections (0 if no limit)
<poolname>.idleTimeout Connection idle timeout time in seconds (0 if no timeout)
<poolname>.validator Class name of optional
ConnectionValidator to use
<poolname>.validatorQuery SQL statement used with
SimpleQueryValidator for optional connection validation
<poolname>.decoder Class name of optional
PasswordDecoder to use
<poolname>.prop.XXX Passes property XXX and its value to the JDBC driver
<poolname>.logfile Filename of optional logfile for this pool (optional, deprecated)
<poolname>.dateformat
SimpleDateFormat formatting string for optional custom log entries (deprecated)
<poolname>.debug Whether to log debug info (optional, default:false)
<poolname>.cache Whether to cache Statements (default:true)
<poolname>.selection Pool connection selection strategy ({LIFO, FIFO, RANDOM}, default:LIFO)
<poolname>.async Whether to use asynchronous connection destruction (default:false)
<poolname>.releaseTimeout Timeout of pool released before forcibly destroyed (-1 if none, 0 if immediately; default:0)
<poolname>.recycleAfterRaw Whether to turn on recycling of connections that have had delegate accessed (default:false)
<poolname>.listenerN Class name of
ConnectionPoolListener to create (N=0, 1, ...)
<poolname>.listenerN.XXX Passes property XXX and its value to the numbered listener
<poolname>.mbean Whether to register a JMX MBean for this pool (default:false)
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.