org.apache.tomcat.dbcp.dbcp

## Class PoolingConnection

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp.AbandonedTrace
  - - org.apache.tomcat.dbcp.dbcp.DelegatingConnection
    - - org.apache.tomcat.dbcp.dbcp.PoolingConnection

- All Implemented Interfaces:
    java.lang.AutoCloseable, java.sql.Connection, java.sql.Wrapper, KeyedPoolableObjectFactory<PStmtKey,DelegatingPreparedStatement>

      public class PoolingConnection
      extends DelegatingConnection
      implements KeyedPoolableObjectFactory<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`.)

  Author:
    Rodney Waldhoff, Dirk Verbeeck
  See Also:
    `PoolablePreparedStatement`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PoolingConnection.StatementType`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected KeyedObjectPool<PStmtKey,DelegatingPreparedStatement>` | `_pstmtPool` Pool of `PreparedStatement`s. and `CallableStatement`s

    - ### Fields inherited from class org.apache.tomcat.dbcp.dbcp.DelegatingConnection

      `_closed, _conn`

    - ### 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(java.sql.Connection c)` Constructor.
    `PoolingConnection(java.sql.Connection c, KeyedObjectPool<PStmtKey,DelegatingPreparedStatement> pool)` Constructor.

  - ### Method Summary

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

    - ### Methods inherited from class org.apache.tomcat.dbcp.dbcp.DelegatingConnection

      `abort, activate, checkOpen, clearWarnings, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, equals, getAutoCommit, getCatalog, getClientInfo, getClientInfo, getDelegate, getDelegateInternal, getHoldability, getInnermostDelegate, getInnermostDelegateInternal, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, handleException, hashCode, innermostDelegateEquals, isClosed, isReadOnly, isValid, isWrapperFor, nativeSQL, passivate, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setClientInfo, setClientInfo, setDelegate, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap, unwrap`

    - ### Methods inherited from class org.apache.tomcat.dbcp.dbcp.AbandonedTrace

      `addTrace, clearTrace, getConfig, getLastUsed, getTrace, printStackTrace, removeTrace, setLastUsed, setLastUsed, setStackTrace`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### _pstmtPool

          protected KeyedObjectPool<PStmtKey,DelegatingPreparedStatement> _pstmtPool

      Pool of `PreparedStatement`s. and `CallableStatement`s

  - ### Constructor Detail

    - #### PoolingConnection

          public PoolingConnection(java.sql.Connection c)

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

    - #### PoolingConnection

          public PoolingConnection(java.sql.Connection c,
                           KeyedObjectPool<PStmtKey,DelegatingPreparedStatement> pool)

      Constructor.
      Parameters:
        `c` - the underlying `Connection`.
        `pool` - `KeyedObjectPool` of `PreparedStatement`s and `CallableStatement`s.

  - ### Method Detail

    - #### close

          public void close()
                     throws java.sql.SQLException

      Close and free all `PreparedStatement`s or `CallableStatement` from the pool, and close the underlying connection.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.sql.Connection`
      Overrides:
        `close` in class `DelegatingConnection`
      Throws:
        `java.sql.SQLException`

    - #### prepareStatement

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

      Create or obtain a `PreparedStatement` from the pool.
      Specified by:
        `prepareStatement` in interface `java.sql.Connection`
      Overrides:
        `prepareStatement` in class `DelegatingConnection`
      Parameters:
        `sql` - the sql string used to define the PreparedStatement
      Returns:
        a `PoolablePreparedStatement`
      Throws:
        `java.sql.SQLException`

    - #### prepareStatement

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

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

    - #### prepareStatement

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

      Create or obtain a `PreparedStatement` from the pool.
      Specified by:
        `prepareStatement` in interface `java.sql.Connection`
      Overrides:
        `prepareStatement` in class `DelegatingConnection`
      Parameters:
        `sql` - the sql string used to define the PreparedStatement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
      Returns:
        a `PoolablePreparedStatement`
      Throws:
        `java.sql.SQLException`

    - #### prepareCall

          public java.sql.CallableStatement prepareCall(java.lang.String sql)
                                                 throws java.sql.SQLException

      Create or obtain a `CallableStatement` from the pool.
      Specified by:
        `prepareCall` in interface `java.sql.Connection`
      Overrides:
        `prepareCall` in class `DelegatingConnection`
      Parameters:
        `sql` - the sql string used to define the CallableStatement
      Returns:
        a `PoolableCallableStatement`
      Throws:
        `java.sql.SQLException`
      Since:
        1.3

    - #### prepareCall

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

      Create or obtain a `CallableStatement` from the pool.
      Specified by:
        `prepareCall` in interface `java.sql.Connection`
      Overrides:
        `prepareCall` in class `DelegatingConnection`
      Parameters:
        `sql` - the sql string used to define the CallableStatement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
      Returns:
        a `PoolableCallableStatement`
      Throws:
        `java.sql.SQLException`
      Since:
        1.3

    - #### prepareStatement

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

      Create or obtain a `PreparedStatement` from the pool.
      Specified by:
        `prepareStatement` in interface `java.sql.Connection`
      Overrides:
        `prepareStatement` in class `DelegatingConnection`
      Parameters:
        `sql` - the sql string used to define the PreparedStatement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
        `resultSetHoldability` - result set holdability
      Returns:
        a `PoolablePreparedStatement`
      Throws:
        `java.sql.SQLException`

    - #### prepareStatement

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

      Create or obtain a `PreparedStatement` from the pool.
      Specified by:
        `prepareStatement` in interface `java.sql.Connection`
      Overrides:
        `prepareStatement` in class `DelegatingConnection`
      Parameters:
        `sql` - the sql string used to define the PreparedStatement
        `columnIndexes` - column indexes
      Returns:
        a `PoolablePreparedStatement`
      Throws:
        `java.sql.SQLException`

    - #### prepareStatement

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

      Create or obtain a `PreparedStatement` from the pool.
      Specified by:
        `prepareStatement` in interface `java.sql.Connection`
      Overrides:
        `prepareStatement` in class `DelegatingConnection`
      Parameters:
        `sql` - the sql string used to define the PreparedStatement
        `columnNames` - column names
      Returns:
        a `PoolablePreparedStatement`
      Throws:
        `java.sql.SQLException`

    - #### prepareCall

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

      Create or obtain a `CallableStatement` from the pool.
      Specified by:
        `prepareCall` in interface `java.sql.Connection`
      Overrides:
        `prepareCall` in class `DelegatingConnection`
      Parameters:
        `sql` - the sql string used to define the CallableStatement
        `resultSetType` - result set type
        `resultSetConcurrency` - result set concurrency
        `resultSetHoldability` - result set holdability
      Returns:
        a `PoolableCallableStatement`
      Throws:
        `java.sql.SQLException`

    - #### createKey

          protected PStmtKey createKey(java.lang.String sql)

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

    - #### createKey

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

    - #### createKey

          protected PStmtKey createKey(java.lang.String sql,
                           int autoGeneratedKeys)

    - #### createKey

          protected PStmtKey createKey(java.lang.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(java.lang.String sql,
                           int resultSetType,
                           int resultSetConcurrency,
                           int resultSetHoldability)

    - #### createKey

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

    - #### createKey

          protected PStmtKey createKey(java.lang.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(java.lang.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(java.lang.String sql,
                           java.lang.String[] columnNames)

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

    - #### normalizeSQL

          protected java.lang.String normalizeSQL(java.lang.String sql)

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

    - #### makeObject

          public DelegatingPreparedStatement makeObject(PStmtKey key)
                                                 throws java.lang.Exception

      `KeyedPoolableObjectFactory` 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 `KeyedPoolableObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - the key for the `PreparedStatement` to be created
      Returns:
        an instance that can be served by the pool.
      Throws:
        `java.lang.Exception` - if there is a problem creating a new instance, this will be propagated to the code requesting an object.
      See Also:
        `createKey(String, int, int, StatementType)`

    - #### destroyObject

          public void destroyObject(PStmtKey key,
                           DelegatingPreparedStatement obj)
                             throws java.lang.Exception

      `KeyedPoolableObjectFactory` method for destroying PoolablePreparedStatements and PoolableCallableStatements. Closes the underlying statement.
      Specified by:
        `destroyObject` in interface `KeyedPoolableObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - ignored
        `obj` - the pooled statement to be destroyed.
      Throws:
        `java.lang.Exception` - should be avoided as it may be swallowed by the pool implementation.
      See Also:
        `KeyedPoolableObjectFactory.validateObject(K, V)`, `KeyedObjectPool.invalidateObject(K, V)`

    - #### validateObject

          public boolean validateObject(PStmtKey key,
                               DelegatingPreparedStatement obj)

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

    - #### activateObject

          public void activateObject(PStmtKey key,
                            DelegatingPreparedStatement obj)
                              throws java.lang.Exception

      `KeyedPoolableObjectFactory` method for activating pooled statements.
      Specified by:
        `activateObject` in interface `KeyedPoolableObjectFactory<PStmtKey,DelegatingPreparedStatement>`
      Parameters:
        `key` - ignored
        `obj` - pooled statement to be activated
      Throws:
        `java.lang.Exception` - if there is a problem activating `obj`, this exception may be swallowed by the pool.
      See Also:
        `KeyedPoolableObjectFactory.destroyObject(K, V)`

    - #### passivateObject

          public void passivateObject(PStmtKey key,
                             DelegatingPreparedStatement obj)
                               throws java.lang.Exception

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

    - #### toString

          public java.lang.String toString()

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

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