Package org.apache.tomcat.dbcp.dbcp2

## Class PoolableConnection

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp2.AbandonedTrace
  - - org.apache.tomcat.dbcp.dbcp2.DelegatingConnection<java.sql.Connection>
    - - org.apache.tomcat.dbcp.dbcp2.PoolableConnection

All Implemented Interfaces:
  `java.lang.AutoCloseable`, `java.sql.Connection`, `java.sql.Wrapper`, `PoolableConnectionMXBean`, `TrackedUse`

    public class PoolableConnection
    extends DelegatingConnection<java.sql.Connection>
    implements PoolableConnectionMXBean

A delegating connection that, rather than closing the underlying connection, returns itself to an `ObjectPool` when closed.

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
`PoolableConnection​(java.sql.Connection conn, ObjectPool<PoolableConnection> pool, javax.management.ObjectName jmxName)`
`PoolableConnection​(java.sql.Connection conn, ObjectPool<PoolableConnection> pool, javax.management.ObjectName jmxObjectName, java.util.Collection<java.lang.String> disconnectSqlCodes, boolean fastFailValidation)`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `abort​(java.util.concurrent.Executor executor)` Abort my underlying `Connection`.
`void` `close()` Returns me to my pool.
`java.util.Collection<java.lang.String>` `getDisconnectionSqlCodes()`
`java.lang.String` `getToString()` Expose the `DelegatingConnection.toString()` method via a bean getter so it can be read as a property via JMX.
`protected void` `handleException​(java.sql.SQLException e)` Handles the given exception by throwing it.
`boolean` `isClosed()`
`boolean` `isFastFailValidation()`
`protected void` `passivate()`
`void` `reallyClose()` Actually close my underlying `Connection`.
`void` `validate​(java.lang.String sql, int timeoutSeconds)` Validates the connection, using the following algorithm: If `fastFailValidation` (constructor argument) is `true` and this connection has previously thrown a fatal disconnection exception, a `SQLException` is thrown. If `sql` is null, the driver's #`isValid(timeout)` is called.

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

`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, handleExceptionNoThrow, innermostDelegateEquals, isClosedInternal, isReadOnly, isValid, isWrapperFor, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCacheState, setCatalog, setClientInfo, setClientInfo, setClosedInternal, setDefaultQueryTimeout, setDelegate, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap, toString, 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`

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

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

### Methods inherited from interface org.apache.tomcat.dbcp.dbcp2.PoolableConnectionMXBean

`clearCachedState, clearWarnings, getAutoCommit, getCacheState, getCatalog, getHoldability, getSchema, getTransactionIsolation, isReadOnly, setAutoCommit, setCacheState, setCatalog, setHoldability, setReadOnly, setSchema, setTransactionIsolation`

### Constructor Detail

#### PoolableConnection

    public PoolableConnection​(java.sql.Connection conn,
                              ObjectPool<PoolableConnection> pool,
                              javax.management.ObjectName jmxObjectName,
                              java.util.Collection<java.lang.String> disconnectSqlCodes,
                              boolean fastFailValidation)

Parameters:
  `conn` - my underlying connection
  `pool` - the pool to which I should return when closed
  `jmxObjectName` - JMX name
  `disconnectSqlCodes` - SQL_STATE codes considered fatal disconnection errors
  `fastFailValidation` - true means fatal disconnection errors cause subsequent validations to fail immediately (no attempt to run query or isValid)

#### PoolableConnection

    public PoolableConnection​(java.sql.Connection conn,
                              ObjectPool<PoolableConnection> pool,
                              javax.management.ObjectName jmxName)

Parameters:
  `conn` - my underlying connection
  `pool` - the pool to which I should return when closed
  `jmxName` - JMX name

### Method Detail

#### passivate

    protected void passivate()
                      throws java.sql.SQLException

Overrides:
  `passivate` in class `DelegatingConnection<java.sql.Connection>`
Throws:
  `java.sql.SQLException`

#### isClosed

    public boolean isClosed()
                     throws java.sql.SQLException

This method should not be used by a client to determine whether or not a connection should be return to the connection pool (by calling `close()`). Clients should always attempt to return a connection to the pool once it is no longer required.

Specified by:
  `isClosed` in interface `java.sql.Connection`
Specified by:
  `isClosed` in interface `PoolableConnectionMXBean`
Overrides:
  `isClosed` in class `DelegatingConnection<java.sql.Connection>`
Throws:
  `java.sql.SQLException`

#### close

    public void close()
               throws java.sql.SQLException

Returns me to my pool.

Specified by:
  `close` in interface `java.lang.AutoCloseable`
Specified by:
  `close` in interface `java.sql.Connection`
Specified by:
  `close` in interface `PoolableConnectionMXBean`
Overrides:
  `close` in class `DelegatingConnection<java.sql.Connection>`
Throws:
  `java.sql.SQLException`

#### reallyClose

    public void reallyClose()
                     throws java.sql.SQLException

Actually close my underlying `Connection`.

Specified by:
  `reallyClose` in interface `PoolableConnectionMXBean`
Throws:
  `java.sql.SQLException`

#### abort

    public void abort​(java.util.concurrent.Executor executor)
               throws java.sql.SQLException

Abort my underlying `Connection`.

Specified by:
  `abort` in interface `java.sql.Connection`
Overrides:
  `abort` in class `DelegatingConnection<java.sql.Connection>`
Throws:
  `java.sql.SQLException`
Since:
  2.9.0

#### getToString

    public java.lang.String getToString()

Expose the `DelegatingConnection.toString()` method via a bean getter so it can be read as a property via JMX.

Specified by:
  `getToString` in interface `PoolableConnectionMXBean`

#### validate

    public void validate​(java.lang.String sql,
                         int timeoutSeconds)
                  throws java.sql.SQLException

Validates the connection, using the following algorithm:

1. If `fastFailValidation` (constructor argument) is `true` and this connection has previously thrown a fatal disconnection exception, a `SQLException` is thrown.
2. If `sql` is null, the driver's #`isValid(timeout)` is called. If it returns `false`, `SQLException` is thrown; otherwise, this method returns successfully.
3. If `sql` is not null, it is executed as a query and if the resulting `ResultSet` contains at least one row, this method returns successfully. If not, `SQLException` is thrown.

Parameters:
  `sql` - The validation SQL query.
  `timeoutSeconds` - The validation timeout in seconds.
Throws:
  `java.sql.SQLException` - Thrown when validation fails or an SQLException occurs during validation

#### handleException

    protected void handleException​(java.sql.SQLException e)
                            throws java.sql.SQLException

Description copied from class: `DelegatingConnection`
Handles the given exception by throwing it.

Overrides:
  `handleException` in class `DelegatingConnection<java.sql.Connection>`
Parameters:
  `e` - the exception to throw.
Throws:
  `java.sql.SQLException` - the exception to throw.

#### getDisconnectionSqlCodes

    public java.util.Collection<java.lang.String> getDisconnectionSqlCodes()

Returns:
  The disconnection SQL codes.
Since:
  2.6.0

#### isFastFailValidation

    public boolean isFastFailValidation()

Returns:
  Whether to fail-fast.
Since:
  2.6.0