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

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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, PoolingConnection.StatementType statementType)` Creates a PStmtKey for the given arguments.
    `protected PStmtKey` | `createKey(String sql, String[] columnNames)` 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 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, 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`

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

      `KeyedPooledObjectFactory` method for activating pooled statements.
      Specified by:
        `activateObject` in interface `KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - ignored
        `pooledObject` - wrapped pooled statement to be activated
      Throws:
        `Exception` - if there is a problem activating `obj`, this exception may be swallowed by the pool.
      See Also:
        `KeyedPooledObjectFactory.destroyObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)`

    - #### close

          public void close()
                     throws SQLException

      Closes and frees all `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`

    - #### connectionReturnedToPool

          public void connectionReturnedToPool()
                                        throws SQLException

      Notification from `PoolableConnection` that we returned to the pool.
      Throws:
        `SQLException` - when `clearStatementPoolOnReturn` is true and the statement pool could not be cleared
      Since:
        2.8.0

    - #### createKey

          protected PStmtKey createKey(String sql)

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
      Returns:
        the PStmtKey created for the given arguments.

    - #### createKey

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

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `columnIndexes` - An array of column indexes indicating the columns that should be returned from the inserted row or rows.
      Returns:
        the PStmtKey created for the given arguments.

    - #### createKey

          protected PStmtKey createKey(String sql,
                           int autoGeneratedKeys)

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `autoGeneratedKeys` - A flag indicating whether auto-generated keys should be returned; one of `Statement.RETURN_GENERATED_KEYS` or `Statement.NO_GENERATED_KEYS`.
      Returns:
        the PStmtKey created for the given arguments.

    - #### createKey

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

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
      Returns:
        the PStmtKey created for the given arguments.

    - #### createKey

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

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
        `resultSetHoldability` - result set holdability
      Returns:
        the PStmtKey created for the given arguments.

    - #### createKey

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

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
        `resultSetHoldability` - result set holdability
        `statementType` - statement type
      Returns:
        the PStmtKey created for the given arguments.

    - #### createKey

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

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
        `statementType` - statement type
      Returns:
        the PStmtKey created for the given arguments.

    - #### createKey

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

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `statementType` - statement type
      Returns:
        the PStmtKey created for the given arguments.

    - #### createKey

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

      Creates a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `columnNames` - column names
      Returns:
        the PStmtKey created for the given arguments.

    - #### destroyObject

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

      `KeyedPooledObjectFactory` method for destroying PoolablePreparedStatements and PoolableCallableStatements. Closes the underlying statement.
      Specified by:
        `destroyObject` in interface `KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - ignored
        `pooledObject` - the wrapped pooled statement to be destroyed.
      Throws:
        `Exception` - should be avoided as it may be swallowed by the pool implementation.
      See Also:
        `KeyedPooledObjectFactory.validateObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)`, `KeyedObjectPool.invalidateObject(K, V)`

    - #### destroyObject

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

      Description copied from interface: `KeyedPooledObjectFactory`
      Destroy an instance no longer needed by the pool, using the provided `DestroyMode`.
      Specified by:
        `destroyObject` in interface `KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - the key used when selecting the instance
        `p` - a `PooledObject` wrapping the instance to be destroyed
        `mode` - DestroyMode providing context to the factory
      Throws:
        `Exception` - should be avoided as it may be swallowed by the pool implementation.
      See Also:
        `KeyedPooledObjectFactory.validateObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)`, `KeyedObjectPool.invalidateObject(K, V)`, `KeyedPooledObjectFactory.destroyObject(Object, PooledObject)`, `DestroyMode`

    - #### getStatementPool

          public KeyedObjectPool<PStmtKey,DelegatingPreparedStatement> getStatementPool()

      Returns the prepared statement pool we're using.
      Returns:
        statement pool
      Since:
        2.8.0

    - #### makeObject

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

      `KeyedPooledObjectFactory` method for creating `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:
        `Exception` - if there is a problem creating a new instance, this will be propagated to the code requesting an object.
      See Also:
        `createKey(String, int, int, StatementType)`

    - #### normalizeSQL

          protected String normalizeSQL(String sql)

      Normalizes the given SQL statement, producing a canonical form that is semantically equivalent to the original.
      Parameters:
        `sql` - The statement to be normalized.
      Returns:
        The canonical form of the supplied SQL statement.

    - #### passivateObject

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

      `KeyedPooledObjectFactory` method for passivating `PreparedStatement`s or `CallableStatement`s. Invokes `PreparedStatement.clearParameters()`.
      Specified by:
        `passivateObject` in interface `KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - ignored
        `pooledObject` - a wrapped `PreparedStatement`
      Throws:
        `Exception` - if there is a problem passivating `obj`, this exception may be swallowed by the pool.
      See Also:
        `KeyedPooledObjectFactory.destroyObject(K, org.apache.tomcat.dbcp.pool2.PooledObject<V>)`

    - #### prepareCall

          public CallableStatement prepareCall(String sql)
                                        throws SQLException

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

    - #### prepareCall

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

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

    - #### prepareCall

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

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

    - #### prepareStatement

          public PreparedStatement prepareStatement(String sql)
                                             throws SQLException

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

    - #### prepareStatement

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

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

    - #### prepareStatement

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

      Creates or obtains a `PreparedStatement` from the pool.
      Specified by:
        `prepareStatement` in interface `Connection`
      Overrides:
        `prepareStatement` in class `DelegatingConnection<Connection>`
      Parameters:
        `sql` - the SQL string used to define the PreparedStatement
        `columnIndexes` - An array of column indexes indicating the columns that should be returned from the inserted row or rows.
      Returns:
        a `PoolablePreparedStatement`
      Throws:
        `SQLException` - Wraps an underlying exception.

    - #### prepareStatement

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

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

    - #### prepareStatement

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

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

    - #### prepareStatement

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

      Creates or obtains a `PreparedStatement` from the pool.
      Specified by:
        `prepareStatement` in interface `Connection`
      Overrides:
        `prepareStatement` in class `DelegatingConnection<Connection>`
      Parameters:
        `sql` - the SQL string used to define the PreparedStatement
        `columnNames` - column names
      Returns:
        a `PoolablePreparedStatement`
      Throws:
        `SQLException` - Wraps an underlying exception.

    - #### setClearStatementPoolOnReturn

          public void setClearStatementPoolOnReturn(boolean clearStatementPoolOnReturn)

      Sets whether the pool of statements should be cleared when the connection is returned to its pool. Default is false.
      Parameters:
        `clearStatementPoolOnReturn` - clear or not
      Since:
        2.8.0

    - #### setStatementPool

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

      Sets the prepared statement pool.
      Parameters:
        `pool` - the prepared statement pool.

    - #### toString

          public String toString()

      Description copied from class: `DelegatingConnection`
      Returns a string representation of the metadata associated with the innermost delegate connection.
      Overrides:
        `toString` in class `DelegatingConnection<Connection>`

    - #### validateObject

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

      `KeyedPooledObjectFactory` method for validating pooled statements. Currently always returns true.
      Specified by:
        `validateObject` in interface `KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - ignored
        `pooledObject` - ignored
      Returns:
        `true`

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.