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 and Description
    `PoolableConnectionFactory(ConnectionFactory connFactory, ObjectName dataSourceJmxObjectName)` Creates a new `PoolableConnectionFactory`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `activateObject(PooledObject<PoolableConnection> p)`
    `void` | `destroyObject(PooledObject<PoolableConnection> p)`
    `boolean` | `getCacheState()`
    `ConnectionFactory` | `getConnectionFactory()`
    `protected AtomicLong` | `getConnectionIndex()`
    `Collection<String>` | `getConnectionInitSqls()`
    `ObjectName` | `getDataSourceJmxName()`
    `ObjectName` | `getDataSourceJmxObjectName()`
    `Boolean` | `getDefaultAutoCommit()`
    `String` | `getDefaultCatalog()`
    `Integer` | `getDefaultQueryTimeout()`
    `Integer` | `getDefaultQueryTimeoutSeconds()`
    `Boolean` | `getDefaultReadOnly()`
    `String` | `getDefaultSchema()`
    `int` | `getDefaultTransactionIsolation()`
    `Collection<String>` | `getDisconnectionSqlCodes()` SQL_STATE codes considered to signal fatal conditions.
    `long` | `getMaxConnLifetimeMillis()`
    `protected int` | `getMaxOpenPreparedStatements()`
    `ObjectPool<PoolableConnection>` | `getPool()` Returns the `ObjectPool` in which `Connection`s are pooled.
    `boolean` | `getPoolStatements()`
    `String` | `getValidationQuery()`
    `int` | `getValidationQueryTimeoutSeconds()`
    `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)`
    `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` | `setMaxConnLifetimeMillis(long maxConnLifetimeMillis)` Sets the maximum lifetime in milliseconds of a connection after which the connection will always fail activation, passivation and validation.
    `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)` 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.
    `void` | `validateConnection(PoolableConnection conn)`
    `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 Exception

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

    - #### destroyObject

          public void destroyObject(PooledObject<PoolableConnection> p)
                             throws Exception

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

    - #### getCacheState

          public boolean getCacheState()

      Returns:
        The cache state.
      Since:
        Made public in 2.6.0.

    - #### getConnectionFactory

          public ConnectionFactory getConnectionFactory()

      Returns:
        The connection factory.
      Since:
        Made public in 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:
        Made public in 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

          public Integer getDefaultQueryTimeout()

      Returns:
        Default query timeout in seconds.

    - #### getDefaultQueryTimeoutSeconds

          public Integer getDefaultQueryTimeoutSeconds()

      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.DISCONNECTION_SQL_CODES` (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

    - #### getMaxConnLifetimeMillis

          public long getMaxConnLifetimeMillis()

      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:
        Made public in 2.6.0.

    - #### getValidationQuery

          public String getValidationQuery()

      Returns:
        Validation query.
      Since:
        2.6.0

    - #### getValidationQueryTimeoutSeconds

          public int getValidationQueryTimeoutSeconds()

      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 Exception

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

    - #### passivateObject

          public void passivateObject(PooledObject<PoolableConnection> p)
                               throws Exception

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

    - #### setAutoCommitOnReturn

          public void setAutoCommitOnReturn(boolean autoCommitOnReturn)

    - #### setCacheState

          public void setCacheState(boolean cacheState)

    - #### 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(Integer defaultQueryTimeoutSeconds)

    - #### 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()`

    - #### setMaxConnLifetimeMillis

          public void setMaxConnLifetimeMillis(long maxConnLifetimeMillis)

      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)

    - #### 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

    - #### 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(int validationQueryTimeoutSeconds)

      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

      Throws:
        `SQLException`

    - #### validateObject

          public boolean validateObject(PooledObject<PoolableConnection> p)

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

Copyright © 2001–2020 The Apache Software Foundation. All rights reserved.