org.logicalcobwebs.proxool
Class ProxoolFacade

java.lang.Object
  org.logicalcobwebs.proxool.ProxoolFacade

public class ProxoolFacade
extends java.lang.Object

This provides some nice-to-have features that can't be provided by the 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.83 $, $Date: 2005/09/26 09:54:14 $

Author:

billhorsman, $Author: billhorsman $ (current maintainer)

Field Summary

private static CompositeProxoolListener	compositeProxoolListener
private static java.util.Map	configurators
private static Log	LOG
private static boolean	MERCIFUL
private static java.lang.Thread	shutdownHook This is the thread that has been registered with Runtime as a shutdownHook.
private static boolean	versionLogged

Constructor Summary

ProxoolFacade()

Method Summary

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

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG

private static final Log LOG

configurators

private static java.util.Map configurators

compositeProxoolListener

private static CompositeProxoolListener compositeProxoolListener

versionLogged

private static boolean versionLogged

shutdownHook

private static java.lang.Thread shutdownHook

This is the thread that has been registered with Runtime as a shutdownHook. It is removed during shutdown.

MERCIFUL

private static final boolean MERCIFUL

See Also:

killAllConnections(java.lang.String), Constant Field Values

Constructor Detail

ProxoolFacade

public ProxoolFacade()

Method Detail

registerConnectionPool

public static java.lang.String registerConnectionPool(java.lang.String url,
                                                      java.util.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 java.lang.String registerConnectionPool(java.lang.String url,
                                                         java.util.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(ConnectionPoolDefinition connectionPoolDefinition)
                                      throws ProxoolException

Throws:

ProxoolException

registerConnectionPool

public static void registerConnectionPool(java.lang.String url)
                                   throws ProxoolException

With no configurator or properties (using default values)

Throws:

ProxoolException

See Also:

registerConnectionPool(java.lang.String, java.util.Properties)

getAlias

protected static java.lang.String getAlias(java.lang.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

removeConnectionPool

private static void removeConnectionPool(java.lang.String finalizer,
                                         ConnectionPool connectionPool,
                                         int delay)

Remove a connection pool. Kills all the connections. Resets everything.

Parameters:

finalizer - the name of the thread requesting shutdown (for logging)

connectionPool - the pool to remove

delay - the time to wait for connections to become inactive before killing it (milliseconds)

removeConnectionPool

public static void removeConnectionPool(java.lang.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

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)

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

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)

shutdown

protected static void shutdown(java.lang.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)

removeConnectionPool

public static void removeConnectionPool(java.lang.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

getConnectionPoolStatistics

public static ConnectionPoolStatisticsIF getConnectionPoolStatistics(java.lang.String alias)
                                                              throws ProxoolException

Deprecated. use getSnapshot(java.lang.String, boolean)

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 java.lang.String getConnectionPoolStatisticsDump(java.lang.String alias)
                                                        throws ProxoolException

Deprecated. use getSnapshot(java.lang.String, boolean)

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

getConnectionPoolDefinition

public static ConnectionPoolDefinitionIF getConnectionPoolDefinition(java.lang.String alias)
                                                              throws ProxoolException

Get the definition of a pool.

Parameters:

alias - identifies the pool

Throws:

ProxoolException - if we couldn't find the pool

getConnectionInfos

public static java.util.Collection getConnectionInfos(java.lang.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

killAllConnections

public static void killAllConnections(java.lang.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

killAllConnections

public static void killAllConnections(java.lang.String alias,
                                      java.lang.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(java.lang.String alias)
                               throws ProxoolException

Deprecated. use alternative to provide better auditing in log

Like killAllConnections(java.lang.String, boolean) but defaults to merciful.

Parameters:

alias - to identify the pool

Throws:

ProxoolException - if we couldn't find the pool

killAllConnections

public static void killAllConnections(java.lang.String alias,
                                      java.lang.String reason)
                               throws ProxoolException

Like killAllConnections(java.lang.String, boolean) 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

killConnecton

public static boolean killConnecton(java.lang.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

killConnecton

public static boolean killConnecton(java.sql.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

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.

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.

setStateListener

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

Deprecated. use addStateListener(String, StateListenerIF) instead.

Throws:

ProxoolException

addStateListener

public static void addStateListener(java.lang.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

removeStateListener

public boolean removeStateListener(java.lang.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

setConnectionListener

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

Deprecated. use addConnectionListener(String, ConnectionListenerIF) instead.

Throws:

ProxoolException

addConnectionListener

public static void addConnectionListener(java.lang.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

removeConnectionListener

public static boolean removeConnectionListener(java.lang.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

setConfigurationListener

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

Deprecated. use addConfigurationListener(String, ConfigurationListenerIF) instead.

Throws:

ProxoolException

addConfigurationListener

public static void addConfigurationListener(java.lang.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

definitionUpdated

protected static void definitionUpdated(java.lang.String alias,
                                        ConnectionPoolDefinitionIF connectionPoolDefinition,
                                        java.util.Properties completeInfo,
                                        java.util.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)

removeConfigurationListener

public static boolean removeConfigurationListener(java.lang.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

redefineConnectionPool

public static void redefineConnectionPool(java.lang.String url,
                                          java.util.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

Throws:

ProxoolException

See Also:

updateConnectionPool(java.lang.String, java.util.Properties)

updateConnectionPool

public static void updateConnectionPool(java.lang.String url,
                                        java.util.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

Throws:

ProxoolException

See Also:

redefineConnectionPool(java.lang.String, java.util.Properties)

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getDelegateStatement

public static java.sql.Statement getDelegateStatement(java.sql.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

Throws:

ProxoolException

getDelegateConnection

public static java.sql.Connection getDelegateConnection(java.sql.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

Throws:

ProxoolException

getId

public static long getId(java.sql.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.

getAlias

public static java.lang.String getAlias(java.sql.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.

getAliases

public static java.lang.String[] getAliases()

Get a list of all the registered pools

Returns:

an array of aliases

Since:

Proxool 0.7

getStatistics

public static StatisticsIF getStatistics(java.lang.String alias,
                                         java.lang.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

getStatistics

public static StatisticsIF[] getStatistics(java.lang.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

addStatisticsListener

public static void addStatisticsListener(java.lang.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

getSnapshot

public static SnapshotIF getSnapshot(java.lang.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

getSnapshot

public static SnapshotIF getSnapshot(java.lang.String alias)
                              throws ProxoolException

Calls getSnapshot using false for the detail parameter.

Throws:

ProxoolException

See Also:

getSnapshot(java.lang.String, boolean)

registerForJmx

private static boolean registerForJmx(java.lang.String alias,
                                      java.util.Properties properties)

registerDataSource

private static boolean registerDataSource(java.lang.String alias,
                                          java.util.Properties jndiProperties)

extractJndiProperties

private static java.util.Properties extractJndiProperties(ConnectionPoolDefinition connectionPoolDefinition)

Get the JNDI properties for the given pool definition if it is configured for JNDI registration. Will remove generic JNDI properties from the delegate properties so that they will not be passed to the delegate driver.

Parameters:

connectionPoolDefinition - the pool definition to get the eventual JNDI configuration from.

Returns:

the JNDI properties, or null if the given definition was not configured for JNDI.

isConfiguredForJMX

private static boolean isConfiguredForJMX(java.util.Properties poolProperties)

Get wether the given pool properties contains configuration for JMX instrumentation of the pool.

Parameters:

poolProperties - the properties to check for JMX configuration.

Returns:

wether the given pool properties contains configuration for JMX instrumentation or not.

setShutdownHook

protected static void setShutdownHook(java.lang.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