org.apache.tomcat.jdbc.pool

## Class ConnectionPool

- java.lang.Object
- - org.apache.tomcat.jdbc.pool.ConnectionPool

    public class ConnectionPool
    extends 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
Author:
  Filip Hanik

### Nested Class Summary

Nested Classes
`protected class` `ConnectionPool.ConnectionFuture` Tread 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
`protected ConnectionPool` `jmxPool` reference to the JMX mbean
`static String` `POOL_JMX_DOMAIN` Default domain for objects registering with an mbean server
`static String` `POOL_JMX_TYPE_PREFIX` Prefix type for JMX registration

### Constructor Summary

Constructors
Constructor and Description
`ConnectionPool(PoolConfiguration prop)` Instantiate a connection pool.

### Method Summary

Methods
`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, String username, 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)`
`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, String username, 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
`Connection` `getConnection()` Borrows a connection from the pool.
`Connection` `getConnection(String username, String password)` Borrows a connection from the pool.
`Future<Connection>` `getConnectionAsync()` Retrieves a Connection future.
`int` `getIdle()` Returns the number of idle connections
`ConnectionPool` `getJmxPool()` Return the object that is potentially registered in JMX for notifications
`String` `getName()` Returns the name of this pool
`static Set<TimerTask>` `getPoolCleaners()`
`PoolConfiguration` `getPoolProperties()` Returns the pool properties associated with this connection pool
`static Timer` `getPoolTimer()`
`long` `getPoolVersion()`
`Constructor<?>` `getProxyConstructor(boolean xa)` Creates and caches a `Constructor` used to instantiate the proxy object.
`int` `getSize()` Returns the total size of this pool, this includes both busy and idle connections
`static String` `getStackTrace(Throwable x)` Convert an exception into a String
`protected static 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
`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 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 abandon a connection signals a connection to be abandoned.
`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 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 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 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:
  `SQLException`

### Method Detail

#### getConnectionAsync

    public Future<Connection> getConnectionAsync()
                                          throws 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:
  `SQLException`

#### getConnection

    public Connection getConnection()
                             throws 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:
  `SQLException` - - if the wait times out or a failure occurs creating a connection

#### getConnection

    public Connection getConnection(String username,
                           String password)
                             throws 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:
  `SQLException` - - if the wait times out or a failure occurs creating a connection

#### getName

    public 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 Connection setupConnection(PooledConnection con)
                                  throws 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:
  `SQLException` - if an interceptor can't be configured, if the proxy can't be instantiated

#### getProxyConstructor

    public Constructor<?> getProxyConstructor(boolean xa)
                                       throws NoSuchMethodException

Creates and caches a `Constructor` used to instantiate the proxy object. We cache this, since the creation of a constructor is fairly slow.

Returns:
  constructor used to instantiate the wrapper object
Throws:
  `NoSuchMethodException`

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

Initialize the connection pool - called from the constructor

Parameters:
  `properties` - PoolProperties - properties used to initialize the pool with
Throws:
  `SQLException` - if initialization fails

#### initializePoolCleaner

    public void initializePoolCleaner(PoolConfiguration properties)

#### 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 logAbanded=true

Parameters:
  `con` - PooledConnection

#### suspect

    protected void suspect(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 logAbanded=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,
                                    String username,
                                    String password)
                                         throws SQLException

Creates a JDBC connection and tries to connect to the database.

Parameters:
  `now` - timestamp of when this was called
  `notUsed` - Argument not used
Returns:
  a PooledConnection that has been connected
Throws:
  `SQLException`

#### borrowConnection

    protected PooledConnection borrowConnection(long now,
                                    PooledConnection con,
                                    String username,
                                    String password)
                                         throws SQLException

Validates and configures a previously idle connection

Parameters:
  `now` - - timestamp
  `con` - - the connection to validate and configure
Returns:
  con
Throws:
  `SQLException` - if a validation error happens

#### terminateTransaction

    protected boolean terminateTransaction(PooledConnection con)

Terminate the current transaction for the given connection.

Parameters:
  `con` -
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 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 String getStackTrace(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.

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

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

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

#### getPoolCleaners

    public static Set<TimerTask> getPoolCleaners()

#### getPoolVersion

    public long getPoolVersion()

#### getPoolTimer

    public static Timer getPoolTimer()