PoolingConnection (Apache Tomcat 11.0.23 API Documentation)
Description: declaration: package: org.apache.tomcat.dbcp.dbcp2, class: PoolingConnection

# 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(PStmtKey)` and `prepareCall(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 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 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 AbandonedTrace

  `addTrace, clearTrace, close, getLastUsed, getLastUsedInstant, getTrace, removeThisTrace, removeTrace, setLastUsed, setLastUsed, setLastUsed`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Connection

  `beginRequest, endRequest, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid`

  ### Methods inherited from interface 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, PooledObject)`

  - ### 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, PooledObject)`
      - `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, PooledObject)`

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