org.logicalcobwebs.proxool

Class ProxoolFacade


public class ProxoolFacade
extends java.lang.Object

This provides some nice-to-have features that can't be provided by the java.sql.Driver implementation of java.sql.Driver. Like starting up a pool before you need a connection. And getting statistical information.

You need to use this class wisely. It is obviously specfic to proxool so it will stop you switching to another driver. Consider isolating the code that calls this class so that you can easily remove it if you have to.

Version:
$Revision: 1.87 $, $Date: 2007/05/15 23:00:22 $
Authors:
billhorsman
$Author: billhorsman $ (current maintainer)

Method Summary

static void
addConfigurationListener(String alias, ConfigurationListenerIF configurationListener)
Adds a listener that gets called everytime the configuration changes.
static void
addConnectionListener(String alias, ConnectionListenerIF connectionListener)
Add a listener that monitors each time a connection is made or destroyed.
static void
addProxoolListener(ProxoolListenerIF proxoolListener)
Add a listener that gets called everytime a global Proxool event ocours.
static void
addStateListener(String alias, StateListenerIF stateListener)
Add a listener that monitors the change of state of the pool (quiet, busy, overloaded, or down)
static void
addStatisticsListener(String alias, StatisticsListenerIF statisticsListener)
Add a listener that receives statistics as they are produced
protected static void
definitionUpdated(String alias, ConnectionPoolDefinitionIF connectionPoolDefinition, Properties completeInfo, Properties changedInfo)
Broadcast a configuration change
static void
disableShutdownHook()
If you call this then you'll have to call shutdown explicitly
static void
enableShutdownHook()
Call this if you change your mind about disabling it.
protected void
finalize()
static String
getAlias(Connection connection)
Get the alias for the connection pool that served a connection
protected static String
getAlias(String url)
Extracts the pool alias from the url: proxool.alias:driver:url -> alias proxool.alias -> alias
static String[]
getAliases()
Get a list of all the registered pools
static Collection
getConnectionInfos(String alias)
Deprecated. use snapshot instead.
static ConnectionPoolDefinitionIF
getConnectionPoolDefinition(String alias)
Get the definition of a pool.
static ConnectionPoolStatisticsIF
getConnectionPoolStatistics(String alias)
Deprecated. use getSnapshot
static String
getConnectionPoolStatisticsDump(String alias)
Deprecated. use getSnapshot
static Connection
getDelegateConnection(Connection connection)
Deprecated. Just cast the connection that you are given into the driver specific one.
static Statement
getDelegateStatement(Statement statement)
Deprecated. Just cast the statement that you are given into the driver specific one.
static long
getId(Connection connection)
Get the connection ID for a connection
static SnapshotIF
getSnapshot(String alias)
Calls getSnapshot using false for the detail parameter.
static SnapshotIF
getSnapshot(String alias, boolean detail)
Gives a snapshot of what the pool is doing
static StatisticsIF[]
getStatistics(String alias)
Get all the lastest performance statistics for this pool
static StatisticsIF
getStatistics(String alias, String token)
Get a particular set of performance statistics for this pool
static boolean
isShutdownHookEnabled()
Whether the ShutdownHook should do anything.
static void
killAllConnections(String alias)
Deprecated. use alternative to provide better auditing in log
static void
killAllConnections(String alias, String reason)
Like killAllConnections but defaults to merciful.
static void
killAllConnections(String alias, String reason, boolean merciful)
Kill all connections in a pool.
static void
killAllConnections(String alias, boolean merciful)
Deprecated. use alternative to provide better auditing in log
static boolean
killConnecton(Connection connection, boolean merciful)
Kill a single connection
static boolean
killConnecton(String alias, long id, boolean merciful)
Kill a single connection
static void
redefineConnectionPool(String url, Properties info)
Redefine the behaviour of the pool.
static void
registerConnectionPool(String url)
With no configurator or properties (using default values)
static String
registerConnectionPool(String url, Properties info)
Build a ConnectionPool based on this definition and then start it.
protected static String
registerConnectionPool(String url, Properties info, boolean explicitRegister)
Build a ConnectionPool based on this definition and then start it.
protected static void
registerConnectionPool(org.logicalcobwebs.proxool.ConnectionPoolDefinition connectionPoolDefinition)
static void
removeAllConnectionPools(int delay)
Deprecated. use the better named shutdown() instead.
static boolean
removeConfigurationListener(String alias, ConfigurationListenerIF configurationListener)
Remove a listener that gets called everytime the configuration changes.
static boolean
removeConnectionListener(String alias, ConnectionListenerIF connectionListener)
Remove a listener that monitors each time a connection is made or destroyed.
static void
removeConnectionPool(String alias)
Like removeConnectionPool(java.lang.String, int) but uses no delay.
static void
removeConnectionPool(String alias, int delay)
Remove a connection pool.
static boolean
removeProxoolListener(ProxoolListenerIF proxoolListener)
Remove a registered ProxoolListenerIF.
static boolean
removeStateListener(String alias, StateListenerIF stateListener)
Remove a listener that monitors the change of state of the pool (quiet, busy, overloaded, or down)
static void
setConfigurationListener(String alias, ConfigurationListenerIF configurationListener)
Deprecated. use addConfigurationListener(String,ConfigurationListenerIF) instead.
static void
setConnectionListener(String alias, ConnectionListenerIF connectionListener)
Deprecated. use addConnectionListener(String,ConnectionListenerIF) instead.
protected static void
setShutdownHook(Thread t)
By remembering the most recent ShutdownHook ProxoolFacade will know to disable it when it is shutdown.
static void
setStateListener(String alias, StateListenerIF stateListener)
Deprecated. use addStateListener(String,StateListenerIF) instead.
static void
shutdown()
Removes all connection pools.
protected static void
shutdown(String finalizer, int delay)
Removes all connection pools.
static void
shutdown(int delay)
Removes all connection pools.
static void
updateConnectionPool(String url, Properties info)
Update the behaviour of the pool.

Method Details

addConfigurationListener

public static void addConfigurationListener(String alias,
                                            ConfigurationListenerIF configurationListener)
            throws ProxoolException
Adds a listener that gets called everytime the configuration changes.
Parameters:
alias - identifies the pool
configurationListener - the new listener
Throws:
ProxoolException - if we couldn't find the pool

addConnectionListener

public static void addConnectionListener(String alias,
                                         ConnectionListenerIF connectionListener)
            throws ProxoolException
Add a listener that monitors each time a connection is made or destroyed.
Parameters:
alias - identifies the pool
connectionListener - the new listener
Throws:
ProxoolException - if we couldn't find the pool

addProxoolListener

public static void addProxoolListener(ProxoolListenerIF proxoolListener)
Add a listener that gets called everytime a global Proxool event ocours.
Parameters:
proxoolListener - the listener to add.

addStateListener

public static void addStateListener(String alias,
                                    StateListenerIF stateListener)
            throws ProxoolException
Add a listener that monitors the change of state of the pool (quiet, busy, overloaded, or down)
Parameters:
alias - identifies the pool
stateListener - the new listener
Throws:
ProxoolException - if we couldn't find the pool

addStatisticsListener

public static void addStatisticsListener(String alias,
                                         StatisticsListenerIF statisticsListener)
            throws ProxoolException
Add a listener that receives statistics as they are produced
Parameters:
statisticsListener - the new listener
Throws:
ProxoolException - if the pool couldn't be found

definitionUpdated

protected static void definitionUpdated(String alias,
                                        ConnectionPoolDefinitionIF connectionPoolDefinition,
                                        Properties completeInfo,
                                        Properties changedInfo)
Broadcast a configuration change
Parameters:
alias - identifies the pool
connectionPoolDefinition - the definition
completeInfo - all properties
changedInfo - only changed properties (since the last time this method was called)

disableShutdownHook

public static void disableShutdownHook()
If you call this then you'll have to call shutdown explicitly

enableShutdownHook

public static void enableShutdownHook()
Call this if you change your mind about disabling it. The default behaviour is to have it enabled so unless you have disabled it then there's nothing to do.

finalize

protected void finalize()
            throws Throwable

getAlias

public static String getAlias(Connection connection)
            throws ProxoolException
Get the alias for the connection pool that served a connection
Parameters:
connection - the connection that was served
Returns:
the alias
Throws:
ProxoolException - if the connection wasn't recognised.

getAlias

protected static String getAlias(String url)
            throws ProxoolException
Extracts the pool alias from the url: proxool.alias:driver:url -> alias proxool.alias -> alias
Returns:
the alias defined within the url
Throws:
ProxoolException - if we couldn't find the alias

getAliases

public static String[] getAliases()
Get a list of all the registered pools
Returns:
an array of aliases
Since:
Proxool 0.7

getConnectionInfos

public static Collection getConnectionInfos(String alias)
            throws ProxoolException

Deprecated. use snapshot instead.

Get details on each connection within the pool. This can tell you which ones are active, how long they have been active, etc.
Parameters:
alias - identifies the pool
Returns:
a collection of ConnectionInfoIFs
Throws:
ProxoolException - if we couldn't find the pool

getConnectionPoolDefinition

public static ConnectionPoolDefinitionIF getConnectionPoolDefinition(String alias)
            throws ProxoolException
Get the definition of a pool.
Parameters:
alias - identifies the pool
Throws:
ProxoolException - if we couldn't find the pool

getConnectionPoolStatistics

public static ConnectionPoolStatisticsIF getConnectionPoolStatistics(String alias)
            throws ProxoolException

Deprecated. use getSnapshot

Get real-time statistical information about how a pool is performing.
Parameters:
alias - to identify the pool
Returns:
the statistics
Throws:
ProxoolException - if we couldn't find the pool

getConnectionPoolStatisticsDump

public static String getConnectionPoolStatisticsDump(String alias)
            throws ProxoolException

Deprecated. use getSnapshot

Get real-time statistical information about how a pool is performing. and extract the information piece by piece.
Parameters:
alias - to identify the pool
Returns:
a horrible string describing the statistics
Throws:
ProxoolException - if we couldn't find the pool

getDelegateConnection

public static Connection getDelegateConnection(Connection connection)
            throws ProxoolException

Deprecated. Just cast the connection that you are given into the driver specific one.

Returns the driver provided connection that Proxool wraps up before it gives it to you.
Returns:
delegate connection

getDelegateStatement

public static Statement getDelegateStatement(Statement statement)
            throws ProxoolException

Deprecated. Just cast the statement that you are given into the driver specific one.

Returns the driver provided statement that Proxool wraps up before it gives it to you.
Returns:
delegate statement

getId

public static long getId(Connection connection)
            throws ProxoolException
Get the connection ID for a connection
Parameters:
connection - the connection that was served
Returns:
the ID
Throws:
ProxoolException - if the connection wasn't recognised.

getSnapshot

public static SnapshotIF getSnapshot(String alias)
            throws ProxoolException
Calls getSnapshot using false for the detail parameter.
See Also:
getSnapshot(java.lang.String, boolean)

getSnapshot

public static SnapshotIF getSnapshot(String alias,
                                     boolean detail)
            throws ProxoolException
Gives a snapshot of what the pool is doing
Parameters:
alias - identifies the pool
detail - if true then include detail of each connection. Note it you ask for detail then the pool must necessarily be locked for the duration it takes to gather the information (which isn't very long). You probably shouldn't do it that often (like not every second or something). Being locked means that connections cannot be served or returned (it doesn't mean that they can't be active).
Returns:
the current status of the pool
Throws:
ProxoolException - if we couldn't find the pool

getStatistics

public static StatisticsIF[] getStatistics(String alias)
            throws ProxoolException
Get all the lastest performance statistics for this pool
Parameters:
alias - identifies the pool
Returns:
a sample containing the statistics, or a zero length array if there none
Throws:
ProxoolException - if we couldn't find the pool

getStatistics

public static StatisticsIF getStatistics(String alias,
                                         String token)
            throws ProxoolException
Get a particular set of performance statistics for this pool
Parameters:
alias - identifies the pool
token - identifies which set, as defined in the configuration (see definition)
Returns:
a sample containing the statistics
Throws:
ProxoolException - if we couldn't find the pool

isShutdownHookEnabled

public static boolean isShutdownHookEnabled()
Whether the ShutdownHook should do anything.
Returns:
true if the shutdown hook should clean up

killAllConnections

public static void killAllConnections(String alias)
            throws ProxoolException

Deprecated. use alternative to provide better auditing in log

Like killAllConnections but defaults to merciful.
Parameters:
alias - to identify the pool
Throws:
ProxoolException - if we couldn't find the pool

killAllConnections

public static void killAllConnections(String alias,
                                      String reason)
            throws ProxoolException
Like killAllConnections but defaults to merciful.
Parameters:
alias - to identify the pool
reason - provides audit in log of why connections were killed
Throws:
ProxoolException - if we couldn't find the pool

killAllConnections

public static void killAllConnections(String alias,
                                      String reason,
                                      boolean merciful)
            throws ProxoolException
Kill all connections in a pool. The pool continues to work however, and new connections will be made as required.
Parameters:
alias - the pool containing the connection
reason - provides audit in log of why connections were killed
merciful - if true will only kill connections that aren't active
Throws:
ProxoolException - if we couldn't find the pool

killAllConnections

public static void killAllConnections(String alias,
                                      boolean merciful)
            throws ProxoolException

Deprecated. use alternative to provide better auditing in log

Kill all connections in a pool. The pool continues to work however, and new connections will be made as required.
Parameters:
alias - the pool containing the connection
merciful - if true will only kill connections that aren't active
Throws:
ProxoolException - if we couldn't find the pool

killConnecton

public static boolean killConnecton(Connection connection,
                                    boolean merciful)
            throws ProxoolException
Kill a single connection
Parameters:
connection - the connection to kill
merciful - if true will only kill connections that aren't active
Returns:
true if the connection was killed, or false if it couldn't be found.
Throws:
ProxoolException - if we didn't recognise the connection

killConnecton

public static boolean killConnecton(String alias,
                                    long id,
                                    boolean merciful)
            throws ProxoolException
Kill a single connection
Parameters:
alias - the pool containing the connection
id - the id of the specific connection
merciful - if true will only kill connections that aren't active
Returns:
true if the connection was killed, or false if it couldn't be found.
Throws:
ProxoolException - if we couldn't find the pool

redefineConnectionPool

public static void redefineConnectionPool(String url,
                                          Properties info)
            throws ProxoolException
Redefine the behaviour of the pool. All existing properties (for Proxool and the delegate driver are reset to their default) and reapplied based on the parameters sent here.
Parameters:
url - the url that defines the pool (or the abbreviated ""proxool.alias")
info - the new properties

registerConnectionPool

public static void registerConnectionPool(String url)
            throws ProxoolException
With no configurator or properties (using default values)
See Also:
registerConnectionPool(java.lang.String, java.util.Properties)

registerConnectionPool

public static String registerConnectionPool(String url,
                                            Properties info)
            throws ProxoolException
Build a ConnectionPool based on this definition and then start it.
Parameters:
url - defines the delegate driver and delegate url.
info - the properties used to configure Proxool (and any for the delegate driver too) - optional
Returns:
the alias for this pool (or the full url if no alias is specified)
Throws:
ProxoolException - if anything goes wrong

registerConnectionPool

protected static String registerConnectionPool(String url,
                                               Properties info,
                                               boolean explicitRegister)
            throws ProxoolException
Build a ConnectionPool based on this definition and then start it.
Parameters:
url - defines the delegate driver and delegate url.
info - the properties used to configure Proxool (and any for the delegate driver too) - optional
explicitRegister - set to true if we are registering a new pool explicitly, or false if it's just because we are serving a url that we haven't come across before
Returns:
the alias for this pool (or the full url if no alias is specified)
Throws:
ProxoolException - if anything goes wrong

registerConnectionPool

protected static void registerConnectionPool(org.logicalcobwebs.proxool.ConnectionPoolDefinition connectionPoolDefinition)
            throws ProxoolException

removeAllConnectionPools

public static void removeAllConnectionPools(int delay)

Deprecated. use the better named shutdown() instead.

Removes all connection pools. Kills all the connections. Resets everything.
Parameters:
delay - the time to wait for connections to become inactive before killing it (milliseconds)

removeConfigurationListener

public static boolean removeConfigurationListener(String alias,
                                                  ConfigurationListenerIF configurationListener)
            throws ProxoolException
Remove a listener that gets called everytime the configuration changes.
Parameters:
alias - identifies the pool.
configurationListener - the listener to be removed.
Returns:
wether the listnener was found and removed or not.
Throws:
ProxoolException - if we couldn't find the pool

removeConnectionListener

public static boolean removeConnectionListener(String alias,
                                               ConnectionListenerIF connectionListener)
            throws ProxoolException
Remove a listener that monitors each time a connection is made or destroyed.
Parameters:
alias - identifies the pool
connectionListener - the listener to be removed
Returns:
wether the listnener was found and removed or not.
Throws:
ProxoolException - if we couldn't find the pool

removeConnectionPool

public static void removeConnectionPool(String alias)
            throws ProxoolException
Like removeConnectionPool(java.lang.String, int) but uses no delay. (Kills everything as quickly as possible).
Parameters:
alias - to identify the pool
Throws:
ProxoolException - if we couldn't find the pool

removeConnectionPool

public static void removeConnectionPool(String alias,
                                        int delay)
            throws ProxoolException
Remove a connection pool. Kills all the connections. Resets everything.
Parameters:
alias - the pool to remove
delay - the time to wait for connections to become inactive before killing it (milliseconds)
Throws:
ProxoolException - if we couldn't find the pool

removeProxoolListener

public static boolean removeProxoolListener(ProxoolListenerIF proxoolListener)
Remove a registered ProxoolListenerIF.
Parameters:
proxoolListener - the listener to remove.
Returns:
whether the listener was found or removed or not.

removeStateListener

public static boolean removeStateListener(String alias,
                                          StateListenerIF stateListener)
            throws ProxoolException
Remove a listener that monitors the change of state of the pool (quiet, busy, overloaded, or down)
Parameters:
alias - identifies the pool
stateListener - the listener to be removed.
Returns:
wether the listnener was found and removed or not.
Throws:
ProxoolException - if we couldn't find the pool

setConfigurationListener

public static void setConfigurationListener(String alias,
                                            ConfigurationListenerIF configurationListener)
            throws ProxoolException

Deprecated. use addConfigurationListener(String,ConfigurationListenerIF) instead.


setConnectionListener

public static void setConnectionListener(String alias,
                                         ConnectionListenerIF connectionListener)
            throws ProxoolException

Deprecated. use addConnectionListener(String,ConnectionListenerIF) instead.


setShutdownHook

protected static void setShutdownHook(Thread t)
By remembering the most recent ShutdownHook ProxoolFacade will know to disable it when it is shutdown. It will gracefully cope with the fact that it may be shutting down by the request of the sutdownHook. If you don't do this and do several "hot deploys" then you end up with a series of shutdown hooks. We only every want one.
Parameters:
t - the thread that will be run as a shutdown hook
See Also:
ShutdownHook

setStateListener

public static void setStateListener(String alias,
                                    StateListenerIF stateListener)
            throws ProxoolException

Deprecated. use addStateListener(String,StateListenerIF) instead.


shutdown

public static void shutdown()
Removes all connection pools. Kills all the connections. Resets everything. Like shutdown(java.lang.String, int) but passes the current thread name and a delay of zero.

shutdown

protected static void shutdown(String finalizer,
                               int delay)
Removes all connection pools. Kills all the connections. Resets everything.
Parameters:
finalizer - used to identify who is causing the pools to be removed (helps logging)
delay - the time to wait for connections to become inactive before killing it (milliseconds)

shutdown

public static void shutdown(int delay)
Removes all connection pools. Kills all the connections. Resets everything. Like shutdown(java.lang.String, int) but passes the current thread name.
Parameters:
delay - the time to wait for connections to become inactive before killing it (milliseconds)

updateConnectionPool

public static void updateConnectionPool(String url,
                                        Properties info)
            throws ProxoolException
Update the behaviour of the pool. Only properties that are defined here are overwritten. That is, properties that were defined before but are not mentioned here are retained.
Parameters:
url - the url that defines the pool (or the abbreviated ""proxool.alias")
info - the new properties