Package org.apache.tomcat.jdbc.pool

Class ConnectionPool

  • public class ConnectionPool
extends java.lang.Object
    Implementation of simple connection pool. The ConnectionPool uses a PoolProperties object for storing all the meta information about the connection pool. As the underlying implementation, the connection pool uses BlockingQueue to store active and idle connections. A custom implementation of a fair FairBlockingQueue blocking queue is provided with the connection pool itself.
    Version:
    1.0

    • Field Detail

      • POOL_JMX_DOMAIN

        public static final java.lang.String POOL_JMX_DOMAIN
        Default domain for objects registering with an mbean server
        See Also:
        Constant Field Values

      • POOL_JMX_TYPE_PREFIX

        public static final java.lang.String POOL_JMX_TYPE_PREFIX
        Prefix type for JMX registration
        See Also:
        Constant Field Values

      • jmxPool

        protected ConnectionPool jmxPool
        reference to the JMX mbean

    • Constructor Detail

      • ConnectionPool

        public ConnectionPool​(PoolConfiguration prop)
               throws java.sql.SQLException
        Instantiate a connection pool. This will create connections if initialSize is larger than 0. The PoolProperties should not be reused for another connection pool.
        Parameters:
        prop - PoolProperties - all the properties for this connection pool
        Throws:
        java.sql.SQLException - Pool initialization error

    • Method Detail

      • getConnectionAsync

        public java.util.concurrent.Future<java.sql.Connection> getConnectionAsync()
                                                                    throws java.sql.SQLException
        Retrieves a Connection future. If a connection is not available, one can block using future.get() until a connection has become available. If a connection is not retrieved, the Future must be cancelled in order for the connection to be returned to the pool.
        Returns:
        a Future containing a reference to the connection or the future connection
        Throws:
        java.sql.SQLException - Cannot use asynchronous connect

      • getConnection

        public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
        Borrows a connection from the pool. If a connection is available (in the idle queue) or the pool has not reached maxActive connections a connection is returned immediately. If no connection is available, the pool will attempt to fetch a connection for maxWait milliseconds.
        Returns:
        Connection - a java.sql.Connection/javax.sql.PooledConnection reflection proxy, wrapping the underlying object.
        Throws:
        java.sql.SQLException - - if the wait times out or a failure occurs creating a connection

      • getConnection

        public java.sql.Connection getConnection​(java.lang.String username,
                                         java.lang.String password)
                                  throws java.sql.SQLException
        Borrows a connection from the pool. If a connection is available (in the idle queue) or the pool has not reached maxActive connections a connection is returned immediately. If no connection is available, the pool will attempt to fetch a connection for maxWait milliseconds.
        Parameters:
        username - The user name to use for the connection
        password - The password for the connection
        Returns:
        Connection - a java.sql.Connection/javax.sql.PooledConnection reflection proxy, wrapping the underlying object.
        Throws:
        java.sql.SQLException - - if the wait times out or a failure occurs creating a connection

      • getName

        public java.lang.String getName()
        Returns the name of this pool
        Returns:
        String - the name of the pool

      • getWaitCount

        public int getWaitCount()
        Return the number of threads waiting for a connection
        Returns:
        number of threads waiting for a connection

      • getPoolProperties

        public PoolConfiguration getPoolProperties()
        Returns the pool properties associated with this connection pool
        Returns:
        PoolProperties

      • getSize

        public int getSize()
        Returns the total size of this pool, this includes both busy and idle connections
        Returns:
        int - number of established connections to the database

      • getActive

        public int getActive()
        Returns the number of connections that are in use
        Returns:
        int - number of established connections that are being used by the application

      • getIdle

        public int getIdle()
        Returns the number of idle connections
        Returns:
        int - number of established connections not being used

      • isClosed

        public boolean isClosed()
        Returns true if close has been called, and the connection pool is unusable
        Returns:
        boolean

      • setupConnection

        protected java.sql.Connection setupConnection​(PooledConnection con)
                                       throws java.sql.SQLException
        configures a pooled connection as a proxy. This Proxy implements Connection and PooledConnection interfaces. All calls on Connection methods will be propagated down to the actual JDBC connection except for the Connection.close() method.
        Parameters:
        con - a PooledConnection to wrap in a Proxy
        Returns:
        a Connection object wrapping a pooled connection.
        Throws:
        java.sql.SQLException - if an interceptor can't be configured, if the proxy can't be instantiated

      • getProxyConstructor

        public java.lang.reflect.Constructor<?> getProxyConstructor​(boolean xa)
                                                     throws java.lang.NoSuchMethodException
        Creates and caches a Constructor used to instantiate the proxy object. We cache this, since the creation of a constructor is fairly slow.
        Parameters:
        xa - Use a XA connection
        Returns:
        constructor used to instantiate the wrapper object
        Throws:
        java.lang.NoSuchMethodException - Failed to get a constructor

      • close

        protected void close​(boolean force)
        Closes the pool and all disconnects all idle connections Active connections will be closed upon the close method is called on the underlying connection instead of being returned to the pool
        Parameters:
        force - - true to even close the active connections

      • init

        protected void init​(PoolConfiguration properties)
             throws java.sql.SQLException
        Initialize the connection pool - called from the constructor
        Parameters:
        properties - PoolProperties - properties used to initialize the pool with
        Throws:
        java.sql.SQLException - if initialization fails

      • checkPoolConfiguration

        public void checkPoolConfiguration​(PoolConfiguration properties)

      • initializePoolCleaner

        public void initializePoolCleaner​(PoolConfiguration properties)

      • terminatePoolCleaner

        public void terminatePoolCleaner()

      • abandon

        protected void abandon​(PooledConnection con)
        thread safe way to abandon a connection signals a connection to be abandoned. this will disconnect the connection, and log the stack trace if logAbandoned=true
        Parameters:
        con - PooledConnection

      • suspect

        protected void suspect​(PooledConnection con)
        Thread safe way to suspect a connection. Similar to abandon(PooledConnection), but instead of actually abandoning the connection, this will log a warning and set the suspect flag on the PooledConnection if logAbandoned=true
        Parameters:
        con - PooledConnection

      • release

        protected void release​(PooledConnection con)
        thread safe way to release a connection
        Parameters:
        con - PooledConnection

      • createConnection

        protected PooledConnection createConnection​(long now,
                                            PooledConnection notUsed,
                                            java.lang.String username,
                                            java.lang.String password)
                                     throws java.sql.SQLException
        Creates a JDBC connection and tries to connect to the database.
        Parameters:
        now - timestamp of when this was called
        notUsed - Argument not used
        username - The user name to use for the connection
        password - The password for the connection
        Returns:
        a PooledConnection that has been connected
        Throws:
        java.sql.SQLException - Failed to get a connection

      • borrowConnection

        protected PooledConnection borrowConnection​(long now,
                                            PooledConnection con,
                                            java.lang.String username,
                                            java.lang.String password)
                                     throws java.sql.SQLException
        Validates and configures a previously idle connection
        Parameters:
        now - - timestamp
        con - - the connection to validate and configure
        username - The user name to use for the connection
        password - The password for the connection
        Returns:
        a connection
        Throws:
        java.sql.SQLException - if a validation error happens

      • terminateTransaction

        protected boolean terminateTransaction​(PooledConnection con)
        Terminate the current transaction for the given connection.
        Parameters:
        con - The connection
        Returns:
        true if the connection TX termination succeeded otherwise false

      • shouldClose

        protected boolean shouldClose​(PooledConnection con,
                              int action)
        Determines if a connection should be closed upon return to the pool.
        Parameters:
        con - - the connection
        action - - the validation action that should be performed
        Returns:
        true if the connection should be closed

      • reconnectIfExpired

        protected boolean reconnectIfExpired​(PooledConnection con)
        Checks whether this connection has expired and tries to reconnect if it has.
        Parameters:
        con - PooledConnection
        Returns:
        true if the connection was either not expired or expired but reconnecting succeeded, false if reconnecting failed (either because a new connection could not be established or validating the newly created connection failed)
        See Also:
        PooledConnection.isMaxAgeExpired()

      • returnConnection

        protected void returnConnection​(PooledConnection con)
        Returns a connection to the pool If the pool is closed, the connection will be released If the connection is not part of the busy queue, it will be released. If PoolProperties.testOnReturn is set to true it will be validated
        Parameters:
        con - PooledConnection to be returned to the pool

      • shouldAbandon

        protected boolean shouldAbandon()
        Determines if a connection should be abandoned based on PoolProperties.abandonWhenPercentageFull setting.
        Returns:
        true if the connection should be abandoned

      • checkAbandoned

        public void checkAbandoned()
        Iterates through all the busy connections and checks for connections that have timed out

      • checkIdle

        public void checkIdle​(boolean ignoreMinSize)

      • shouldReleaseIdle

        protected boolean shouldReleaseIdle​(long now,
                                    PooledConnection con,
                                    long time)

      • getThreadDump

        protected static java.lang.String getThreadDump()
        Creates a stack trace representing the existing thread's current state.
        Returns:
        a string object representing the current state. TODO investigate if we simply should store Thread.getStackTrace() elements

      • getStackTrace

        public static java.lang.String getStackTrace​(java.lang.Throwable x)
        Convert an exception into a String
        Parameters:
        x - - the throwable
        Returns:
        a string representing the stack trace

      • create

        protected PooledConnection create​(boolean incrementCounter)
        Create a new pooled connection object. Not connected nor validated.
        Parameters:
        incrementCounter - true to increment the connection count
        Returns:
        a pooled connection object

      • purge

        public void purge()
        Purges all connections in the pool. For connections currently in use, these connections will be purged when returned on the pool. This call also purges connections that are idle and in the pool To only purge used/active connections see purgeOnReturn()

      • purgeOnReturn

        public void purgeOnReturn()
        Purges connections when they are returned from the pool. This call does not purge idle connections until they are used. To purge idle connections see purge()

      • finalize

        protected void finalize​(PooledConnection con)
        Hook to perform final actions on a pooled connection object once it has been disconnected and will be discarded
        Parameters:
        con - The connection

      • disconnectEvent

        protected void disconnectEvent​(PooledConnection con,
                               boolean finalizing)
        Hook to perform final actions on a pooled connection object once it has been disconnected and will be discarded
        Parameters:
        con - The connection
        finalizing - true if finalizing the connection

      • getJmxPool

        public ConnectionPool getJmxPool()
        Return the object that is potentially registered in JMX for notifications
        Returns:
        the object implementing the ConnectionPoolMBean interface

      • createMBean

        protected void createMBean()
        Create MBean object that can be registered.

      • getBorrowedCount

        public long getBorrowedCount()
        The total number of connections borrowed from this pool.
        Returns:
        the borrowed connection count

      • getReturnedCount

        public long getReturnedCount()
        The total number of connections returned to this pool.
        Returns:
        the returned connection count

      • getCreatedCount

        public long getCreatedCount()
        The total number of connections created by this pool.
        Returns:
        the created connection count

      • getReleasedCount

        public long getReleasedCount()
        The total number of connections released from this pool.
        Returns:
        the released connection count

      • getReconnectedCount

        public long getReconnectedCount()
        The total number of connections reconnected by this pool.
        Returns:
        the reconnected connection count

      • getRemoveAbandonedCount

        public long getRemoveAbandonedCount()
        The total number of connections released by remove abandoned.
        Returns:
        the PoolCleaner removed abandoned connection count

      • getReleasedIdleCount

        public long getReleasedIdleCount()
        The total number of connections released by eviction.
        Returns:
        the PoolCleaner evicted idle connection count

      • resetStats

        public void resetStats()
        reset the statistics of this pool.

      • getPoolCleaners

        public static java.util.Set<java.util.TimerTask> getPoolCleaners()

      • getPoolVersion

        public long getPoolVersion()

      • getPoolTimer

        public static java.util.Timer getPoolTimer()