Package org.apache.tomcat.dbcp.dbcp2

## Class PoolingConnection

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp2.AbandonedTrace
  - - org.apache.tomcat.dbcp.dbcp2.DelegatingConnection<java.sql.Connection>
    - - org.apache.tomcat.dbcp.dbcp2.PoolingConnection

All Implemented Interfaces:
  `java.lang.AutoCloseable`, `java.sql.Connection`, `java.sql.Wrapper`, `KeyedPooledObjectFactory<PStmtKey,​DelegatingPreparedStatement>`, `TrackedUse`

    public class PoolingConnection
    extends DelegatingConnection<java.sql.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
`static class` `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
`PoolingConnection​(java.sql.Connection connection)` Constructor.

### Method Summary

All Methods Instance Methods Concrete Methods
`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​(java.lang.String sql)` Creates a PStmtKey for the given arguments.
`protected PStmtKey` `createKey​(java.lang.String sql, int autoGeneratedKeys)` Creates a PStmtKey for the given arguments.
`protected PStmtKey` `createKey​(java.lang.String sql, int[] columnIndexes)` Creates a PStmtKey for the given arguments.
`protected PStmtKey` `createKey​(java.lang.String sql, int resultSetType, int resultSetConcurrency)` Creates a PStmtKey for the given arguments.
`protected PStmtKey` `createKey​(java.lang.String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` Creates a PStmtKey for the given arguments.
`protected PStmtKey` `createKey​(java.lang.String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability, PoolingConnection.StatementType statementType)` Creates a PStmtKey for the given arguments.
`protected PStmtKey` `createKey​(java.lang.String sql, int resultSetType, int resultSetConcurrency, PoolingConnection.StatementType statementType)` Creates a PStmtKey for the given arguments.
`protected PStmtKey` `createKey​(java.lang.String sql, java.lang.String[] columnNames)` Creates a PStmtKey for the given arguments.
`protected PStmtKey` `createKey​(java.lang.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 `PoolablePreparedStatement`s or `PoolableCallableStatement`s.
`protected java.lang.String` `normalizeSQL​(java.lang.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.
`java.sql.CallableStatement` `prepareCall​(java.lang.String sql)` Creates or obtains a `CallableStatement` from the pool.
`java.sql.CallableStatement` `prepareCall​(java.lang.String sql, int resultSetType, int resultSetConcurrency)` Creates or obtains a `CallableStatement` from the pool.
`java.sql.CallableStatement` `prepareCall​(java.lang.String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` Creates or obtains a `CallableStatement` from the pool.
`java.sql.PreparedStatement` `prepareStatement​(java.lang.String sql)` Creates or obtains a `PreparedStatement` from the pool.
`java.sql.PreparedStatement` `prepareStatement​(java.lang.String sql, int autoGeneratedKeys)`
`java.sql.PreparedStatement` `prepareStatement​(java.lang.String sql, int[] columnIndexes)` Creates or obtains a `PreparedStatement` from the pool.
`java.sql.PreparedStatement` `prepareStatement​(java.lang.String sql, int resultSetType, int resultSetConcurrency)` Creates or obtains a `PreparedStatement` from the pool.
`java.sql.PreparedStatement` `prepareStatement​(java.lang.String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` Creates or obtains a `PreparedStatement` from the pool.
`java.sql.PreparedStatement` `prepareStatement​(java.lang.String sql, java.lang.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.
`java.lang.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 Detail

#### PoolingConnection

    public PoolingConnection​(java.sql.Connection connection)

Constructor.

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

### Method Detail

#### activateObject

    public void activateObject​(PStmtKey key,
                               PooledObject<DelegatingPreparedStatement> pooledObject)
                        throws java.lang.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:
  `java.lang.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 java.sql.SQLException

Closes and frees all `PreparedStatement`s or `CallableStatement`s from the pool, and close the underlying connection.

Specified by:
  `close` in interface `java.lang.AutoCloseable`
Specified by:
  `close` in interface `java.sql.Connection`
Overrides:
  `close` in class `DelegatingConnection<java.sql.Connection>`
Throws:
  `java.sql.SQLException`

#### connectionReturnedToPool

    public void connectionReturnedToPool()
                                  throws java.sql.SQLException

Notification from `PoolableConnection` that we returned to the pool.

Throws:
  `java.sql.SQLException` - when `clearStatementPoolOnReturn` is true and the statement pool could not be cleared
Since:
  2.8.0

#### createKey

    protected PStmtKey createKey​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String sql,
                                 java.lang.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 java.lang.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:
  `java.lang.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 java.lang.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:
  `java.lang.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 java.lang.Exception

`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:
  `java.lang.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 java.lang.String normalizeSQL​(java.lang.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 java.lang.Exception

`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:
  `java.lang.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 java.sql.CallableStatement prepareCall​(java.lang.String sql)
                                           throws java.sql.SQLException

Creates or obtains a `CallableStatement` from the pool.

Specified by:
  `prepareCall` in interface `java.sql.Connection`
Overrides:
  `prepareCall` in class `DelegatingConnection<java.sql.Connection>`
Parameters:
  `sql` - the SQL string used to define the CallableStatement
Returns:
  a `PoolableCallableStatement`
Throws:
  `java.sql.SQLException` - Wraps an underlying exception.

#### prepareCall

    public java.sql.CallableStatement prepareCall​(java.lang.String sql,
                                                  int resultSetType,
                                                  int resultSetConcurrency)
                                           throws java.sql.SQLException

Creates or obtains a `CallableStatement` from the pool.

Specified by:
  `prepareCall` in interface `java.sql.Connection`
Overrides:
  `prepareCall` in class `DelegatingConnection<java.sql.Connection>`
Parameters:
  `sql` - the SQL string used to define the CallableStatement
  `resultSetType` - result set type
  `resultSetConcurrency` - result set concurrency
Returns:
  a `PoolableCallableStatement`
Throws:
  `java.sql.SQLException` - Wraps an underlying exception.

#### prepareCall

    public java.sql.CallableStatement prepareCall​(java.lang.String sql,
                                                  int resultSetType,
                                                  int resultSetConcurrency,
                                                  int resultSetHoldability)
                                           throws java.sql.SQLException

Creates or obtains a `CallableStatement` from the pool.

Specified by:
  `prepareCall` in interface `java.sql.Connection`
Overrides:
  `prepareCall` in class `DelegatingConnection<java.sql.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:
  `java.sql.SQLException` - Wraps an underlying exception.

#### prepareStatement

    public java.sql.PreparedStatement prepareStatement​(java.lang.String sql)
                                                throws java.sql.SQLException

Creates or obtains a `PreparedStatement` from the pool.

Specified by:
  `prepareStatement` in interface `java.sql.Connection`
Overrides:
  `prepareStatement` in class `DelegatingConnection<java.sql.Connection>`
Parameters:
  `sql` - the SQL string used to define the PreparedStatement
Returns:
  a `PoolablePreparedStatement`
Throws:
  `java.sql.SQLException` - Wraps an underlying exception.

#### prepareStatement

    public java.sql.PreparedStatement prepareStatement​(java.lang.String sql,
                                                       int autoGeneratedKeys)
                                                throws java.sql.SQLException

Specified by:
  `prepareStatement` in interface `java.sql.Connection`
Overrides:
  `prepareStatement` in class `DelegatingConnection<java.sql.Connection>`
Throws:
  `java.sql.SQLException`

#### prepareStatement

    public java.sql.PreparedStatement prepareStatement​(java.lang.String sql,
                                                       int[] columnIndexes)
                                                throws java.sql.SQLException

Creates or obtains a `PreparedStatement` from the pool.

Specified by:
  `prepareStatement` in interface `java.sql.Connection`
Overrides:
  `prepareStatement` in class `DelegatingConnection<java.sql.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:
  `java.sql.SQLException` - Wraps an underlying exception.

#### prepareStatement

    public java.sql.PreparedStatement prepareStatement​(java.lang.String sql,
                                                       int resultSetType,
                                                       int resultSetConcurrency)
                                                throws java.sql.SQLException

Creates or obtains a `PreparedStatement` from the pool.

Specified by:
  `prepareStatement` in interface `java.sql.Connection`
Overrides:
  `prepareStatement` in class `DelegatingConnection<java.sql.Connection>`
Parameters:
  `sql` - the SQL string used to define the PreparedStatement
  `resultSetType` - result set type
  `resultSetConcurrency` - result set concurrency
Returns:
  a `PoolablePreparedStatement`
Throws:
  `java.sql.SQLException` - Wraps an underlying exception.

#### prepareStatement

    public java.sql.PreparedStatement prepareStatement​(java.lang.String sql,
                                                       int resultSetType,
                                                       int resultSetConcurrency,
                                                       int resultSetHoldability)
                                                throws java.sql.SQLException

Creates or obtains a `PreparedStatement` from the pool.

Specified by:
  `prepareStatement` in interface `java.sql.Connection`
Overrides:
  `prepareStatement` in class `DelegatingConnection<java.sql.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:
  `java.sql.SQLException` - Wraps an underlying exception.

#### prepareStatement

    public java.sql.PreparedStatement prepareStatement​(java.lang.String sql,
                                                       java.lang.String[] columnNames)
                                                throws java.sql.SQLException

Creates or obtains a `PreparedStatement` from the pool.

Specified by:
  `prepareStatement` in interface `java.sql.Connection`
Overrides:
  `prepareStatement` in class `DelegatingConnection<java.sql.Connection>`
Parameters:
  `sql` - the SQL string used to define the PreparedStatement
  `columnNames` - column names
Returns:
  a `PoolablePreparedStatement`
Throws:
  `java.sql.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 java.lang.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<java.sql.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`