snaq.db
Class ConnectionPoolManager

java.lang.Object
  extended by snaq.db.ConnectionPoolManager
All Implemented Interfaces:
Comparable<ConnectionPoolManager>

public final class ConnectionPoolManager
extends Object
implements Comparable<ConnectionPoolManager>

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.

  1. Properties file located in CLASSPATH
  2. Properties file referenced explicitly (with a File object)
  3. Properties object
  1. 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.
  2. 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.
  3. 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 ConnectionValidator to use
 <poolname>.decoder              Class name of PasswordDecoder to use
 <poolname>.prop.XXX             Passes property XXX and its value to the JDBC driver
 <poolname>.logfile              Filename of logfile for this pool (optional)
 <poolname>.dateformat           SimpleDateFormat formatting string for custom log entries
 <poolname>.debug                Whether to log debug info (optional, default:false)
 <poolname>.cache                Whether to cache Statements (default:true)
 <poolname>.access               Pool access type ({LIFO, FIFO, RANDOM}, default:LIFO)
 <poolname>.async                Whether to use asynchronous connection destruction (default:false)
 <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.

Author:
Giles Winstanley
See Also:
AutoCommitValidator, ConnectionValidator, LIFO, FIFO

Method Summary
 void addConnectionPoolManagerListener(ConnectionPoolManagerListener x)
          Adds a ConnectionPoolManagerListener to the event notification list.
 int compareTo(ConnectionPoolManager cpm)
          Compares this object with the specified object for order.
static void createInstance(Properties props)
          Creates a singleton instance of the ConnectionPoolManager for the specified Properties object.
 boolean equals(Object obj)
          Indicates whether some other object is "equal to" this one.
 Connection getConnection(String name)
          Returns an open Connection from the specified ConnectionPool.
 Connection getConnection(String name, long time)
          Returns an open Connection from the specified pool.
static ConnectionPoolManager getInstance()
          Returns the standard singleton instance of the ConnectionPoolManager.
static ConnectionPoolManager getInstance(File propsFile)
          Returns the singleton instance of the ConnectionPoolManager for the specified properties file.
static ConnectionPoolManager getInstance(File propsFile, String enc)
          Returns the singleton instance of the ConnectionPoolManager for the specified properties file.
static ConnectionPoolManager getInstance(String propsFile)
          Returns the singleton instance of the ConnectionPoolManager for the specified properties file.
static ConnectionPoolManager getInstance(String propsFile, String enc)
          Returns the singleton instance of the ConnectionPoolManager for the specified properties file.
static Set<ConnectionPoolManager> getInstances()
          Returns a Set containing all the current ConnectionPoolManager instances.
 String getName()
          Returns the pool manager's name.
 ConnectionPool getPool(String name)
          Returns one of the ConnectionPool instances by name.
 Collection<ConnectionPool> getPools()
          Returns all the current ConnectionPool instances maintained by this manager.
 int hashCode()
          Returns a hash code value for the object.
 boolean isReleased()
          Returns whether this instance has been released (and therefore is unusable).
static void registerGlobalShutdownHook()
          Registers a shutdown hook for all current and future ConnectionPoolManager instances to ensure they are released if the JVM exits with any managers having not been released.
 void registerShutdownHook()
          Registers a shutdown hook for this ConnectionPoolManager instance to ensure it is released if the JVM exits
 void release()
          Releases all resources for this ConnectionPoolManager, and deregisters JDBC drivers if necessary.
 void removeConnectionPoolManagerListener(ConnectionPoolManagerListener x)
          Removes a ConnectionPoolManagerListener from the event notification list.
static void removeGlobalShutdownHook()
          Removes a registered global shutdown hook for all current and future ConnectionPoolManager instances.
 void removeShutdownHook()
          Removes a registered shutdown hook for this ConnectionPoolManager instance.
 String toString()
          Returns a descriptive string for this instance.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

registerShutdownHook

public void registerShutdownHook()
Registers a shutdown hook for this ConnectionPoolManager instance to ensure it is released if the JVM exits


removeShutdownHook

public void removeShutdownHook()
Removes a registered shutdown hook for this ConnectionPoolManager instance.


registerGlobalShutdownHook

public static void registerGlobalShutdownHook()
Registers a shutdown hook for all current and future ConnectionPoolManager instances to ensure they are released if the JVM exits with any managers having not been released.

Note: All individual shutdown hooks will be deregistered and replaced with this single shutdown hook.


removeGlobalShutdownHook

public static void removeGlobalShutdownHook()
Removes a registered global shutdown hook for all current and future ConnectionPoolManager instances.


toString

public String toString()
Returns a descriptive string for this instance.

Overrides:
toString in class Object

equals

public boolean equals(Object obj)
Indicates whether some other object is "equal to" this one. This implementation performs checks on the name and the "source", which represents how the pool manager was created.

Overrides:
equals in class Object

hashCode

public int hashCode()
Returns a hash code value for the object. This implementation hashes on the name and toString() value.

Overrides:
hashCode in class Object

compareTo

public int compareTo(ConnectionPoolManager cpm)
Compares this object with the specified object for order. This implementation is generally consistent with the implementation of equals(Object), but consistency is not complete due to awkwardness of comparison of Properties instances. (check source for implementation details).

Specified by:
compareTo in interface Comparable<ConnectionPoolManager>

getInstances

public static Set<ConnectionPoolManager> getInstances()
Returns a Set containing all the current ConnectionPoolManager instances. This method is included for convenience for external monitoring. Clients wanting to obtain an instance for using connections should NOT use this method.

Returns:
all current instances of ConnectionPoolManager.

getInstance

public static ConnectionPoolManager getInstance(String propsFile,
                                                String enc)
                                         throws IOException
Returns the singleton instance of the ConnectionPoolManager for the specified properties file.

Parameters:
propsFile - filename of the properties file to use (path info should not be specified; available CLASSPATH will be searched for the properties file)
enc - character-encoding to use for reading properties file
Returns:
instance of ConnectionPoolManager relating to the specified properties file
Throws:
IOException - if there was an problem loading the properties

getInstance

public static ConnectionPoolManager getInstance(String propsFile)
                                         throws IOException
Returns the singleton instance of the ConnectionPoolManager for the specified properties file.

Parameters:
propsFile - filename of the properties file to use (path info should not be specified; available CLASSPATH will be searched for the properties file)
Returns:
instance of ConnectionPoolManager relating to the specified properties file
Throws:
IOException - if there was an problem loading the properties

getInstance

public static ConnectionPoolManager getInstance(File propsFile,
                                                String enc)
                                         throws IOException
Returns the singleton instance of the ConnectionPoolManager for the specified properties file.

Parameters:
propsFile - filename of the properties file to use (path info should not be specified; available CLASSPATH will be searched for the properties file)
enc - character-encoding to use for reading properties file
Returns:
instance of ConnectionPoolManager relating to the specified properties file
Throws:
IOException - if there was an problem loading the properties

getInstance

public static ConnectionPoolManager getInstance(File propsFile)
                                         throws IOException
Returns the singleton instance of the ConnectionPoolManager for the specified properties file.

Parameters:
propsFile - filename of the properties file to use (path info should not be specified; available CLASSPATH will be searched for the properties file)
Returns:
instance of ConnectionPoolManager relating to the specified properties file
Throws:
IOException - if there was an problem loading the properties

getInstance

public static ConnectionPoolManager getInstance()
                                         throws IOException
Returns the standard singleton instance of the ConnectionPoolManager. If an instance has been obtained with a user-specified Properties object then this instance is returned, otherwise an attempt is made to return an instance using the default properties file (dbpool.properties).

Throws:
IOException - if there was an problem loading the properties

createInstance

public static void createInstance(Properties props)
Creates a singleton instance of the ConnectionPoolManager for the specified Properties object. To subsequently use this instance user's should call the getInstance() method. This mechanism is used to provide the maximum separation between creation and use of this instance to avoid haphazard changes to any referenced Properties object that may occur between calls. (This method can only be used successfully if no default properties instance exists and is in use at the time of calling.)

Parameters:
props - Properties object to use
Throws:
RuntimeException - if default properties instance already exists and is in use

getName

public final String getName()
Returns the pool manager's name.


getPool

public ConnectionPool getPool(String name)
Returns one of the ConnectionPool instances by name. (This is only provided as a convenience method to allow fine-tuning in exceptional circumstances.)

Parameters:
name - pool name as defined in the properties file
Returns:
the pool or null

getPools

public Collection<ConnectionPool> getPools()
Returns all the current ConnectionPool instances maintained by this manager. (This is only provided as a convenience method.)

Returns:
array of ConnectionPool instances

getConnection

public Connection getConnection(String name)
                         throws SQLException
Returns an open Connection from the specified ConnectionPool. If one is not available, and the max number of connections has not been reached, a new connection is created.

Parameters:
name - ConnectionPool name as defined in the properties file
Returns:
a Connection, or null if unable to obtain one
Throws:
SQLException

getConnection

public Connection getConnection(String name,
                                long time)
                         throws SQLException
Returns an open Connection from the specified pool. If one is not available, and the max number of connections has not been reached, a new connection is created. If the max number has been reached, waits until one is available or the specified time has elapsed.

Parameters:
name - pool name as defined in the properties file
time - number of milliseconds to wait
Returns:
the Connection or null
Throws:
SQLException

release

public void release()
Releases all resources for this ConnectionPoolManager, and deregisters JDBC drivers if necessary. Any connections still in use are forcibly closed.


isReleased

public boolean isReleased()
Returns whether this instance has been released (and therefore is unusable).


addConnectionPoolManagerListener

public final void addConnectionPoolManagerListener(ConnectionPoolManagerListener x)
Adds a ConnectionPoolManagerListener to the event notification list.


removeConnectionPoolManagerListener

public final void removeConnectionPoolManagerListener(ConnectionPoolManagerListener x)
Removes a ConnectionPoolManagerListener from the event notification list.