org.apache.tomcat.dbcp.dbcp2

## Class PoolableConnectionFactory

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp2.PoolableConnectionFactory

- All Implemented Interfaces:
    PooledObjectFactory<PoolableConnection>

      public class PoolableConnectionFactory
      extends Object
      implements PooledObjectFactory<PoolableConnection>

  A `PooledObjectFactory` that creates `PoolableConnection`s.
  Since:
    2.0
  Author:
    Rodney Waldhoff, Glenn L. Nielsen, James House, Dirk Verbeeck

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PoolableConnectionFactory(ConnectionFactory connFactory, ObjectName dataSourceJmxName)` Create a new `PoolableConnectionFactory`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `activateObject(PooledObject<PoolableConnection> p)` Reinitialize an instance to be returned by the pool.
    `void` | `destroyObject(PooledObject<PoolableConnection> p)` Destroys an instance no longer needed by the pool.
    `protected boolean` | `getCacheState()`
    `protected ConnectionFactory` | `getConnectionFactory()`
    `protected AtomicLong` | `getConnectionIndex()`
    `protected ObjectName` | `getDataSourceJmxName()`
    `Integer` | `getDefaultQueryTimeout()`
    `Collection<String>` | `getDisconnectionSqlCodes()` SQL_STATE codes considered to signal fatal conditions.
    `protected int` | `getMaxOpenPreparedStatements()`
    `ObjectPool<PoolableConnection>` | `getPool()` Returns the `ObjectPool` in which `Connection`s are pooled.
    `protected boolean` | `getPoolStatements()`
    `protected void` | `initializeConnection(Connection conn)`
    `boolean` | `isEnableAutoCommitOnReturn()`
    `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()` Create 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)` Uninitialize an instance to be returned to the idle object pool.
    `void` | `setCacheState(boolean cacheState)`
    `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 defaultQueryTimeout)`
    `void` | `setDefaultReadOnly(Boolean defaultReadOnly)` Sets the default "read only" 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 enableAutoCommitOnReturn)`
    `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` | `setMaxOpenPrepatedStatements(int maxOpenPreparedStatements)`
    `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 timeout)` 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)` 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 dataSourceJmxName)

      Create a new `PoolableConnectionFactory`.
      Parameters:
        `connFactory` - the `ConnectionFactory` from which to obtain
        `dataSourceJmxName` - The JMX name base `Connection`s

  - ### Method Detail

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

      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:
        `timeout` - new validation query timeout value in seconds

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

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

    - #### getPool

          public ObjectPool<PoolableConnection> getPool()

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

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

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

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

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

    - #### setCacheState

          public void setCacheState(boolean cacheState)

    - #### setPoolStatements

          public void setPoolStatements(boolean poolStatements)

    - #### setMaxOpenPrepatedStatements

          public void setMaxOpenPrepatedStatements(int maxOpenPreparedStatements)

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

    - #### isEnableAutoCommitOnReturn

          public boolean isEnableAutoCommitOnReturn()

    - #### setEnableAutoCommitOnReturn

          public void setEnableAutoCommitOnReturn(boolean enableAutoCommitOnReturn)

    - #### isRollbackOnReturn

          public boolean isRollbackOnReturn()

    - #### setRollbackOnReturn

          public void setRollbackOnReturn(boolean rollbackOnReturn)

    - #### getDefaultQueryTimeout

          public Integer getDefaultQueryTimeout()

    - #### setDefaultQueryTimeout

          public void setDefaultQueryTimeout(Integer defaultQueryTimeout)

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

    - #### setDisconnectionSqlCodes

          public void setDisconnectionSqlCodes(Collection<String> disconnectionSqlCodes)

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

    - #### 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
      See Also:
        `setDisconnectionSqlCodes(Collection)`

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

    - #### makeObject

          public PooledObject<PoolableConnection> makeObject()
                                                      throws Exception

      Description copied from interface: `PooledObjectFactory`
      Create 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:
        `Exception` - if there is a problem creating a new instance, this will be propagated to the code requesting an object.

    - #### initializeConnection

          protected void initializeConnection(Connection conn)
                                       throws SQLException

      Throws:
        `SQLException`

    - #### destroyObject

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

      Description copied from interface: `PooledObjectFactory`
      Destroys an instance no longer needed by the pool.

      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:
        `Exception` - should be avoided as it may be swallowed by the pool implementation.
      See Also:
        `PooledObjectFactory.validateObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>)`, `ObjectPool.invalidateObject(T)`

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

    - #### validateConnection

          public void validateConnection(PoolableConnection conn)
                                  throws SQLException

      Throws:
        `SQLException`

    - #### passivateObject

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

      Description copied from interface: `PooledObjectFactory`
      Uninitialize 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:
        `Exception` - if there is a problem passivating `obj`, this exception may be swallowed by the pool.
      See Also:
        `PooledObjectFactory.destroyObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>)`

    - #### activateObject

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

      Description copied from interface: `PooledObjectFactory`
      Reinitialize 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:
        `Exception` - if there is a problem activating `obj`, this exception may be swallowed by the pool.
      See Also:
        `PooledObjectFactory.destroyObject(org.apache.tomcat.dbcp.pool2.PooledObject<T>)`

    - #### getConnectionFactory

          protected ConnectionFactory getConnectionFactory()

    - #### getPoolStatements

          protected boolean getPoolStatements()

    - #### getMaxOpenPreparedStatements

          protected int getMaxOpenPreparedStatements()

    - #### getCacheState

          protected boolean getCacheState()

    - #### getDataSourceJmxName

          protected ObjectName getDataSourceJmxName()

    - #### getConnectionIndex

          protected AtomicLong getConnectionIndex()

Copyright © 2000-2017 Apache Software Foundation. All Rights Reserved.