PoolableConnectionFactory (Apache Tomcat 10.1.7 API Documentation)

Package org.apache.tomcat.dbcp.dbcp2

## Class PoolableConnectionFactory

- java.lang.Object
- - org.apache.tomcat.dbcp.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)` | Reinitializes an instance to be returned by the pool.
    `void` | `destroyObject​(PooledObject<PoolableConnection> p)` | Destroys an instance no longer needed by the pool, using the default (NORMAL) DestroyMode.
    `void` | `destroyObject​(PooledObject<PoolableConnection> p, DestroyMode mode)` | Destroys an instance no longer needed by the pool, using the provided DestroyMode.
    `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()` | Creates an instance that can be served by the pool and wrap it in a `PooledObject` to be managed by the pool.
    `void` | `passivateObject​(PooledObject<PoolableConnection> p)` | Uninitializes an instance to be returned to the idle object pool.
    `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)` | Ensures that the instance is safe to be returned by the pool.

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

      Description copied from interface: `PooledObjectFactory`
      Reinitializes an instance to be returned by the pool.
      Specified by:
        `activateObject` in interface `PooledObjectFactory<PoolableConnection>`
      Parameters:
        `p` - a `PooledObject` wrapping the instance to be activated
      Throws:
        `SQLException`
      See Also:
        `PooledObjectFactory.destroyObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>)`

    - #### destroyObject

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

      Description copied from interface: `PooledObjectFactory`
      Destroys an instance no longer needed by the pool, using the default (NORMAL) DestroyMode.

      It is important for implementations of this method to be aware that there is no guarantee about what state `obj` will be in and the implementation should be prepared to handle unexpected errors.

      Also, an implementation must take in to consideration that instances lost to the garbage collector may never be destroyed.

      Specified by:
        `destroyObject` in interface `PooledObjectFactory<PoolableConnection>`
      Parameters:
        `p` - a `PooledObject` wrapping the instance to be destroyed
      Throws:
        `SQLException`
      See Also:
        `PooledObjectFactory.validateObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>)`, `ObjectPool.invalidateObject(T)`

    - #### destroyObject

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

      Description copied from interface: `PooledObjectFactory`
      Destroys an instance no longer needed by the pool, using the provided DestroyMode.
      Specified by:
        `destroyObject` in interface `PooledObjectFactory<PoolableConnection>`
      Parameters:
        `p` - a `PooledObject` wrapping the instance to be destroyed
        `mode` - DestroyMode providing context to the factory
      Throws:
        `SQLException`
      Since:
        2.9.0
      See Also:
        `PooledObjectFactory.validateObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>)`, `ObjectPool.invalidateObject(T)`, `PooledObjectFactory.destroyObject(PooledObject)`, `DestroyMode`

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

      Description copied from interface: `PooledObjectFactory`
      Creates an instance that can be served by the pool and wrap it in a `PooledObject` to be managed by the pool.
      Specified by:
        `makeObject` in interface `PooledObjectFactory<PoolableConnection>`
      Returns:
        a `PooledObject` wrapping an instance that can be served by the pool
      Throws:
        `SQLException`

    - #### passivateObject

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

      Description copied from interface: `PooledObjectFactory`
      Uninitializes an instance to be returned to the idle object pool.
      Specified by:
        `passivateObject` in interface `PooledObjectFactory<PoolableConnection>`
      Parameters:
        `p` - a `PooledObject` wrapping the instance to be passivated
      Throws:
        `SQLException`
      See Also:
        `PooledObjectFactory.destroyObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>)`

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

      Description copied from interface: `PooledObjectFactory`
      Ensures that the instance is safe to be returned by the pool.
      Specified by:
        `validateObject` in interface `PooledObjectFactory<PoolableConnection>`
      Parameters:
        `p` - a `PooledObject` wrapping the instance to be validated
      Returns:
        `false` if `obj` is not valid and should be dropped from the pool, `true` otherwise.