Package org.apache.commons.dbcp2

# Class PoolableConnection

java.lang.Object
org.apache.commons.dbcp2.AbandonedTrace
org.apache.commons.dbcp2.DelegatingConnection<Connection>
org.apache.commons.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 java.sql.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)`
  Constructs a new instance.
  `PoolableConnection(Connection conn, ObjectPool<PoolableConnection> pool, ObjectName jmxObjectName, Collection<String> disconnectSqlCodes, boolean fastFailValidation)`
  Constructs a new instance.
  `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()`
  Gets the disconnection SQL codes.
  `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()`
  Tests whether to fail-fast.
  `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 org.apache.commons.dbcp2.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 org.apache.commons.dbcp2.AbandonedTrace

  `addTrace, clearTrace, close, getLastUsed, getLastUsedInstant, 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 org.apache.commons.dbcp2.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)
    Constructs a new instance.
    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)
    Constructs a new 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
      `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()
    Gets the disconnection SQL codes.
    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()
    Tests whether to fail-fast.
    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