Class 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.87 $, $Date: 2007/05/15 23:00:22 $
    Author:
    billhorsman, $Author: billhorsman $ (current maintainer)
    • 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​(org.logicalcobwebs.proxool.ConnectionPoolDefinition connectionPoolDefinition)
                                              throws ProxoolException
        Throws:
        ProxoolException
      • 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

        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)
      • disableShutdownHook

        public static void disableShutdownHook()
        If you call this then you'll have to call shutdown explicitly
        See Also:
        shutdown(String, int)
      • 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.
      • isShutdownHookEnabled

        public static boolean isShutdownHookEnabled()
        Whether the ShutdownHook should do anything.
        Returns:
        true if the shutdown hook should clean up
        See Also:
        disableShutdownHook(), enableShutdownHook()
      • getConnectionPoolStatisticsDump

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