ConnectionPoolManager (DBPool 6.0 API)

java.lang.Object
- 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 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>.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

Methods
Modifier and Type	Method and Description
`void`	`addConnectionPoolManagerListener(ConnectionPoolManagerListener listener)` 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 timeout)` 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).
`protected void`	`log_debug(String s)` Logging relay method (to prefix pool name).
`protected void`	`log_debug(String s, Throwable throwable)` Logging relay method (to prefix pool name).
`protected void`	`log_error(String s)` Logging relay method (to prefix pool name).
`protected void`	`log_error(String s, Throwable throwable)` Logging relay method (to prefix pool name).
`protected void`	`log_info(String s)` Logging relay method (to prefix pool name).
`protected void`	`log_info(String s, Throwable throwable)` Logging relay method (to prefix pool name).
`protected void`	`log_trace(String s)` Logging relay method (to prefix pool name).
`protected void`	`log_trace(String s, Throwable throwable)` Logging relay method (to prefix pool name).
`protected void`	`log_warn(String s)` Logging relay method (to prefix pool name).
`protected void`	`log_warn(String s, Throwable throwable)` Logging relay method (to prefix pool name).
`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 unregisters JDBC drivers if necessary.
`void`	`removeConnectionPoolManagerListener(ConnectionPoolManagerListener listener)` 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
clone, finalize, 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 unregistered 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>
    
    Parameters:
    cpm - ConnectionPoolManager to which to compare this instance
  - 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).
    
    Returns:
    An instance of ConnectionPoolManager
    
    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:
    
    IllegalStateException - if default properties instance already exists and is in use
  - getName
```
public final String getName()
```
    Returns the pool manager's name.
    
    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 if the named pool could not be found
    
    Throws:
    
    IllegalArgumentException - if the specified name is not a valid pool name (i.e. 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:
    
    IllegalArgumentException - if the specified name is not a valid pool name
    
    SQLException - if such an exception is raised by ConnectionPool.getConnection()
  - getConnection
```
public Connection getConnection(String name,
                       long timeout)
                         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
    timeout - number of milliseconds to wait
    
    Returns:
    the Connection or null
    
    Throws:
    
    IllegalArgumentException - if the specified name is not a valid pool name
    
    SQLException - if such an exception is raised by ConnectionPool.getConnection(long)
  - release
```
public void release()
```
    Releases all resources for this ConnectionPoolManager, and unregisters 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).
    
    Returns:
    true if already release, false otherwise
  - log_error
```
protected void log_error(String s)
```
    Logging relay method (to prefix pool name).
  - log_error
```
protected void log_error(String s,
             Throwable throwable)
```
    Logging relay method (to prefix pool name).
  - log_warn
```
protected void log_warn(String s)
```
    Logging relay method (to prefix pool name).
  - log_warn
```
protected void log_warn(String s,
            Throwable throwable)
```
    Logging relay method (to prefix pool name).
  - log_info
```
protected void log_info(String s)
```
    Logging relay method (to prefix pool name).
  - log_info
```
protected void log_info(String s,
            Throwable throwable)
```
    Logging relay method (to prefix pool name).
  - log_debug
```
protected void log_debug(String s)
```
    Logging relay method (to prefix pool name).
  - log_debug
```
protected void log_debug(String s,
             Throwable throwable)
```
    Logging relay method (to prefix pool name).
  - log_trace
```
protected void log_trace(String s)
```
    Logging relay method (to prefix pool name).
  - log_trace
```
protected void log_trace(String s,
             Throwable throwable)
```
    Logging relay method (to prefix pool name).
  - addConnectionPoolManagerListener
```
public final void addConnectionPoolManagerListener(ConnectionPoolManagerListener listener)
```
    Adds a ConnectionPoolManagerListener to the event notification list.
    
    Parameters:
    listener - listener to add
  - removeConnectionPoolManagerListener
```
public final void removeConnectionPoolManagerListener(ConnectionPoolManagerListener listener)
```
    Removes a ConnectionPoolManagerListener from the event notification list.
    
    Parameters:
    listener - listener to add

Class ConnectionPoolManager

Method Summary

Methods inherited from class java.lang.Object

Method Detail

registerShutdownHook

removeShutdownHook

registerGlobalShutdownHook

removeGlobalShutdownHook

toString

equals

hashCode

compareTo

getInstances

getInstance

getInstance

getInstance

getInstance

getInstance

createInstance

getName

getPool

getPools

getConnection

getConnection

release

isReleased

log_error

log_error

log_warn

log_warn

log_info

log_info

log_debug

log_debug

log_trace

log_trace

addConnectionPoolManagerListener

removeConnectionPoolManagerListener