PoolableConnection (Apache Tomcat 8.5.89 API Documentation)

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
    Constructor | Description
    --- | ---
    `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
    Modifier and Type | Method | Description
    --- | --- | ---
    `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