|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectsnaq.db.ConnectionPoolManager
public final class 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.
File
object)
Properties
object
getInstance(name)
where name is the name of the
properties file specified as a string.
getInstance(File)
. This same file handle must be used
each time you want to obtain the instance in this way.
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 dateformatSimpleDateFormat
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 ofConnectionValidator
to use <poolname>.decoder Class name ofPasswordDecoder
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>.dateformatSimpleDateFormat
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 ofConnectionPoolListener
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.
AutoCommitValidator
,
ConnectionValidator
,
LIFO,
FIFOMethod 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 |
---|
public void registerShutdownHook()
public void removeShutdownHook()
public static void registerGlobalShutdownHook()
Note: All individual shutdown hooks will be deregistered and replaced with this single shutdown hook.
public static void removeGlobalShutdownHook()
public String toString()
toString
in class Object
public boolean equals(Object obj)
equals
in class Object
public int hashCode()
toString()
value.
hashCode
in class Object
public int compareTo(ConnectionPoolManager cpm)
equals(Object)
, but consistency is not complete due to
awkwardness of comparison of Properties
instances.
(check source for implementation details).
compareTo
in interface Comparable<ConnectionPoolManager>
public static Set<ConnectionPoolManager> getInstances()
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.
ConnectionPoolManager
.public static ConnectionPoolManager getInstance(String propsFile, String enc) throws IOException
ConnectionPoolManager
for the specified properties file.
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
ConnectionPoolManager
relating to the specified properties file
IOException
- if there was an problem loading the propertiespublic static ConnectionPoolManager getInstance(String propsFile) throws IOException
ConnectionPoolManager
for the specified properties file.
propsFile
- filename of the properties file to use (path info should not be specified; available CLASSPATH will be searched for the properties file)
ConnectionPoolManager
relating to the specified properties file
IOException
- if there was an problem loading the propertiespublic static ConnectionPoolManager getInstance(File propsFile, String enc) throws IOException
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
IOException
- if there was an problem loading the propertiespublic static ConnectionPoolManager getInstance(File propsFile) throws IOException
propsFile
- filename of the properties file to use (path info should not be specified; available CLASSPATH will be searched for the properties file)
IOException
- if there was an problem loading the propertiespublic static ConnectionPoolManager getInstance() throws IOException
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
).
IOException
- if there was an problem loading the propertiespublic static void createInstance(Properties props)
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.)
props
- Properties
object to use
RuntimeException
- if default properties instance already exists and is in usepublic final String getName()
public ConnectionPool getPool(String name)
ConnectionPool
instances by name.
(This is only provided as a convenience method to allow fine-tuning in
exceptional circumstances.)
name
- pool name as defined in the properties file
null
public Collection<ConnectionPool> getPools()
ConnectionPool
instances maintained by this manager.
(This is only provided as a convenience method.)
ConnectionPool
instancespublic Connection getConnection(String name) throws SQLException
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.
name
- ConnectionPool
name as defined in the properties file
Connection
, or null
if unable to obtain one
SQLException
public Connection getConnection(String name, long time) throws SQLException
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.
name
- pool name as defined in the properties filetime
- number of milliseconds to wait
Connection
or null
SQLException
public void release()
ConnectionPoolManager
, and deregisters
JDBC drivers if necessary. Any connections still in use are forcibly closed.
public boolean isReleased()
public final void addConnectionPoolManagerListener(ConnectionPoolManagerListener x)
ConnectionPoolManagerListener
to the event notification list.
public final void removeConnectionPoolManagerListener(ConnectionPoolManagerListener x)
ConnectionPoolManagerListener
from the event notification list.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |