Package org.apache.tomcat.dbcp.dbcp2

## Class DelegatingConnection<C extends Connection>

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp2.AbandonedTrace
  - - org.apache.tomcat.dbcp.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
`DelegatingConnection​(C connection)` Creates a wrapper for the Connection which traces this Connection in the AbandonedObjectPool.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`void` `abort​(Executor executor)`
`protected void` `activate()`
`protected void` `checkOpen()`
`void` `clearCachedState()` Clears the cached state.
`void` `clearWarnings()`
`void` `close()` Closes the underlying connection, and close any Statements that were not explicitly closed.
`protected void` `closeInternal()`
`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()` Returns the state caching flag.
`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 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.
`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()`
`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()`
`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 the state caching flag.
`void` `setCatalog​(String catalog)`
`void` `setClientInfo​(String name, String value)`
`void` `setClientInfo​(Properties properties)`
`protected void` `setClosedInternal​(boolean closed)`
`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.tomcat.dbcp.dbcp2.AbandonedTrace

`addTrace, clearTrace, close, getLastUsed, getLastUsedInstant, getTrace, removeThisTrace, removeTrace, setLastUsed, setLastUsed, setLastUsed`

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

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

### Methods inherited from interface java.sql.Connection

`beginRequest, endRequest, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid`

### Constructor Detail

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

#### abort

    public void abort​(Executor executor)
               throws SQLException

Specified by:
  `abort` in interface `Connection`
Throws:
  `SQLException`

#### activate

    protected void activate()

#### checkOpen

    protected void checkOpen()
                      throws SQLException

Throws:
  `SQLException`

#### clearCachedState

    public void clearCachedState()

Clears the cached state. Call when you known 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

Throws:
  `SQLException`

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

Returns the state caching flag.

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()

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

Throws:
  `SQLException`

#### 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 the state caching flag.

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)

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