Package org.apache.commons.dbcp2

## Class PoolableConnectionFactory

- java.lang.Object
- - org.apache.commons.dbcp2.PoolableConnectionFactory

- All Implemented Interfaces:
    `PooledObjectFactory<PoolableConnection>`
  Direct Known Subclasses:
    `PoolableManagedConnectionFactory`

      public class PoolableConnectionFactory
      extends Object
      implements PooledObjectFactory<PoolableConnection>

  A `PooledObjectFactory` that creates `PoolableConnection`s.
  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PoolableConnectionFactory​(ConnectionFactory connFactory, ObjectName dataSourceJmxObjectName)` | Creates a new `PoolableConnectionFactory`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `activateObject​(PooledObject<PoolableConnection> p)` |
    `void` | `destroyObject​(PooledObject<PoolableConnection> p)` |
    `void` | `destroyObject​(PooledObject<PoolableConnection> p, DestroyMode mode)` |
    `boolean` | `getCacheState()` | Gets the cache state.
    `ConnectionFactory` | `getConnectionFactory()` | Gets the connection factory.
    `protected AtomicLong` | `getConnectionIndex()` |
    `Collection<String>` | `getConnectionInitSqls()` |
    `ObjectName` | `getDataSourceJmxName()` |
    `ObjectName` | `getDataSourceJmxObjectName()` |
    `Boolean` | `getDefaultAutoCommit()` |
    `String` | `getDefaultCatalog()` |
    `Integer` | `getDefaultQueryTimeout()` | Deprecated. Use `getDefaultQueryTimeoutDuration()`.
    `Duration` | `getDefaultQueryTimeoutDuration()` | Gets the default query timeout Duration.
    `Integer` | `getDefaultQueryTimeoutSeconds()` | Deprecated. Use `getDefaultQueryTimeoutDuration()`.
    `Boolean` | `getDefaultReadOnly()` |
    `String` | `getDefaultSchema()` |
    `int` | `getDefaultTransactionIsolation()` |
    `Collection<String>` | `getDisconnectionSqlCodes()` | SQL_STATE codes considered to signal fatal conditions.
    `Duration` | `getMaxConnDuration()` | Gets the Maximum connection duration.
    `long` | `getMaxConnLifetimeMillis()` | Gets the Maximum connection lifetime in milliseconds.
    `protected int` | `getMaxOpenPreparedStatements()` |
    `ObjectPool<PoolableConnection>` | `getPool()` | Returns the `ObjectPool` in which `Connection`s are pooled.
    `boolean` | `getPoolStatements()` |
    `String` | `getValidationQuery()` |
    `Duration` | `getValidationQueryTimeoutDuration()` | Gets the query timeout in seconds.
    `int` | `getValidationQueryTimeoutSeconds()` | Deprecated. Use `getValidationQueryTimeoutDuration()`.
    `protected void` | `initializeConnection​(Connection conn)` |
    `boolean` | `isAutoCommitOnReturn()` |
    `boolean` | `isEnableAutoCommitOnReturn()` | Deprecated. Use `isAutoCommitOnReturn()`.
    `boolean` | `isFastFailValidation()` | True means that validation will fail immediately for connections that have previously thrown SQLExceptions with SQL_STATE indicating fatal disconnection errors.
    `boolean` | `isRollbackOnReturn()` |
    `PooledObject<PoolableConnection>` | `makeObject()` |
    `void` | `passivateObject​(PooledObject<PoolableConnection> p)` |
    `void` | `setAutoCommitOnReturn​(boolean autoCommitOnReturn)` |
    `void` | `setCacheState​(boolean cacheState)` |
    `void` | `setClearStatementPoolOnReturn​(boolean clearStatementPoolOnReturn)` | Sets whether the pool of statements (which was enabled with `setPoolStatements(boolean)`) should be cleared when the connection is returned to its pool.
    `void` | `setConnectionInitSql​(Collection<String> connectionInitSqls)` | Sets the SQL statements I use to initialize newly created `Connection`s.
    `void` | `setDefaultAutoCommit​(Boolean defaultAutoCommit)` | Sets the default "auto commit" setting for borrowed `Connection`s
    `void` | `setDefaultCatalog​(String defaultCatalog)` | Sets the default "catalog" setting for borrowed `Connection`s
    `void` | `setDefaultQueryTimeout​(Integer defaultQueryTimeoutSeconds)` | Deprecated. Use `setDefaultQueryTimeout(Duration)`.
    `void` | `setDefaultQueryTimeout​(Duration defaultQueryTimeoutDuration)` | Sets the query timeout Duration.
    `void` | `setDefaultReadOnly​(Boolean defaultReadOnly)` | Sets the default "read only" setting for borrowed `Connection`s
    `void` | `setDefaultSchema​(String defaultSchema)` | Sets the default "schema" setting for borrowed `Connection`s
    `void` | `setDefaultTransactionIsolation​(int defaultTransactionIsolation)` | Sets the default "Transaction Isolation" setting for borrowed `Connection`s
    `void` | `setDisconnectionSqlCodes​(Collection<String> disconnectionSqlCodes)` |
    `void` | `setEnableAutoCommitOnReturn​(boolean autoCommitOnReturn)` | Deprecated. Use `setAutoCommitOnReturn(boolean)`.
    `void` | `setFastFailValidation​(boolean fastFailValidation)` |
    `void` | `setMaxConn​(Duration maxConnDuration)` | Sets the maximum lifetime in milliseconds of a connection after which the connection will always fail activation, passivation and validation.
    `void` | `setMaxConnLifetimeMillis​(long maxConnLifetimeMillis)` | Deprecated. Use `setMaxConn(Duration)`.
    `void` | `setMaxOpenPreparedStatements​(int maxOpenPreparedStatements)` | Sets the maximum number of open prepared statements.
    `void` | `setMaxOpenPrepatedStatements​(int maxOpenPreparedStatements)` | Deprecated. Use `setMaxOpenPreparedStatements(int)`.
    `void` | `setPool​(ObjectPool<PoolableConnection> pool)` | Sets the `ObjectPool` in which to pool `Connection`s.
    `void` | `setPoolStatements​(boolean poolStatements)` |
    `void` | `setRollbackOnReturn​(boolean rollbackOnReturn)` |
    `void` | `setValidationQuery​(String validationQuery)` | Sets the query I use to `validate` `Connection`s.
    `void` | `setValidationQueryTimeout​(int validationQueryTimeoutSeconds)` | Deprecated. `setValidationQueryTimeout(Duration)`.
    `void` | `setValidationQueryTimeout​(Duration validationQueryTimeoutDuration)` | Sets the validation query timeout, the amount of time, that connection validation will wait for a response from the database when executing a validation query.
    `void` | `validateConnection​(PoolableConnection conn)` | Validates the given connection if it is open.
    `boolean` | `validateObject​(PooledObject<PoolableConnection> p)` |

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

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

- - ### Constructor Detail

    - #### PoolableConnectionFactory

          public PoolableConnectionFactory​(ConnectionFactory connFactory,
                                           ObjectName dataSourceJmxObjectName)

      Creates a new `PoolableConnectionFactory`.
      Parameters:
        `connFactory` - the `ConnectionFactory` from which to obtain base `Connection`s
        `dataSourceJmxObjectName` - The JMX object name, may be null.

  - ### Method Detail

    - #### activateObject

          public void activateObject​(PooledObject<PoolableConnection> p)
                              throws SQLException

      Specified by:
        `activateObject` in interface `PooledObjectFactory<PoolableConnection>`
      Throws:
        `SQLException`

    - #### destroyObject

          public void destroyObject​(PooledObject<PoolableConnection> p)
                             throws SQLException

      Specified by:
        `destroyObject` in interface `PooledObjectFactory<PoolableConnection>`
      Throws:
        `SQLException`

    - #### destroyObject

          public void destroyObject​(PooledObject<PoolableConnection> p,
                                    DestroyMode mode)
                             throws SQLException

      Specified by:
        `destroyObject` in interface `PooledObjectFactory<PoolableConnection>`
      Throws:
        `SQLException`
      Since:
        2.9.0

    - #### getCacheState

          public boolean getCacheState()

      Gets the cache state.
      Returns:
        The cache state.
      Since:
        2.6.0.

    - #### getConnectionFactory

          public ConnectionFactory getConnectionFactory()

      Gets the connection factory.
      Returns:
        The connection factory.
      Since:
        2.6.0.

    - #### getConnectionIndex

          protected AtomicLong getConnectionIndex()

    - #### getConnectionInitSqls

          public Collection<String> getConnectionInitSqls()

      Returns:
        The collection of initialization SQL statements.
      Since:
        2.6.0

    - #### getDataSourceJmxName

          public ObjectName getDataSourceJmxName()

      Returns:
        The data source JMX ObjectName
      Since:
        2.6.0.

    - #### getDataSourceJmxObjectName

          public ObjectName getDataSourceJmxObjectName()

      Returns:
        The data source JMS ObjectName.
      Since:
        2.6.0

    - #### getDefaultAutoCommit

          public Boolean getDefaultAutoCommit()

      Returns:
        Default auto-commit value.
      Since:
        2.6.0

    - #### getDefaultCatalog

          public String getDefaultCatalog()

      Returns:
        Default catalog.
      Since:
        2.6.0

    - #### getDefaultQueryTimeout

          @Deprecated
          public Integer getDefaultQueryTimeout()

      Deprecated.
      Use `getDefaultQueryTimeoutDuration()`.
      Returns:
        Default query timeout in seconds.

    - #### getDefaultQueryTimeoutDuration

          public Duration getDefaultQueryTimeoutDuration()

      Gets the default query timeout Duration.
      Returns:
        Default query timeout Duration.
      Since:
        2.10.0

    - #### getDefaultQueryTimeoutSeconds

          @Deprecated
          public Integer getDefaultQueryTimeoutSeconds()

      Deprecated.
      Use `getDefaultQueryTimeoutDuration()`.
      Returns:
        Default query timeout in seconds.
      Since:
        2.6.0

    - #### getDefaultReadOnly

          public Boolean getDefaultReadOnly()

      Returns:
        Default read-only-value.
      Since:
        2.6.0

    - #### getDefaultSchema

          public String getDefaultSchema()

      Returns:
        Default schema.
      Since:
        2.6.0

    - #### getDefaultTransactionIsolation

          public int getDefaultTransactionIsolation()

      Returns:
        Default transaction isolation.
      Since:
        2.6.0

    - #### getDisconnectionSqlCodes

          public Collection<String> getDisconnectionSqlCodes()

      SQL_STATE codes considered to signal fatal conditions.

      Overrides the defaults in `Utils.getDisconnectionSqlCodes()` (plus anything starting with `Utils.DISCONNECTION_SQL_CODE_PREFIX`). If this property is non-null and `isFastFailValidation()` is `true`, whenever connections created by this factory generate exceptions with SQL_STATE codes in this list, they will be marked as "fatally disconnected" and subsequent validations will fail fast (no attempt at isValid or validation query).

      If `isFastFailValidation()` is `false` setting this property has no effect.

      Returns:
        SQL_STATE codes overriding defaults
      Since:
        2.1

    - #### getMaxConnDuration

          public Duration getMaxConnDuration()

      Gets the Maximum connection duration.
      Returns:
        Maximum connection duration.
      Since:
        2.10.0

    - #### getMaxConnLifetimeMillis

          public long getMaxConnLifetimeMillis()

      Gets the Maximum connection lifetime in milliseconds.
      Returns:
        Maximum connection lifetime in milliseconds.
      Since:
        2.6.0

    - #### getMaxOpenPreparedStatements

          protected int getMaxOpenPreparedStatements()

    - #### getPool

          public ObjectPool<PoolableConnection> getPool()

      Returns the `ObjectPool` in which `Connection`s are pooled.
      Returns:
        the connection pool

    - #### getPoolStatements

          public boolean getPoolStatements()

      Returns:
        Whether to pool statements.
      Since:
        2.6.0.

    - #### getValidationQuery

          public String getValidationQuery()

      Returns:
        Validation query.
      Since:
        2.6.0

    - #### getValidationQueryTimeoutDuration

          public Duration getValidationQueryTimeoutDuration()

      Gets the query timeout in seconds.
      Returns:
        Validation query timeout in seconds.
      Since:
        2.10.0

    - #### getValidationQueryTimeoutSeconds

          @Deprecated
          public int getValidationQueryTimeoutSeconds()

      Deprecated.
      Use `getValidationQueryTimeoutDuration()`.
      Gets the query timeout in seconds.
      Returns:
        Validation query timeout in seconds.
      Since:
        2.6.0

    - #### initializeConnection

          protected void initializeConnection​(Connection conn)
                                       throws SQLException

      Throws:
        `SQLException`

    - #### isAutoCommitOnReturn

          public boolean isAutoCommitOnReturn()

      Returns:
        Whether to auto-commit on return.
      Since:
        2.6.0

    - #### isEnableAutoCommitOnReturn

          @Deprecated
          public boolean isEnableAutoCommitOnReturn()

      Deprecated.
      Use `isAutoCommitOnReturn()`.
      Returns:
        Whether to auto-commit on return.

    - #### isFastFailValidation

          public boolean isFastFailValidation()

      True means that validation will fail immediately for connections that have previously thrown SQLExceptions with SQL_STATE indicating fatal disconnection errors.
      Returns:
        true if connections created by this factory will fast fail validation.
      Since:
        2.1, 2.5.0 Defaults to true, previous versions defaulted to false.
      See Also:
        `setDisconnectionSqlCodes(Collection)`

    - #### isRollbackOnReturn

          public boolean isRollbackOnReturn()

      Returns:
        Whether to rollback on return.

    - #### makeObject

          public PooledObject<PoolableConnection> makeObject()
                                                      throws SQLException

      Specified by:
        `makeObject` in interface `PooledObjectFactory<PoolableConnection>`
      Throws:
        `SQLException`

    - #### passivateObject

          public void passivateObject​(PooledObject<PoolableConnection> p)
                               throws SQLException

      Specified by:
        `passivateObject` in interface `PooledObjectFactory<PoolableConnection>`
      Throws:
        `SQLException`

    - #### setAutoCommitOnReturn

          public void setAutoCommitOnReturn​(boolean autoCommitOnReturn)

    - #### setCacheState

          public void setCacheState​(boolean cacheState)

    - #### setClearStatementPoolOnReturn

          public void setClearStatementPoolOnReturn​(boolean clearStatementPoolOnReturn)

      Sets whether the pool of statements (which was enabled with `setPoolStatements(boolean)`) should be cleared when the connection is returned to its pool. Default is false.
      Parameters:
        `clearStatementPoolOnReturn` - clear or not
      Since:
        2.8.0

    - #### setConnectionInitSql

          public void setConnectionInitSql​(Collection<String> connectionInitSqls)

      Sets the SQL statements I use to initialize newly created `Connection`s. Using `null` turns off connection initialization.
      Parameters:
        `connectionInitSqls` - SQL statement to initialize `Connection`s.

    - #### setDefaultAutoCommit

          public void setDefaultAutoCommit​(Boolean defaultAutoCommit)

      Sets the default "auto commit" setting for borrowed `Connection`s
      Parameters:
        `defaultAutoCommit` - the default "auto commit" setting for borrowed `Connection`s

    - #### setDefaultCatalog

          public void setDefaultCatalog​(String defaultCatalog)

      Sets the default "catalog" setting for borrowed `Connection`s
      Parameters:
        `defaultCatalog` - the default "catalog" setting for borrowed `Connection`s

    - #### setDefaultQueryTimeout

          public void setDefaultQueryTimeout​(Duration defaultQueryTimeoutDuration)

      Sets the query timeout Duration.
      Parameters:
        `defaultQueryTimeoutDuration` - the query timeout Duration.
      Since:
        2.10.0

    - #### setDefaultQueryTimeout

          @Deprecated
          public void setDefaultQueryTimeout​(Integer defaultQueryTimeoutSeconds)

      Deprecated.
      Use `setDefaultQueryTimeout(Duration)`.
      Sets the query timeout in seconds.
      Parameters:
        `defaultQueryTimeoutSeconds` - the query timeout in seconds.

    - #### setDefaultReadOnly

          public void setDefaultReadOnly​(Boolean defaultReadOnly)

      Sets the default "read only" setting for borrowed `Connection`s
      Parameters:
        `defaultReadOnly` - the default "read only" setting for borrowed `Connection`s

    - #### setDefaultSchema

          public void setDefaultSchema​(String defaultSchema)

      Sets the default "schema" setting for borrowed `Connection`s
      Parameters:
        `defaultSchema` - the default "schema" setting for borrowed `Connection`s
      Since:
        2.5.0

    - #### setDefaultTransactionIsolation

          public void setDefaultTransactionIsolation​(int defaultTransactionIsolation)

      Sets the default "Transaction Isolation" setting for borrowed `Connection`s
      Parameters:
        `defaultTransactionIsolation` - the default "Transaction Isolation" setting for returned `Connection`s

    - #### setDisconnectionSqlCodes

          public void setDisconnectionSqlCodes​(Collection<String> disconnectionSqlCodes)

      Parameters:
        `disconnectionSqlCodes` - The disconnection SQL codes.
      Since:
        2.1
      See Also:
        `getDisconnectionSqlCodes()`

    - #### setEnableAutoCommitOnReturn

          @Deprecated
          public void setEnableAutoCommitOnReturn​(boolean autoCommitOnReturn)

      Deprecated.
      Use `setAutoCommitOnReturn(boolean)`.
      Parameters:
        `autoCommitOnReturn` - Whether to auto-commit on return.

    - #### setFastFailValidation

          public void setFastFailValidation​(boolean fastFailValidation)

      Parameters:
        `fastFailValidation` - true means connections created by this factory will fast fail validation
      Since:
        2.1
      See Also:
        `isFastFailValidation()`

    - #### setMaxConn

          public void setMaxConn​(Duration maxConnDuration)

      Sets the maximum lifetime in milliseconds of a connection after which the connection will always fail activation, passivation and validation. A value of zero or less indicates an infinite lifetime. The default value is -1.
      Parameters:
        `maxConnDuration` - The maximum lifetime in milliseconds.
      Since:
        2.10.0

    - #### setMaxConnLifetimeMillis

          @Deprecated
          public void setMaxConnLifetimeMillis​(long maxConnLifetimeMillis)

      Deprecated.
      Use `setMaxConn(Duration)`.
      Sets the maximum lifetime in milliseconds of a connection after which the connection will always fail activation, passivation and validation. A value of zero or less indicates an infinite lifetime. The default value is -1.
      Parameters:
        `maxConnLifetimeMillis` - The maximum lifetime in milliseconds.

    - #### setMaxOpenPreparedStatements

          public void setMaxOpenPreparedStatements​(int maxOpenPreparedStatements)

      Sets the maximum number of open prepared statements.
      Parameters:
        `maxOpenPreparedStatements` - The maximum number of open prepared statements.

    - #### setMaxOpenPrepatedStatements

          @Deprecated
          public void setMaxOpenPrepatedStatements​(int maxOpenPreparedStatements)

      Deprecated.
      Use `setMaxOpenPreparedStatements(int)`.
      Deprecated due to typo in method name.
      Parameters:
        `maxOpenPreparedStatements` - The maximum number of open prepared statements.

    - #### setPool

          public void setPool​(ObjectPool<PoolableConnection> pool)

      Sets the `ObjectPool` in which to pool `Connection`s.
      Parameters:
        `pool` - the `ObjectPool` in which to pool those `Connection`s

    - #### setPoolStatements

          public void setPoolStatements​(boolean poolStatements)

    - #### setRollbackOnReturn

          public void setRollbackOnReturn​(boolean rollbackOnReturn)

    - #### setValidationQuery

          public void setValidationQuery​(String validationQuery)

      Sets the query I use to `validate` `Connection`s. Should return at least one row. If not specified, `Connection.isValid(int)` will be used to validate connections.
      Parameters:
        `validationQuery` - a query to use to `validate` `Connection`s.

    - #### setValidationQueryTimeout

          public void setValidationQueryTimeout​(Duration validationQueryTimeoutDuration)

      Sets the validation query timeout, the amount of time, that connection validation will wait for a response from the database when executing a validation query. Use a value less than or equal to 0 for no timeout.
      Parameters:
        `validationQueryTimeoutDuration` - new validation query timeout duration.
      Since:
        2.10.0

    - #### setValidationQueryTimeout

          @Deprecated
          public void setValidationQueryTimeout​(int validationQueryTimeoutSeconds)

      Deprecated.
      `setValidationQueryTimeout(Duration)`.
      Sets the validation query timeout, the amount of time, in seconds, that connection validation will wait for a response from the database when executing a validation query. Use a value less than or equal to 0 for no timeout.
      Parameters:
        `validationQueryTimeoutSeconds` - new validation query timeout value in seconds

    - #### validateConnection

          public void validateConnection​(PoolableConnection conn)
                                  throws SQLException

      Validates the given connection if it is open.
      Parameters:
        `conn` - the connection to validate.
      Throws:
        `SQLException` - if the connection is closed or validate fails.

    - #### validateObject

          public boolean validateObject​(PooledObject<PoolableConnection> p)

      Specified by:
        `validateObject` in interface `PooledObjectFactory<PoolableConnection>`