PoolingConnection (Apache Tomcat 10.1.14 API Documentation)

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 `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 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
    Constructor | Description
    --- | ---
    `PoolingConnection​(Connection connection)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### PoolingConnection

          public PoolingConnection​(Connection connection)

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

  - ### Method Detail

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