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

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

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, 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)
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, 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.
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 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 - Pool initialization error

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 - Cannot use asyncronous connect

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.

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:

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.

Parameters:

xa - Use a XA connection

Returns:

constructor used to instantiate the wrapper object

Throws:

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 SQLException

Initialize the connection pool - called from the constructor

Parameters:

properties - PoolProperties - properties used to initialize the pool with

Throws:

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

username - The user name to use for the connection

password - The password for the connection

Returns:

a PooledConnection that has been connected

Throws:

SQLException - Failed to get a connection

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

username - The user name to use for the connection

password - The password for the connection

Returns:

a connection

Throws:

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

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.

getPoolCleaners

public static Set<TimerTask> getPoolCleaners()

getPoolVersion

public long getPoolVersion()

getPoolTimer

public static Timer getPoolTimer()