ConnectionPool (Apache Tomcat 7.0.67 API Documentation)

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.

Version:

1.0

Author:

Filip Hanik

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`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
Modifier and Type	Field and 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 and Description

ConnectionPool(PoolConfiguration prop)
Instantiate a connection pool.

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

Method Summary

Methods
Modifier and Type	Method and 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
`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.
`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.
`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
`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 abandon a connection signals a connection to be abandoned.
`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
- 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
  - 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.
    
    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.
    
    Returns:
    constructor used to instantiate the wrapper object
    
    Throws:
    
    java.lang.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 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 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,
                                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
    
    Returns:
    a PooledConnection that has been connected
    
    Throws:
    
    java.sql.SQLException
  - 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
    
    Returns:
    con
    
    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 -
    
    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.
    
    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 java.util.Set<java.util.TimerTask> getPoolCleaners()
```
  - getPoolVersion
```
public long getPoolVersion()
```
  - getPoolTimer
```
public static java.util.Timer getPoolTimer()
```

Class ConnectionPool

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

POOL_JMX_DOMAIN

POOL_JMX_TYPE_PREFIX

jmxPool

Constructor Detail

ConnectionPool

Method Detail

getConnectionAsync

getConnection

getConnection

getName

getWaitCount

getPoolProperties

getSize

getActive

getIdle

isClosed

setupConnection

getProxyConstructor

close

init

checkPoolConfiguration

initializePoolCleaner

terminatePoolCleaner

abandon

suspect

release

createConnection

borrowConnection

terminateTransaction

shouldClose

returnConnection

shouldAbandon

checkAbandoned

checkIdle

checkIdle

shouldReleaseIdle

testAllIdle

getThreadDump

getStackTrace

create

purge

purgeOnReturn

finalize

disconnectEvent

getJmxPool

createMBean

getPoolCleaners

getPoolVersion

getPoolTimer