PoolableConnectionFactory (Apache Tomcat 9.0.0.M9 API Documentation)

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

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

All Methods Instance Methods Concrete 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 Connections
- Method Detail
  - setValidationQuery
```
public void setValidationQuery(String validationQuery)
```
    Sets the query I use to validate Connections. 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 Connections.
  - 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 Connections. Using null turns off connection initialization.
    
    Parameters:
    
    connectionInitSqls - SQL statement to initialize Connections.
  - setPool
```
public void setPool(ObjectPool<PoolableConnection> pool)
```
    Sets the ObjectPool in which to pool Connections.
    
    Parameters:
    
    pool - the ObjectPool in which to pool those Connections
  - getPool
```
public ObjectPool<PoolableConnection> getPool()
```
    Returns the ObjectPool in which Connections are pooled.
    
    Returns:
    
    the connection pool
  - setDefaultReadOnly
```
public void setDefaultReadOnly(Boolean defaultReadOnly)
```
    Sets the default "read only" setting for borrowed Connections
    
    Parameters:
    
    defaultReadOnly - the default "read only" setting for borrowed Connections
  - setDefaultAutoCommit
```
public void setDefaultAutoCommit(Boolean defaultAutoCommit)
```
    Sets the default "auto commit" setting for borrowed Connections
    
    Parameters:
    
    defaultAutoCommit - the default "auto commit" setting for borrowed Connections
  - setDefaultTransactionIsolation
```
public void setDefaultTransactionIsolation(int defaultTransactionIsolation)
```
    Sets the default "Transaction Isolation" setting for borrowed Connections
    
    Parameters:
    
    defaultTransactionIsolation - the default "Transaction Isolation" setting for returned Connections
  - setDefaultCatalog
```
public void setDefaultCatalog(String defaultCatalog)
```
    Sets the default "catalog" setting for borrowed Connections
    
    Parameters:
    
    defaultCatalog - the default "catalog" setting for borrowed Connections
  - 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()
```

Class PoolableConnectionFactory

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PoolableConnectionFactory

Method Detail

setValidationQuery

setValidationQueryTimeout

setConnectionInitSql

setPool

getPool

setDefaultReadOnly

setDefaultAutoCommit

setDefaultTransactionIsolation

setDefaultCatalog

setCacheState

setPoolStatements

setMaxOpenPrepatedStatements

setMaxConnLifetimeMillis

isEnableAutoCommitOnReturn

setEnableAutoCommitOnReturn

isRollbackOnReturn

setRollbackOnReturn

getDefaultQueryTimeout

setDefaultQueryTimeout

getDisconnectionSqlCodes

setDisconnectionSqlCodes

isFastFailValidation

setFastFailValidation

makeObject

initializeConnection

destroyObject

validateObject

validateConnection

passivateObject

activateObject

getConnectionFactory

getPoolStatements

getMaxOpenPreparedStatements

getCacheState

getDataSourceJmxName

getConnectionIndex