Package org.apache.commons.dbcp2

# Class DelegatingConnection<C extends Connection>

java.lang.Object
org.apache.commons.dbcp2.AbandonedTrace
org.apache.commons.dbcp2.DelegatingConnection<C>

Type Parameters:
  `C` - the Connection type

All Implemented Interfaces:
  `AutoCloseable`, `Connection`, `Wrapper`, `TrackedUse`

Direct Known Subclasses:
  `ManagedConnection`, `PoolableConnection`, `PoolingConnection`

public class DelegatingConnection<C extends Connection> extends AbandonedTrace implements Connection
A base delegating implementation of `Connection`.

All of the methods from the `Connection` interface simply check to see that the `Connection` is active, and call the corresponding method on the "delegate" provided in my constructor.

Extends AbandonedTrace to implement Connection tracking and logging of code which created the Connection. Tracking the Connection ensures that the AbandonedObjectPool can close this connection and recycle it if its pool of connections is nearing exhaustion and this connection's last usage is older than the removeAbandonedTimeout.

Since:
  2.0

- ## 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
  `DelegatingConnection(C connection)`
  Creates a wrapper for the Connection which traces this Connection in the AbandonedObjectPool.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `abort(Executor executor)`
  `protected void`
  `activate()`
  Marks this instance as used and delegates to a wrapped `activate()`.
  `protected void`
  `checkOpen()`
  Throws a SQLException if this connection is not open.
  `void`
  `clearCachedState()`
  Clears the cached state.
  `void`
  `clearWarnings()`
  `void`
  `close()`
  Closes the underlying connection, and close any Statements that were not explicitly closed.
  `protected final void`
  `closeInternal()`
  Closes the underlying connection for `close()`.
  `void`
  `commit()`
  `Array`
  `createArrayOf(String typeName, Object[] elements)`
  `Blob`
  `createBlob()`
  `Clob`
  `createClob()`
  `NClob`
  `createNClob()`
  `SQLXML`
  `createSQLXML()`
  `Statement`
  `createStatement()`
  `Statement`
  `createStatement(int resultSetType, int resultSetConcurrency)`
  `Statement`
  `createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)`
  `Struct`
  `createStruct(String typeName, Object[] attributes)`
  `boolean`
  `getAutoCommit()`
  `boolean`
  `getCacheState()`
  Gets whether to cache properties.
  `String`
  `getCatalog()`
  `Properties`
  `getClientInfo()`
  `String`
  `getClientInfo(String name)`
  `Integer`
  `getDefaultQueryTimeout()`
  Deprecated.
  Use `getDefaultQueryTimeoutDuration()`.
  `Duration`
  `getDefaultQueryTimeoutDuration()`
  Gets the default query timeout that will be used for `Statement`s created from this connection.
  `C`
  `getDelegate()`
  Returns my underlying `Connection`.
  `protected final C`
  `getDelegateInternal()`
  Gets the delegate connection.
  `int`
  `getHoldability()`
  `Connection`
  `getInnermostDelegate()`
  If my underlying `Connection` is not a `DelegatingConnection`, returns it, otherwise recursively invokes this method on my delegate.
  `final Connection`
  `getInnermostDelegateInternal()`
  Although this method is public, it is part of the internal API and should not be used by clients.
  `DatabaseMetaData`
  `getMetaData()`
  `int`
  `getNetworkTimeout()`
  `String`
  `getSchema()`
  `int`
  `getTransactionIsolation()`
  `Map<String,Class<?>>`
  `getTypeMap()`
  `SQLWarning`
  `getWarnings()`
  `protected void`
  `handleException(SQLException e)`
  Handles the given exception by throwing it.
  `protected <T extends Throwable>
  T`
  `handleExceptionNoThrow(T e)`
  Handles the given `SQLException`.
  `boolean`
  `innermostDelegateEquals(Connection c)`
  Compares innermost delegate to the given connection.
  `boolean`
  `isClosed()`
  `protected boolean`
  `isClosedInternal()`
  Tests the raw internal closed state.
  `boolean`
  `isReadOnly()`
  `boolean`
  `isValid(int timeoutSeconds)`
  Deprecated.
  Use `isValid(Duration)`.
  `boolean`
  `isValid(Duration timeout)`
  Tests if the connection has not been closed and is still valid.
  `boolean`
  `isWrapperFor(Class<?> iface)`
  `String`
  `nativeSQL(String sql)`
  `protected void`
  `passivate()`
  Clears the list of objects being traced by this object.
  `CallableStatement`
  `prepareCall(String sql)`
  `CallableStatement`
  `prepareCall(String sql, int resultSetType, int resultSetConcurrency)`
  `CallableStatement`
  `prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)`
  `PreparedStatement`
  `prepareStatement(String sql)`
  `PreparedStatement`
  `prepareStatement(String sql, int autoGeneratedKeys)`
  `PreparedStatement`
  `prepareStatement(String sql, int[] columnIndexes)`
  `PreparedStatement`
  `prepareStatement(String sql, int resultSetType, int resultSetConcurrency)`
  `PreparedStatement`
  `prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)`
  `PreparedStatement`
  `prepareStatement(String sql, String[] columnNames)`
  `void`
  `releaseSavepoint(Savepoint savepoint)`
  `void`
  `rollback()`
  `void`
  `rollback(Savepoint savepoint)`
  `void`
  `setAutoCommit(boolean autoCommit)`
  `void`
  `setCacheState(boolean cacheState)`
  Sets whether to cache properties.
  `void`
  `setCatalog(String catalog)`
  `void`
  `setClientInfo(String name, String value)`
  `void`
  `setClientInfo(Properties properties)`
  `protected void`
  `setClosedInternal(boolean closed)`
  Sets the raw internal closed state.
  `void`
  `setDefaultQueryTimeout(Integer defaultQueryTimeoutSeconds)`
  Deprecated.
  Use `setDefaultQueryTimeout(Duration)`.
  `void`
  `setDefaultQueryTimeout(Duration defaultQueryTimeoutDuration)`
  Sets the default query timeout that will be used for `Statement`s created from this connection.
  `void`
  `setDelegate(C connection)`
  Sets my delegate.
  `void`
  `setHoldability(int holdability)`
  `void`
  `setNetworkTimeout(Executor executor, int milliseconds)`
  `void`
  `setReadOnly(boolean readOnly)`
  `Savepoint`
  `setSavepoint()`
  `Savepoint`
  `setSavepoint(String name)`
  `void`
  `setSchema(String schema)`
  `void`
  `setTransactionIsolation(int level)`
  `void`
  `setTypeMap(Map<String,Class<?>> map)`
  `String`
  `toString()`
  Returns a string representation of the metadata associated with the innermost delegate connection.
  `<T> T`
  `unwrap(Class<T> iface)`

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

- ## Constructor Details

  - ### DelegatingConnection

    public DelegatingConnection(C connection)
    Creates a wrapper for the Connection which traces this Connection in the AbandonedObjectPool.
    Parameters:
      `connection` - the `Connection` to delegate all calls to, may be null (see `ManagedConnection`).

- ## Method Details

  - ### abort

    public void abort(Executor executor) throws SQLException
    Specified by:
      `abort` in interface `Connection`
    Throws:
      `SQLException`

  - ### activate

    protected void activate()
    Marks this instance as used and delegates to a wrapped `activate()`.

  - ### checkOpen

    protected void checkOpen() throws SQLException
    Throws a SQLException if this connection is not open.
    Throws:
      `SQLException` - Thrown if this connection is not open.

  - ### clearCachedState

    public void clearCachedState()
    Clears the cached state. Call when you know that the underlying connection may have been accessed directly.

  - ### clearWarnings

    public void clearWarnings() throws SQLException
    Specified by:
      `clearWarnings` in interface `Connection`
    Throws:
      `SQLException`

  - ### close

    public void close() throws SQLException
    Closes the underlying connection, and close any Statements that were not explicitly closed. Sub-classes that override this method must:
    1. Call `passivate()`
    2. Call close (or the equivalent appropriate action) on the wrapped connection
    3. Set `closed` to `false`
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Connection`
    Overrides:
      `close` in class `AbandonedTrace`
    Throws:
      `SQLException` - Ignored here, for subclasses.

  - ### closeInternal

    protected final void closeInternal() throws SQLException
    Closes the underlying connection for `close()`.
    Throws:
      `SQLException` - SQLException if a database access error occurs.

  - ### commit

    public void commit() throws SQLException
    Specified by:
      `commit` in interface `Connection`
    Throws:
      `SQLException`

  - ### createArrayOf

    public Array createArrayOf(String typeName, Object[] elements) throws SQLException
    Specified by:
      `createArrayOf` in interface `Connection`
    Throws:
      `SQLException`

  - ### createBlob

    public Blob createBlob() throws SQLException
    Specified by:
      `createBlob` in interface `Connection`
    Throws:
      `SQLException`

  - ### createClob

    public Clob createClob() throws SQLException
    Specified by:
      `createClob` in interface `Connection`
    Throws:
      `SQLException`

  - ### createNClob

    public NClob createNClob() throws SQLException
    Specified by:
      `createNClob` in interface `Connection`
    Throws:
      `SQLException`

  - ### createSQLXML

    public SQLXML createSQLXML() throws SQLException
    Specified by:
      `createSQLXML` in interface `Connection`
    Throws:
      `SQLException`

  - ### createStatement

    public Statement createStatement() throws SQLException
    Specified by:
      `createStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### createStatement

    public Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException
    Specified by:
      `createStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### createStatement

    public Statement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
    Specified by:
      `createStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### createStruct

    public Struct createStruct(String typeName, Object[] attributes) throws SQLException
    Specified by:
      `createStruct` in interface `Connection`
    Throws:
      `SQLException`

  - ### getAutoCommit

    public boolean getAutoCommit() throws SQLException
    Specified by:
      `getAutoCommit` in interface `Connection`
    Throws:
      `SQLException`

  - ### getCacheState

    public boolean getCacheState()
    Gets whether to cache properties. The cached properties are:
    - auto-commit
    - catalog
    - schema
    - read-only
    Returns:
      the state caching flag

  - ### getCatalog

    public String getCatalog() throws SQLException
    Specified by:
      `getCatalog` in interface `Connection`
    Throws:
      `SQLException`

  - ### getClientInfo

    public Properties getClientInfo() throws SQLException
    Specified by:
      `getClientInfo` in interface `Connection`
    Throws:
      `SQLException`

  - ### getClientInfo

    public String getClientInfo(String name) throws SQLException
    Specified by:
      `getClientInfo` in interface `Connection`
    Throws:
      `SQLException`

  - ### getDefaultQueryTimeout

    @Deprecated public Integer getDefaultQueryTimeout()
    Deprecated.
    Use `getDefaultQueryTimeoutDuration()`.
    Gets the default query timeout that will be used for `Statement`s created from this connection. `null` means that the driver default will be used.
    Returns:
      query timeout limit in seconds; zero means there is no limit.

  - ### getDefaultQueryTimeoutDuration

    public Duration getDefaultQueryTimeoutDuration()
    Gets the default query timeout that will be used for `Statement`s created from this connection. `null` means that the driver default will be used.
    Returns:
      query timeout limit; zero means there is no limit.
    Since:
      2.10.0

  - ### getDelegate

    public C getDelegate()
    Returns my underlying `Connection`.
    Returns:
      my underlying `Connection`.

  - ### getDelegateInternal

    protected final C getDelegateInternal()
    Gets the delegate connection.
    Returns:
      the delegate connection.

  - ### getHoldability

    public int getHoldability() throws SQLException
    Specified by:
      `getHoldability` in interface `Connection`
    Throws:
      `SQLException`

  - ### getInnermostDelegate

    public Connection getInnermostDelegate()
    If my underlying `Connection` is not a `DelegatingConnection`, returns it, otherwise recursively invokes this method on my delegate.

    Hence this method will return the first delegate that is not a `DelegatingConnection`, or `null` when no non-`DelegatingConnection` delegate can be found by traversing this chain.

    This method is useful when you may have nested `DelegatingConnection`s, and you want to make sure to obtain a "genuine" `Connection`.

    Returns:
      innermost delegate.

  - ### getInnermostDelegateInternal

    public final Connection getInnermostDelegateInternal()
    Although this method is public, it is part of the internal API and should not be used by clients. The signature of this method may change at any time including in ways that break backwards compatibility.
    Returns:
      innermost delegate.

  - ### getMetaData

    public DatabaseMetaData getMetaData() throws SQLException
    Specified by:
      `getMetaData` in interface `Connection`
    Throws:
      `SQLException`

  - ### getNetworkTimeout

    public int getNetworkTimeout() throws SQLException
    Specified by:
      `getNetworkTimeout` in interface `Connection`
    Throws:
      `SQLException`

  - ### getSchema

    public String getSchema() throws SQLException
    Specified by:
      `getSchema` in interface `Connection`
    Throws:
      `SQLException`

  - ### getTransactionIsolation

    public int getTransactionIsolation() throws SQLException
    Specified by:
      `getTransactionIsolation` in interface `Connection`
    Throws:
      `SQLException`

  - ### getTypeMap

    public Map<String,Class<?>> getTypeMap() throws SQLException
    Specified by:
      `getTypeMap` in interface `Connection`
    Throws:
      `SQLException`

  - ### getWarnings

    public SQLWarning getWarnings() throws SQLException
    Specified by:
      `getWarnings` in interface `Connection`
    Throws:
      `SQLException`

  - ### handleException

    protected void handleException(SQLException e) throws SQLException
    Handles the given exception by throwing it.
    Parameters:
      `e` - the exception to throw.
    Throws:
      `SQLException` - the exception to throw.

  - ### handleExceptionNoThrow

    protected <T extends Throwable> T handleExceptionNoThrow(T e)
    Handles the given `SQLException`.
    Type Parameters:
      `T` - The throwable type.
    Parameters:
      `e` - The SQLException
    Returns:
      the given `SQLException`
    Since:
      2.7.0

  - ### innermostDelegateEquals

    public boolean innermostDelegateEquals(Connection c)
    Compares innermost delegate to the given connection.
    Parameters:
      `c` - connection to compare innermost delegate with
    Returns:
      true if innermost delegate equals `c`

  - ### isClosed

    public boolean isClosed() throws SQLException
    Specified by:
      `isClosed` in interface `Connection`
    Throws:
      `SQLException`

  - ### isClosedInternal

    protected boolean isClosedInternal()
    Tests the raw internal closed state.
    Returns:
      the raw internal closed state.

  - ### isReadOnly

    public boolean isReadOnly() throws SQLException
    Specified by:
      `isReadOnly` in interface `Connection`
    Throws:
      `SQLException`

  - ### isValid

    public boolean isValid(Duration timeout) throws SQLException
    Tests if the connection has not been closed and is still valid.
    Parameters:
      `timeout` - The duration to wait for the database operation used to validate the connection to complete.
    Returns:
      See `Connection.isValid(int)`.
    Throws:
      `SQLException` - See `Connection.isValid(int)`.
    Since:
      2.10.0
    See Also:
      - `Connection.isValid(int)`

  - ### isValid

    @Deprecated public boolean isValid(int timeoutSeconds) throws SQLException
    Deprecated.
    Use `isValid(Duration)`.
    Specified by:
      `isValid` in interface `Connection`
    Throws:
      `SQLException`

  - ### isWrapperFor

    public boolean isWrapperFor(Class<?> iface) throws SQLException
    Specified by:
      `isWrapperFor` in interface `Wrapper`
    Throws:
      `SQLException`

  - ### nativeSQL

    public String nativeSQL(String sql) throws SQLException
    Specified by:
      `nativeSQL` in interface `Connection`
    Throws:
      `SQLException`

  - ### passivate

    protected void passivate() throws SQLException
    Clears the list of objects being traced by this object.
    Throws:
      `SQLException` - Thrown if not all traced objects were closed.

  - ### prepareCall

    public CallableStatement prepareCall(String sql) throws SQLException
    Specified by:
      `prepareCall` in interface `Connection`
    Throws:
      `SQLException`

  - ### prepareCall

    public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
    Specified by:
      `prepareCall` in interface `Connection`
    Throws:
      `SQLException`

  - ### prepareCall

    public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
    Specified by:
      `prepareCall` in interface `Connection`
    Throws:
      `SQLException`

  - ### prepareStatement

    public PreparedStatement prepareStatement(String sql) throws SQLException
    Specified by:
      `prepareStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### prepareStatement

    public PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) throws SQLException
    Specified by:
      `prepareStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### prepareStatement

    public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
    Specified by:
      `prepareStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### prepareStatement

    public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
    Specified by:
      `prepareStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### prepareStatement

    public PreparedStatement prepareStatement(String sql, int[] columnIndexes) throws SQLException
    Specified by:
      `prepareStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### prepareStatement

    public PreparedStatement prepareStatement(String sql, String[] columnNames) throws SQLException
    Specified by:
      `prepareStatement` in interface `Connection`
    Throws:
      `SQLException`

  - ### releaseSavepoint

    public void releaseSavepoint(Savepoint savepoint) throws SQLException
    Specified by:
      `releaseSavepoint` in interface `Connection`
    Throws:
      `SQLException`

  - ### rollback

    public void rollback() throws SQLException
    Specified by:
      `rollback` in interface `Connection`
    Throws:
      `SQLException`

  - ### rollback

    public void rollback(Savepoint savepoint) throws SQLException
    Specified by:
      `rollback` in interface `Connection`
    Throws:
      `SQLException`

  - ### setAutoCommit

    public void setAutoCommit(boolean autoCommit) throws SQLException
    Specified by:
      `setAutoCommit` in interface `Connection`
    Throws:
      `SQLException`

  - ### setCacheState

    public void setCacheState(boolean cacheState)
    Sets whether to cache properties. The cached properties are:
    - auto-commit
    - catalog
    - schema
    - read-only
    Parameters:
      `cacheState` - The new value for the state caching flag

  - ### setCatalog

    public void setCatalog(String catalog) throws SQLException
    Specified by:
      `setCatalog` in interface `Connection`
    Throws:
      `SQLException`

  - ### setClientInfo

    public void setClientInfo(Properties properties) throws SQLClientInfoException
    Specified by:
      `setClientInfo` in interface `Connection`
    Throws:
      `SQLClientInfoException`

  - ### setClientInfo

    public void setClientInfo(String name, String value) throws SQLClientInfoException
    Specified by:
      `setClientInfo` in interface `Connection`
    Throws:
      `SQLClientInfoException`

  - ### setClosedInternal

    protected void setClosedInternal(boolean closed)
    Sets the raw internal closed state.
    Parameters:
      `closed` - the raw internal closed state.

  - ### setDefaultQueryTimeout

    public void setDefaultQueryTimeout(Duration defaultQueryTimeoutDuration)
    Sets the default query timeout that will be used for `Statement`s created from this connection. `null` means that the driver default will be used.
    Parameters:
      `defaultQueryTimeoutDuration` - the new query timeout limit Duration; zero means there is no limit.
    Since:
      2.10.0

  - ### setDefaultQueryTimeout

    @Deprecated public void setDefaultQueryTimeout(Integer defaultQueryTimeoutSeconds)
    Deprecated.
    Use `setDefaultQueryTimeout(Duration)`.
    Sets the default query timeout that will be used for `Statement`s created from this connection. `null` means that the driver default will be used.
    Parameters:
      `defaultQueryTimeoutSeconds` - the new query timeout limit in seconds; zero means there is no limit.

  - ### setDelegate

    public void setDelegate(C connection)
    Sets my delegate.
    Parameters:
      `connection` - my delegate, may be null.

  - ### setHoldability

    public void setHoldability(int holdability) throws SQLException
    Specified by:
      `setHoldability` in interface `Connection`
    Throws:
      `SQLException`

  - ### setNetworkTimeout

    public void setNetworkTimeout(Executor executor, int milliseconds) throws SQLException
    Specified by:
      `setNetworkTimeout` in interface `Connection`
    Throws:
      `SQLException`

  - ### setReadOnly

    public void setReadOnly(boolean readOnly) throws SQLException
    Specified by:
      `setReadOnly` in interface `Connection`
    Throws:
      `SQLException`

  - ### setSavepoint

    public Savepoint setSavepoint() throws SQLException
    Specified by:
      `setSavepoint` in interface `Connection`
    Throws:
      `SQLException`

  - ### setSavepoint

    public Savepoint setSavepoint(String name) throws SQLException
    Specified by:
      `setSavepoint` in interface `Connection`
    Throws:
      `SQLException`

  - ### setSchema

    public void setSchema(String schema) throws SQLException
    Specified by:
      `setSchema` in interface `Connection`
    Throws:
      `SQLException`

  - ### setTransactionIsolation

    public void setTransactionIsolation(int level) throws SQLException
    Specified by:
      `setTransactionIsolation` in interface `Connection`
    Throws:
      `SQLException`

  - ### setTypeMap

    public void setTypeMap(Map<String,Class<?>> map) throws SQLException
    Specified by:
      `setTypeMap` in interface `Connection`
    Throws:
      `SQLException`

  - ### toString

    public String toString()
    Returns a string representation of the metadata associated with the innermost delegate connection.
    Overrides:
      `toString` in class `Object`

  - ### unwrap

    public <T> T unwrap(Class<T> iface) throws SQLException
    Specified by:
      `unwrap` in interface `Wrapper`
    Throws:
      `SQLException`