Package org.apache.tomcat.jdbc.pool

## Class ConnectionPool

- java.lang.Object
- - org.apache.tomcat.jdbc.pool.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.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected class` | `ConnectionPool.ConnectionFuture` | Thread safe wrapper around a future for the regular queue This one retrieves the pooled connection object and performs the initialization according to interceptors and validation rules.
    `protected static class` | `ConnectionPool.PoolCleaner` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected ConnectionPool` | `jmxPool` | reference to the JMX mbean
    `static java.lang.String` | `POOL_JMX_DOMAIN` | Default domain for objects registering with an mbean server
    `static java.lang.String` | `POOL_JMX_TYPE_PREFIX` | Prefix type for JMX registration

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ConnectionPool​(PoolConfiguration prop)` | Instantiate a connection pool.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `abandon​(PooledConnection con)` | thread safe way to abandon a connection signals a connection to be abandoned.
    `protected PooledConnection` | `borrowConnection​(long now, PooledConnection con, java.lang.String username, java.lang.String password)` | Validates and configures a previously idle connection
    `void` | `checkAbandoned()` | Iterates through all the busy connections and checks for connections that have timed out
    `void` | `checkIdle()` | Iterates through the idle connections and resizes the idle pool based on parameters `PoolProperties.maxIdle`, `PoolProperties.minIdle`, `PoolProperties.minEvictableIdleTimeMillis`
    `void` | `checkIdle​(boolean ignoreMinSize)` |
    `void` | `checkPoolConfiguration​(PoolConfiguration properties)` |
    `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
    `protected PooledConnection` | `create​(boolean incrementCounter)` | Create a new pooled connection object.
    `protected PooledConnection` | `createConnection​(long now, PooledConnection notUsed, java.lang.String username, java.lang.String password)` | Creates a JDBC connection and tries to connect to the database.
    `protected void` | `createMBean()` | Create MBean object that can be registered.
    `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
    `protected void` | `finalize​(PooledConnection con)` | Hook to perform final actions on a pooled connection object once it has been disconnected and will be discarded
    `int` | `getActive()` | Returns the number of connections that are in use
    `long` | `getBorrowedCount()` | The total number of connections borrowed from this pool.
    `java.sql.Connection` | `getConnection()` | Borrows a connection from the pool.
    `java.sql.Connection` | `getConnection​(java.lang.String username, java.lang.String password)` | Borrows a connection from the pool.
    `java.util.concurrent.Future<java.sql.Connection>` | `getConnectionAsync()` | Retrieves a Connection future.
    `long` | `getCreatedCount()` | The total number of connections created by this pool.
    `int` | `getIdle()` | Returns the number of idle connections
    `ConnectionPool` | `getJmxPool()` | Return the object that is potentially registered in JMX for notifications
    `java.lang.String` | `getName()` | Returns the name of this pool
    `static java.util.Set<java.util.TimerTask>` | `getPoolCleaners()` |
    `PoolConfiguration` | `getPoolProperties()` | Returns the pool properties associated with this connection pool
    `static java.util.Timer` | `getPoolTimer()` |
    `long` | `getPoolVersion()` |
    `java.lang.reflect.Constructor<?>` | `getProxyConstructor​(boolean xa)` | Creates and caches a `Constructor` used to instantiate the proxy object.
    `long` | `getReconnectedCount()` | The total number of connections reconnected by this pool.
    `long` | `getReleasedCount()` | The total number of connections released from this pool.
    `long` | `getReleasedIdleCount()` | The total number of connections released by eviction.
    `long` | `getRemoveAbandonedCount()` | The total number of connections released by remove abandoned.
    `long` | `getReturnedCount()` | The total number of connections returned to this pool.
    `int` | `getSize()` | Returns the total size of this pool, this includes both busy and idle connections
    `static java.lang.String` | `getStackTrace​(java.lang.Throwable x)` | Convert an exception into a String
    `protected static java.lang.String` | `getThreadDump()` | Creates a stack trace representing the existing thread's current state.
    `int` | `getWaitCount()` | Return the number of threads waiting for a connection
    `protected void` | `init​(PoolConfiguration properties)` | Initialize the connection pool - called from the constructor
    `void` | `initializePoolCleaner​(PoolConfiguration properties)` |
    `boolean` | `isClosed()` | Returns true if `close` has been called, and the connection pool is unusable
    `void` | `purge()` | Purges all connections in the pool.
    `void` | `purgeOnReturn()` | Purges connections when they are returned from the pool.
    `protected void` | `release​(PooledConnection con)` | thread safe way to release a connection
    `void` | `resetStats()` | reset the statistics of this pool.
    `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.
    `protected java.sql.Connection` | `setupConnection​(PooledConnection con)` | configures a pooled connection as a proxy.
    `protected boolean` | `shouldAbandon()` | Determines if a connection should be abandoned based on `PoolProperties.abandonWhenPercentageFull` setting.
    `protected boolean` | `shouldClose​(PooledConnection con, int action)` | Determines if a connection should be closed upon return to the pool.
    `protected boolean` | `shouldReleaseIdle​(long now, PooledConnection con, long time)` |
    `protected void` | `suspect​(PooledConnection con)` | Thread safe way to suspect a connection.
    `void` | `terminatePoolCleaner()` |
    `protected boolean` | `terminateTransaction​(PooledConnection con)` | Terminate the current transaction for the given connection.
    `void` | `testAllIdle()` | Forces a validation of all idle connections if `PoolProperties.testWhileIdle` is set.

    - ### Methods inherited from class java.lang.Object

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

- - ### 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

    - #### 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()

      Iterates through the idle connections and resizes the idle pool based on parameters `PoolProperties.maxIdle`, `PoolProperties.minIdle`, `PoolProperties.minEvictableIdleTimeMillis`

    - #### checkIdle

          public void checkIdle​(boolean ignoreMinSize)

    - #### shouldReleaseIdle

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

    - #### testAllIdle

          public void testAllIdle()

      Forces a validation of all idle connections if `PoolProperties.testWhileIdle` is set.

    - #### 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()