Package org.apache.tomcat.dbcp.dbcp2

Class PoolingConnection

java.lang.Object

org.apache.tomcat.dbcp.dbcp2.AbandonedTrace

org.apache.tomcat.dbcp.dbcp2.DelegatingConnection<Connection>

org.apache.tomcat.dbcp.dbcp2.PoolingConnection

All Implemented Interfaces:

AutoCloseable, Connection, Wrapper, KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>, TrackedUse

public class PoolingConnection
extends DelegatingConnection<Connection>
implements KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>

A DelegatingConnection that pools PreparedStatements.

The prepareStatement(org.apache.tomcat.dbcp.dbcp2.PStmtKey) and prepareCall(org.apache.tomcat.dbcp.dbcp2.PStmtKey) methods, rather than creating a new PreparedStatement each time, may actually pull the statement from a pool of unused statements. The Statement.close() method of the returned statement doesn't actually close the statement, but rather returns it to the pool. (See PoolablePreparedStatement, PoolableCallableStatement.)

Since:

2.0

See Also:

• PoolablePreparedStatement

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	PoolingConnection.StatementType	Statement types.

Field Summary

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Constructor Summary

Constructors

Constructor	Description
PoolingConnection(Connection connection)	Constructor.

Method Summary

Modifier and Type	Method	Description
void	activateObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> pooledObject)	KeyedPooledObjectFactory method for activating pooled statements.
void	close()	Closes and frees all PreparedStatements or CallableStatements from the pool, and close the underlying connection.
void	connectionReturnedToPool()	Notification from PoolableConnection that we returned to the pool.
protected PStmtKey	createKey(String sql)	Creates a PStmtKey for the given arguments.
protected PStmtKey	createKey(String sql, int autoGeneratedKeys)	Creates a PStmtKey for the given arguments.
protected PStmtKey	createKey(String sql, int[] columnIndexes)	Creates a PStmtKey for the given arguments.
protected PStmtKey	createKey(String sql, int resultSetType, int resultSetConcurrency)	Creates a PStmtKey for the given arguments.
protected PStmtKey	createKey(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)	Creates a PStmtKey for the given arguments.
protected PStmtKey	createKey(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability, PoolingConnection.StatementType statementType)	Creates a PStmtKey for the given arguments.
protected PStmtKey	createKey(String sql, int resultSetType, int resultSetConcurrency, PoolingConnection.StatementType statementType)	Creates a PStmtKey for the given arguments.
protected PStmtKey	createKey(String sql, String[] columnNames)	Creates a PStmtKey for the given arguments.
protected PStmtKey	createKey(String sql, PoolingConnection.StatementType statementType)	Creates a PStmtKey for the given arguments.
void	destroyObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> pooledObject)	KeyedPooledObjectFactory method for destroying PoolablePreparedStatements and PoolableCallableStatements.
void	destroyObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> p, DestroyMode mode)	Destroy an instance no longer needed by the pool, using the provided DestroyMode.
KeyedObjectPool<PStmtKey,DelegatingPreparedStatement>	getStatementPool()	Returns the prepared statement pool we're using.
PooledObject<DelegatingPreparedStatement>	makeObject(PStmtKey key)	KeyedPooledObjectFactory method for creating PoolablePreparedStatements or PoolableCallableStatements.
protected String	normalizeSQL(String sql)	Normalizes the given SQL statement, producing a canonical form that is semantically equivalent to the original.
void	passivateObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> pooledObject)	KeyedPooledObjectFactory method for passivating PreparedStatements or CallableStatements.
CallableStatement	prepareCall(String sql)	Creates or obtains a CallableStatement from the pool.
CallableStatement	prepareCall(String sql, int resultSetType, int resultSetConcurrency)	Creates or obtains a CallableStatement from the pool.
CallableStatement	prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)	Creates or obtains a CallableStatement from the pool.
PreparedStatement	prepareStatement(String sql)	Creates or obtains a PreparedStatement from the pool.
PreparedStatement	prepareStatement(String sql, int autoGeneratedKeys)
PreparedStatement	prepareStatement(String sql, int[] columnIndexes)	Creates or obtains a PreparedStatement from the pool.
PreparedStatement	prepareStatement(String sql, int resultSetType, int resultSetConcurrency)	Creates or obtains a PreparedStatement from the pool.
PreparedStatement	prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)	Creates or obtains a PreparedStatement from the pool.
PreparedStatement	prepareStatement(String sql, String[] columnNames)	Creates or obtains a PreparedStatement from the pool.
void	setClearStatementPoolOnReturn(boolean clearStatementPoolOnReturn)	Sets whether the pool of statements should be cleared when the connection is returned to its pool.
void	setStatementPool(KeyedObjectPool<PStmtKey,DelegatingPreparedStatement> pool)	Sets the prepared statement pool.
String	toString()	Returns a string representation of the metadata associated with the innermost delegate connection.
boolean	validateObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> pooledObject)	KeyedPooledObjectFactory method for validating pooled statements.

Methods inherited from class org.apache.tomcat.dbcp.dbcp2.DelegatingConnection

abort, activate, checkOpen, clearCachedState, clearWarnings, closeInternal, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCacheState, getCatalog, getClientInfo, getClientInfo, getDefaultQueryTimeout, getDelegate, getDelegateInternal, getHoldability, getInnermostDelegate, getInnermostDelegateInternal, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, handleException, handleExceptionNoThrow, innermostDelegateEquals, isClosed, isClosedInternal, isReadOnly, isValid, isWrapperFor, nativeSQL, passivate, releaseSavepoint, rollback, rollback, setAutoCommit, setCacheState, setCatalog, setClientInfo, setClientInfo, setClosedInternal, setDefaultQueryTimeout, setDelegate, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap, unwrap

Methods inherited from class org.apache.tomcat.dbcp.dbcp2.AbandonedTrace

addTrace, clearTrace, getLastUsed, getTrace, removeThisTrace, removeTrace, setLastUsed, setLastUsed

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.sql.Connection

beginRequest, endRequest, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid

Constructor Details

PoolingConnection

public PoolingConnection(Connection connection)

Constructor.

Parameters:

connection - the underlying Connection.

Method Details

activateObject

public void activateObject(PStmtKey key,
 PooledObject<DelegatingPreparedStatement> pooledObject)
                    throws Exception

KeyedPooledObjectFactory method for activating pooled statements.

Specified by:

activateObject in interface KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>

Parameters:

key - ignored

pooledObject - wrapped pooled statement to be activated

Throws:

Exception - if there is a problem activating obj, this exception may be swallowed by the pool.

See Also:

• KeyedPooledObjectFactory.destroyObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)

close

public void close()
           throws SQLException

Closes and frees all PreparedStatements or CallableStatements from the pool, and close the underlying connection.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Connection

Overrides:

close in class DelegatingConnection<Connection>

Throws:

SQLException

connectionReturnedToPool

public void connectionReturnedToPool()
                              throws SQLException

Notification from PoolableConnection that we returned to the pool.

Throws:

SQLException - when clearStatementPoolOnReturn is true and the statement pool could not be cleared

Since:

2.8.0

createKey

protected PStmtKey createKey(String sql)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

Returns:

the PStmtKey created for the given arguments.

createKey

protected PStmtKey createKey(String sql,
 int[] columnIndexes)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

columnIndexes - An array of column indexes indicating the columns that should be returned from the inserted row or rows.

Returns:

the PStmtKey created for the given arguments.

createKey

protected PStmtKey createKey(String sql,
 int autoGeneratedKeys)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

autoGeneratedKeys - A flag indicating whether auto-generated keys should be returned; one of Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS.

Returns:

the PStmtKey created for the given arguments.

createKey

protected PStmtKey createKey(String sql,
 int resultSetType,
 int resultSetConcurrency)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

resultSetType - result set type

resultSetConcurrency - result set concurrency

Returns:

the PStmtKey created for the given arguments.

createKey

protected PStmtKey createKey(String sql,
 int resultSetType,
 int resultSetConcurrency,
 int resultSetHoldability)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

resultSetType - result set type

resultSetConcurrency - result set concurrency

resultSetHoldability - result set holdability

Returns:

the PStmtKey created for the given arguments.

createKey

protected PStmtKey createKey(String sql,
 int resultSetType,
 int resultSetConcurrency,
 int resultSetHoldability,
 PoolingConnection.StatementType statementType)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

resultSetType - result set type

resultSetConcurrency - result set concurrency

resultSetHoldability - result set holdability

statementType - statement type

Returns:

the PStmtKey created for the given arguments.

createKey

protected PStmtKey createKey(String sql,
 int resultSetType,
 int resultSetConcurrency,
 PoolingConnection.StatementType statementType)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

resultSetType - result set type

resultSetConcurrency - result set concurrency

statementType - statement type

Returns:

the PStmtKey created for the given arguments.

createKey

protected PStmtKey createKey(String sql,
 PoolingConnection.StatementType statementType)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

statementType - statement type

Returns:

the PStmtKey created for the given arguments.

createKey

protected PStmtKey createKey(String sql,
 String[] columnNames)

Creates a PStmtKey for the given arguments.

Parameters:

sql - the SQL string used to define the statement

columnNames - column names

Returns:

the PStmtKey created for the given arguments.

destroyObject

public void destroyObject(PStmtKey key,
 PooledObject<DelegatingPreparedStatement> pooledObject)
                   throws Exception

KeyedPooledObjectFactory method for destroying PoolablePreparedStatements and PoolableCallableStatements. Closes the underlying statement.

Specified by:

destroyObject in interface KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>

Parameters:

key - ignored

pooledObject - the wrapped pooled statement to be destroyed.

Throws:

Exception - should be avoided as it may be swallowed by the pool implementation.

See Also:

• KeyedPooledObjectFactory.validateObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)
• KeyedObjectPool.invalidateObject(K, V)

destroyObject

public void destroyObject(PStmtKey key,
 PooledObject<DelegatingPreparedStatement> p,
 DestroyMode mode)
                   throws Exception

Description copied from interface: KeyedPooledObjectFactory

Destroy an instance no longer needed by the pool, using the provided DestroyMode.

Specified by:

destroyObject in interface KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>

Parameters:

key - the key used when selecting the instance

p - a PooledObject wrapping the instance to be destroyed

mode - DestroyMode providing context to the factory

Throws:

Exception - should be avoided as it may be swallowed by the pool implementation.

See Also:

• KeyedPooledObjectFactory.validateObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)
• KeyedObjectPool.invalidateObject(K, V)
• KeyedPooledObjectFactory.destroyObject(Object, PooledObject)
• DestroyMode

getStatementPool

public KeyedObjectPool<PStmtKey,DelegatingPreparedStatement> getStatementPool()

Returns the prepared statement pool we're using.

Returns:

statement pool

Since:

2.8.0

makeObject

public PooledObject<DelegatingPreparedStatement> makeObject(PStmtKey key)
                                                     throws Exception

KeyedPooledObjectFactory method for creating PoolablePreparedStatements or PoolableCallableStatements. The stmtType field in the key determines whether a PoolablePreparedStatement or PoolableCallableStatement is created.

Specified by:

makeObject in interface KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>

Parameters:

key - the key for the PreparedStatement to be created

Returns:

a PooledObject wrapping an instance that can be served by the pool.

Throws:

Exception - if there is a problem creating a new instance, this will be propagated to the code requesting an object.

See Also:

• createKey(String, int, int, StatementType)

normalizeSQL

protected String normalizeSQL(String sql)

Normalizes the given SQL statement, producing a canonical form that is semantically equivalent to the original.

Parameters:

sql - The statement to be normalized.

Returns:

The canonical form of the supplied SQL statement.

passivateObject

public void passivateObject(PStmtKey key,
 PooledObject<DelegatingPreparedStatement> pooledObject)
                     throws Exception

KeyedPooledObjectFactory method for passivating PreparedStatements or CallableStatements. Invokes PreparedStatement.clearParameters().

Specified by:

passivateObject in interface KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>

Parameters:

key - ignored

pooledObject - a wrapped PreparedStatement

Throws:

Exception - if there is a problem passivating obj, this exception may be swallowed by the pool.

See Also:

• KeyedPooledObjectFactory.destroyObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)

prepareCall

public CallableStatement prepareCall(String sql)
                              throws SQLException

Creates or obtains a CallableStatement from the pool.

Specified by:

prepareCall in interface Connection

Overrides:

prepareCall in class DelegatingConnection<Connection>

Parameters:

sql - the SQL string used to define the CallableStatement

Returns:

a PoolableCallableStatement

Throws:

SQLException - Wraps an underlying exception.

prepareCall

public CallableStatement prepareCall(String sql,
 int resultSetType,
 int resultSetConcurrency)
                              throws SQLException

Creates or obtains a CallableStatement from the pool.

Specified by:

prepareCall in interface Connection

Overrides:

prepareCall in class DelegatingConnection<Connection>

Parameters:

sql - the SQL string used to define the CallableStatement

resultSetType - result set type

resultSetConcurrency - result set concurrency

Returns:

a PoolableCallableStatement

Throws:

SQLException - Wraps an underlying exception.

prepareCall

public CallableStatement prepareCall(String sql,
 int resultSetType,
 int resultSetConcurrency,
 int resultSetHoldability)
                              throws SQLException

Creates or obtains a CallableStatement from the pool.

Specified by:

prepareCall in interface Connection

Overrides:

prepareCall in class DelegatingConnection<Connection>

Parameters:

sql - the SQL string used to define the CallableStatement

resultSetType - result set type

resultSetConcurrency - result set concurrency

resultSetHoldability - result set holdability

Returns:

a PoolableCallableStatement

Throws:

SQLException - Wraps an underlying exception.

prepareStatement

public PreparedStatement prepareStatement(String sql)
                                   throws SQLException

Creates or obtains a PreparedStatement from the pool.

Specified by:

prepareStatement in interface Connection

Overrides:

prepareStatement in class DelegatingConnection<Connection>

Parameters:

sql - the SQL string used to define the PreparedStatement

Returns:

a PoolablePreparedStatement

Throws:

SQLException - Wraps an underlying exception.

prepareStatement

public PreparedStatement prepareStatement(String sql,
 int autoGeneratedKeys)
                                   throws SQLException

Specified by:

prepareStatement in interface Connection

Overrides:

prepareStatement in class DelegatingConnection<Connection>

Throws:

SQLException

prepareStatement

public PreparedStatement prepareStatement(String sql,
 int[] columnIndexes)
                                   throws SQLException

Creates or obtains a PreparedStatement from the pool.

Specified by:

prepareStatement in interface Connection

Overrides:

prepareStatement in class DelegatingConnection<Connection>

Parameters:

sql - the SQL string used to define the PreparedStatement

columnIndexes - An array of column indexes indicating the columns that should be returned from the inserted row or rows.

Returns:

a PoolablePreparedStatement

Throws:

SQLException - Wraps an underlying exception.

prepareStatement

public PreparedStatement prepareStatement(String sql,
 int resultSetType,
 int resultSetConcurrency)
                                   throws SQLException

Creates or obtains a PreparedStatement from the pool.

Specified by:

prepareStatement in interface Connection

Overrides:

prepareStatement in class DelegatingConnection<Connection>

Parameters:

sql - the SQL string used to define the PreparedStatement

resultSetType - result set type

resultSetConcurrency - result set concurrency

Returns:

a PoolablePreparedStatement

Throws:

SQLException - Wraps an underlying exception.

prepareStatement

public PreparedStatement prepareStatement(String sql,
 int resultSetType,
 int resultSetConcurrency,
 int resultSetHoldability)
                                   throws SQLException

Creates or obtains a PreparedStatement from the pool.

Specified by:

prepareStatement in interface Connection

Overrides:

prepareStatement in class DelegatingConnection<Connection>

Parameters:

sql - the SQL string used to define the PreparedStatement

resultSetType - result set type

resultSetConcurrency - result set concurrency

resultSetHoldability - result set holdability

Returns:

a PoolablePreparedStatement

Throws:

SQLException - Wraps an underlying exception.

prepareStatement

public PreparedStatement prepareStatement(String sql,
 String[] columnNames)
                                   throws SQLException

Creates or obtains a PreparedStatement from the pool.

Specified by:

prepareStatement in interface Connection

Overrides:

prepareStatement in class DelegatingConnection<Connection>

Parameters:

sql - the SQL string used to define the PreparedStatement

columnNames - column names

Returns:

a PoolablePreparedStatement

Throws:

SQLException - Wraps an underlying exception.

setClearStatementPoolOnReturn

public void setClearStatementPoolOnReturn(boolean clearStatementPoolOnReturn)

Sets whether the pool of statements should be cleared when the connection is returned to its pool. Default is false.

Parameters:

clearStatementPoolOnReturn - clear or not

Since:

2.8.0

setStatementPool

public void setStatementPool(KeyedObjectPool<PStmtKey,DelegatingPreparedStatement> pool)

Sets the prepared statement pool.

Parameters:

pool - the prepared statement pool.

toString

public String toString()

Description copied from class: DelegatingConnection

Returns a string representation of the metadata associated with the innermost delegate connection.

Overrides:

toString in class DelegatingConnection<Connection>

validateObject

public boolean validateObject(PStmtKey key,
 PooledObject<DelegatingPreparedStatement> pooledObject)

KeyedPooledObjectFactory method for validating pooled statements. Currently always returns true.

Specified by:

validateObject in interface KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>

Parameters:

key - ignored

pooledObject - ignored

Returns:

true