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

  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 Details

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

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