# Class PoolableConnection

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

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

Direct Known Subclasses:
  `PoolableManagedConnection`

public class PoolableConnection extends DelegatingConnection<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 Connection

`TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE`

## Constructor Summary

Constructors
Constructor
Description
`PoolableConnection(Connection conn, ObjectPool<PoolableConnection> pool, ObjectName jmxName)`
`PoolableConnection(Connection conn, ObjectPool<PoolableConnection> pool, ObjectName jmxObjectName, Collection<String> disconnectSqlCodes, boolean fastFailValidation)`
`PoolableConnection(Connection conn, ObjectPool<PoolableConnection> pool, ObjectName jmxObjectName, Collection<String> disconnectSqlCodes, Collection<String> disconnectionIgnoreSqlCodes, boolean fastFailValidation)`
Creates a new `PoolableConnection` instance.

## Method Summary

Modifier and Type
Method
Description
`void`
`abort(Executor executor)`
Abort my underlying `Connection`.
`void`
`close()`
Returns this instance to my containing pool.
`Collection<String>`
`getDisconnectionSqlCodes()`
`String`
`getToString()`
Gets the value of the `DelegatingConnection.toString()` method via a bean getter, so it can be read as a property via JMX.
`protected void`
`handleException(SQLException e)`
Handles the given exception by throwing it.
`boolean`
`isClosed()`
See `Connection.isClosed()`.
`boolean`
`isFastFailValidation()`
`protected void`
`passivate()`
Clears the list of objects being traced by this object.
`void`
`reallyClose()`
Closes the underlying `Connection`.
`void`
`setLastUsed()`
Sets the time this object was last used to the current time in milliseconds.
`void`
`validate(String sql, int timeoutSeconds)`
Deprecated.
Use `validate(String, Duration)`.
`void`
`validate(String sql, Duration timeoutDuration)`
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 DelegatingConnection

`activate, checkOpen, clearCachedState, clearWarnings, closeInternal, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCacheState, getCatalog, getClientInfo, getClientInfo, getDefaultQueryTimeout, getDefaultQueryTimeoutDuration, getDelegate, getDelegateInternal, getHoldability, getInnermostDelegate, getInnermostDelegateInternal, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, handleExceptionNoThrow, innermostDelegateEquals, isClosedInternal, isReadOnly, isValid, isValid, isWrapperFor, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCacheState, setCatalog, setClientInfo, setClientInfo, setClosedInternal, setDefaultQueryTimeout, setDefaultQueryTimeout, setDelegate, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap, toString, unwrap`

### Methods inherited from class AbandonedTrace

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

### Methods inherited from class Object

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

### Methods inherited from interface Connection

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

### Methods inherited from interface PoolableConnectionMXBean

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

## Constructor Details

### PoolableConnection

public PoolableConnection(Connection conn, ObjectPool<PoolableConnection> pool, ObjectName jmxName)

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

### PoolableConnection

public PoolableConnection(Connection conn, ObjectPool<PoolableConnection> pool, ObjectName jmxObjectName, Collection<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(Connection conn, ObjectPool<PoolableConnection> pool, ObjectName jmxObjectName, Collection<String> disconnectSqlCodes, Collection<String> disconnectionIgnoreSqlCodes, boolean fastFailValidation)
Creates a new `PoolableConnection` instance.

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
  `disconnectionIgnoreSqlCodes` - SQL State codes that should be ignored when determining fatal disconnection errors
  `fastFailValidation` - true means fatal disconnection errors cause subsequent validations to fail immediately (no attempt to run query or isValid)
Since:
  2.13.0

## Method Details

### abort

public void abort(Executor executor) throws SQLException
Abort my underlying `Connection`.

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

### close

public void close() throws SQLException
Returns this instance to my containing pool.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Connection`
Specified by:
  `close` in interface `PoolableConnectionMXBean`
Overrides:
  `close` in class `DelegatingConnection<Connection>`
Throws:
  `SQLException` - Ignored here, for subclasses.

### getDisconnectionSqlCodes

public Collection<String> getDisconnectionSqlCodes()

Returns:
  The disconnection SQL codes.
Since:
  2.6.0

### getToString

public String getToString()
Gets the value of the `DelegatingConnection.toString()` method via a bean getter, so it can be read as a property via JMX.

Specified by:
  `getToString` in interface `PoolableConnectionMXBean`
Returns:
  the value of the `Object.toString()`.

### handleException

protected void handleException(SQLException e) throws SQLException
Description copied from class: `DelegatingConnection`
Handles the given exception by throwing it.

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

### isClosed

public boolean isClosed() throws SQLException
See `Connection.isClosed()`.

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 `Connection`
Specified by:
  `isClosed` in interface `PoolableConnectionMXBean`
Overrides:
  `isClosed` in class `DelegatingConnection<Connection>`
Returns:
  See `Connection.isClosed()`.
Throws:
  `SQLException` - See `Connection.isClosed()`.

### isFastFailValidation

public boolean isFastFailValidation()

Returns:
  Whether to fail-fast.
Since:
  2.6.0

### passivate

protected void passivate() throws SQLException
Description copied from class: `DelegatingConnection`
Clears the list of objects being traced by this object.

Overrides:
  `passivate` in class `DelegatingConnection<Connection>`
Throws:
  `SQLException` - Thrown if not all traced objects were closed.

### reallyClose

public void reallyClose() throws SQLException
Closes the underlying `Connection`.

Specified by:
  `reallyClose` in interface `PoolableConnectionMXBean`
Throws:
  `SQLException` - Thrown if the connection can be closed.

### setLastUsed

public void setLastUsed()
Description copied from class: `AbandonedTrace`
Sets the time this object was last used to the current time in milliseconds.

Overrides:
  `setLastUsed` in class `AbandonedTrace`

### validate

public void validate(String sql, Duration timeoutDuration) throws 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.
  `timeoutDuration` - The validation timeout in seconds.
Throws:
  `SQLException` - Thrown when validation fails or an SQLException occurs during validation
Since:
  2.10.0

### validate

@Deprecated public void validate(String sql, int timeoutSeconds) throws SQLException
Deprecated.
Use `validate(String, Duration)`.
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:
  `SQLException` - Thrown when validation fails or an SQLException occurs during validation