# 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 `PreparedStatement`s.

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)`
Constructs a new instance.

## 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 `PreparedStatement`s or `CallableStatement`s 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.
`KeyedObjectPool<PStmtKey, DelegatingPreparedStatement>`
`getStatementPool()`
Gets the prepared statement pool.
`PooledObject<DelegatingPreparedStatement>`
`makeObject(PStmtKey key)`
`KeyedPooledObjectFactory` method for creating `PoolablePreparedStatement`s or `PoolableCallableStatement`s.
`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 `PreparedStatement`s or `CallableStatement`s.
`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, getDefaultQueryTimeoutDuration, getDelegate, getDelegateInternal, getHoldability, getInnermostDelegate, getInnermostDelegateInternal, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, handleException, handleExceptionNoThrow, innermostDelegateEquals, isClosed, isClosedInternal, isReadOnly, isValid, isValid, isWrapperFor, nativeSQL, passivate, releaseSavepoint, rollback, rollback, setAutoCommit, setCacheState, setCatalog, setClientInfo, setClientInfo, setClosedInternal, setDefaultQueryTimeout, setDefaultQueryTimeout, setDelegate, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap, unwrap`

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

`addTrace, clearTrace, close, getLastUsed, getLastUsedInstant, getTrace, removeThisTrace, removeTrace, setLastUsed, 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`

### Methods inherited from interface org.apache.tomcat.dbcp.pool2.KeyedPooledObjectFactory

`destroyObject`

## Constructor Details

### PoolingConnection

public PoolingConnection(Connection connection)
Constructs a new instance.

Parameters:
  `connection` - the underlying `Connection`.

## Method Details

### activateObject

public void activateObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> pooledObject) throws SQLException
`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:
  `SQLException`
See Also:
  - `KeyedPooledObjectFactory.destroyObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)`

### close

public void close() throws SQLException
Closes and frees all `PreparedStatement`s or `CallableStatement`s 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` - Ignored here, for subclasses.

### 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 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, 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, 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 SQLException
`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:
  `SQLException`
See Also:
  - `KeyedPooledObjectFactory.validateObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)`
  - `KeyedObjectPool.invalidateObject(K, V)`

### getStatementPool

public KeyedObjectPool<PStmtKey, DelegatingPreparedStatement> getStatementPool()
Gets the prepared statement pool.

Returns:
  statement pool
Since:
  2.8.0

### makeObject

public PooledObject<DelegatingPreparedStatement> makeObject(PStmtKey key) throws SQLException
`KeyedPooledObjectFactory` method for creating `PoolablePreparedStatement`s or `PoolableCallableStatement`s. 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:
  `SQLException`
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 SQLException
`KeyedPooledObjectFactory` method for passivating `PreparedStatement`s or `CallableStatement`s. Invokes `PreparedStatement.clearParameters()`.

Specified by:
  `passivateObject` in interface `KeyedPooledObjectFactory<PStmtKey, DelegatingPreparedStatement>`
Parameters:
  `key` - ignored
  `pooledObject` - a wrapped `PreparedStatement`
Throws:
  `SQLException`
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 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, 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, 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`