org.apache.commons.dbcp2

## Class PoolingConnection

- java.lang.Object
- - org.apache.commons.dbcp2.AbandonedTrace
  - - org.apache.commons.dbcp2.DelegatingConnection<Connection>
    - - org.apache.commons.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(java.lang.String)` and `prepareCall(java.lang.String)` 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
  Author:
    Rodney Waldhoff, Dirk Verbeeck
  See Also:
    `PoolablePreparedStatement`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `PoolingConnection.StatementType` The possible 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 c)` Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `activateObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> p)` `KeyedPooledObjectFactory` method for activating pooled statements.
    `void` | `close()` Close and free all `PreparedStatement`s or `CallableStatement`s from the pool, and close the underlying connection.
    `protected PStmtKey` | `createKey(String sql)` Create a PStmtKey for the given arguments.
    `protected PStmtKey` | `createKey(String sql, int autoGeneratedKeys)`
    `protected PStmtKey` | `createKey(String sql, int[] columnIndexes)` Create a PStmtKey for the given arguments.
    `protected PStmtKey` | `createKey(String sql, int resultSetType, int resultSetConcurrency)` Create a PStmtKey for the given arguments.
    `protected PStmtKey` | `createKey(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` Create a PStmtKey for the given arguments.
    `protected PStmtKey` | `createKey(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability, PoolingConnection.StatementType stmtType)` Create a PStmtKey for the given arguments.
    `protected PStmtKey` | `createKey(String sql, int resultSetType, int resultSetConcurrency, PoolingConnection.StatementType stmtType)` Create a PStmtKey for the given arguments.
    `protected PStmtKey` | `createKey(String sql, PoolingConnection.StatementType stmtType)` Create a PStmtKey for the given arguments.
    `protected PStmtKey` | `createKey(String sql, String[] columnNames)` Create a PStmtKey for the given arguments.
    `void` | `destroyObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> p)` `KeyedPooledObjectFactory` method for destroying PoolablePreparedStatements and PoolableCallableStatements.
    `PooledObject<DelegatingPreparedStatement>` | `makeObject(PStmtKey key)` `KeyedPooledObjectFactory` method for creating `PoolablePreparedStatement`s or `PoolableCallableStatement`s.
    `protected String` | `normalizeSQL(String sql)` Normalize the given SQL statement, producing a canonical form that is semantically equivalent to the original.
    `void` | `passivateObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> p)` `KeyedPooledObjectFactory` method for passivating `PreparedStatement`s or `CallableStatement`s.
    `CallableStatement` | `prepareCall(String sql)` Create or obtain a `CallableStatement` from the pool.
    `CallableStatement` | `prepareCall(String sql, int resultSetType, int resultSetConcurrency)` Create or obtain a `CallableStatement` from the pool.
    `CallableStatement` | `prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` Create or obtain a `CallableStatement` from the pool.
    `PreparedStatement` | `prepareStatement(String sql)` Create or obtain a `PreparedStatement` from the pool.
    `PreparedStatement` | `prepareStatement(String sql, int autoGeneratedKeys)`
    `PreparedStatement` | `prepareStatement(String sql, int[] columnIndexes)` Create or obtain a `PreparedStatement` from the pool.
    `PreparedStatement` | `prepareStatement(String sql, int resultSetType, int resultSetConcurrency)` Create or obtain a `PreparedStatement` from the pool.
    `PreparedStatement` | `prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)` Create or obtain a `PreparedStatement` from the pool.
    `PreparedStatement` | `prepareStatement(String sql, String[] columnNames)` Create or obtain a `PreparedStatement` from the pool.
    `void` | `setStatementPool(KeyedObjectPool<PStmtKey,DelegatingPreparedStatement> pool)`
    `String` | `toString()` Returns a string representation of the metadata associated with the innermost delegate connection.
    `boolean` | `validateObject(PStmtKey key, PooledObject<DelegatingPreparedStatement> p)` `KeyedPooledObjectFactory` method for validating pooled statements.

    - ### Methods inherited from class org.apache.commons.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, 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.commons.dbcp2.AbandonedTrace

      `addTrace, clearTrace, getLastUsed, getTrace, 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 c)

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

  - ### Method Detail

    - #### setStatementPool

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

    - #### close

          public void close()
                     throws SQLException

      Close and free 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`

    - #### prepareStatement

          public PreparedStatement prepareStatement(String sql)
                                             throws SQLException

      Create or obtain 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`

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

      Create or obtain 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`

    - #### prepareCall

          public CallableStatement prepareCall(String sql)
                                        throws SQLException

      Create or obtain 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`

    - #### prepareCall

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

      Create or obtain 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`

    - #### prepareStatement

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

      Create or obtain 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`

    - #### prepareStatement

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

      Create or obtain 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` - column indexes
      Returns:
        a `PoolablePreparedStatement`
      Throws:
        `SQLException`

    - #### prepareStatement

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

      Create or obtain 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`

    - #### prepareCall

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

      Create or obtain 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`

    - #### createKey

          protected PStmtKey createKey(String sql,
                           int autoGeneratedKeys)

    - #### createKey

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

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

    - #### createKey

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

      Create a PStmtKey for the given arguments.
      Parameters:
        `sql` - the sql string used to define the statement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
        `stmtType` - statement type

    - #### createKey

          protected PStmtKey createKey(String sql)

      Create a PStmtKey for the given arguments.
      Parameters:
        `sql` - the sql string used to define the statement

    - #### createKey

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

      Create a PStmtKey for the given arguments.
      Parameters:
        `sql` - the SQL string used to define the statement
        `stmtType` - statement type

    - #### createKey

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

      Create 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

    - #### createKey

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

      Create 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
        `stmtType` - statement type

    - #### createKey

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

      Create a PStmtKey for the given arguments.
      Parameters:
        `sql` - the sql string used to define the statement
        `columnIndexes` - column indexes

    - #### createKey

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

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

    - #### normalizeSQL

          protected String normalizeSQL(String sql)

      Normalize the given SQL statement, producing a canonical form that is semantically equivalent to the original.

    - #### 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
      Throws:
        `Exception`
      See Also:
        `createKey(String, int, int, StatementType)`

    - #### destroyObject

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

      `KeyedPooledObjectFactory` method for destroying PoolablePreparedStatements and PoolableCallableStatements. Closes the underlying statement.
      Specified by:
        `destroyObject` in interface `KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - ignored
        `p` - the wrapped pooled statement to be destroyed.
      Throws:
        `Exception`

    - #### validateObject

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

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

    - #### activateObject

          public void activateObject(PStmtKey key,
                            PooledObject<DelegatingPreparedStatement> p)
                              throws Exception

      `KeyedPooledObjectFactory` method for activating pooled statements.
      Specified by:
        `activateObject` in interface `KeyedPooledObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - ignored
        `p` - wrapped pooled statement to be activated
      Throws:
        `Exception`

    - #### passivateObject

          public void passivateObject(PStmtKey key,
                             PooledObject<DelegatingPreparedStatement> p)
                               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
        `p` - a wrapped `PreparedStatement`
      Throws:
        `Exception`

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

Copyright © 2001–2017 The Apache Software Foundation. All rights reserved.