Class PoolableConnectionFactory

java.lang.Object

org.apache.commons.dbcp2.PoolableConnectionFactory

All Implemented Interfaces:

org.apache.commons.pool2.PooledObjectFactory<PoolableConnection>

Direct Known Subclasses:

PoolableManagedConnectionFactory

public class PoolableConnectionFactory
extends Object
implements org.apache.commons.pool2.PooledObjectFactory<PoolableConnection>

A PooledObjectFactory that creates PoolableConnections.

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(org.apache.commons.pool2.PooledObject<PoolableConnection> p)
void	destroyObject(org.apache.commons.pool2.PooledObject<PoolableConnection> p)
void	destroyObject(org.apache.commons.pool2.PooledObject<PoolableConnection> p, org.apache.commons.pool2.DestroyMode mode)
boolean	getCacheState()	Gets the cache state to propagate in makeObject().
ConnectionFactory	getConnectionFactory()	Gets the connection factory.
protected AtomicLong	getConnectionIndex()	Gets how many connections were created in makeObject().
Collection<String>	getConnectionInitSqls()	Gets the collection of initialization SQL statements.
ObjectName	getDataSourceJmxName()	Gets data source JMX ObjectName.
ObjectName	getDataSourceJmxObjectName()	Gets the data source JMX ObjectName.
Boolean	getDefaultAutoCommit()	Gets the Default auto-commit value.
String	getDefaultCatalog()	Gets the default catalog.
Integer	getDefaultQueryTimeout()	Deprecated. Use getDefaultQueryTimeoutDuration().
Duration	getDefaultQueryTimeoutDuration()	Gets the default query timeout Duration.
Integer	getDefaultQueryTimeoutSeconds()	Deprecated. Use getDefaultQueryTimeoutDuration().
Boolean	getDefaultReadOnly()	Gets the default read-only-value.
String	getDefaultSchema()	Gets the default schema.
int	getDefaultTransactionIsolation()	Gets the default transaction isolation.
Collection<String>	getDisconnectionIgnoreSqlCodes()	Gets the collection of SQL State codes that are not considered fatal disconnection codes.
Collection<String>	getDisconnectionSqlCodes()	Gets 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()	Gets the maximum number of open prepared statements.
org.apache.commons.pool2.ObjectPool<PoolableConnection>	getPool()	Returns the ObjectPool in which Connections are pooled.
boolean	getPoolStatements()	Tests whether to pool statements.
String	getValidationQuery()	Gets the validation query.
Duration	getValidationQueryTimeoutDuration()	Gets the query timeout in seconds.
int	getValidationQueryTimeoutSeconds()	Deprecated. Use getValidationQueryTimeoutDuration().
protected void	initializeConnection(Connection conn)	Initializes the given connection with the collection of SQL statements set in setConnectionInitSql(Collection).
boolean	isAutoCommitOnReturn()	Tests whether to set auto-commit on passivateObject(PooledObject).
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()	Tests whether to rollback on return.
org.apache.commons.pool2.PooledObject<PoolableConnection>	makeObject()
void	passivateObject(org.apache.commons.pool2.PooledObject<PoolableConnection> p)
void	setAutoCommitOnReturn(boolean autoCommitOnReturn)	Sets whether to set auto-commit on passivateObject(PooledObject).
void	setCacheState(boolean cacheState)	Sets the cache state to propagate in makeObject().
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 Connections.
void	setDefaultAutoCommit(Boolean defaultAutoCommit)	Sets the default "auto commit" setting for borrowed Connections
void	setDefaultCatalog(String defaultCatalog)	Sets the default "catalog" setting for borrowed Connections
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 Connections
void	setDefaultSchema(String defaultSchema)	Sets the default "schema" setting for borrowed Connections
void	setDefaultTransactionIsolation(int defaultTransactionIsolation)	Sets the default "Transaction Isolation" setting for borrowed Connections
void	setDisconnectionIgnoreSqlCodes(Collection<String> disconnectionIgnoreSqlCodes)	Sets the disconnection SQL codes to ignore.
void	setDisconnectionSqlCodes(Collection<String> disconnectionSqlCodes)	Sets the disconnection SQL codes.
void	setEnableAutoCommitOnReturn(boolean autoCommitOnReturn)	Deprecated.
void	setFastFailValidation(boolean fastFailValidation)	Sets whether connections created by this factory will fast fail validation.
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(org.apache.commons.pool2.ObjectPool<PoolableConnection> pool)	Sets the ObjectPool in which to pool Connections.
void	setPoolStatements(boolean poolStatements)	Sets whether to pool statements.
void	setRollbackOnReturn(boolean rollbackOnReturn)	Sets whether to rollback on return.
void	setValidationQuery(String validationQuery)	Sets the query I use to validate Connections.
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(org.apache.commons.pool2.PooledObject<PoolableConnection> p)

Methods inherited from class 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 Connections

dataSourceJmxObjectName - The JMX object name, may be null.

Method Details

activateObject

public void activateObject(org.apache.commons.pool2.PooledObject<PoolableConnection> p)
                    throws SQLException

Specified by:

activateObject in interface org.apache.commons.pool2.PooledObjectFactory<PoolableConnection>

Throws:

SQLException

destroyObject

public void destroyObject(org.apache.commons.pool2.PooledObject<PoolableConnection> p)
                   throws SQLException

Specified by:

destroyObject in interface org.apache.commons.pool2.PooledObjectFactory<PoolableConnection>

Throws:

SQLException

destroyObject

public void destroyObject(org.apache.commons.pool2.PooledObject<PoolableConnection> p,
 org.apache.commons.pool2.DestroyMode mode)
                   throws SQLException

Specified by:

destroyObject in interface org.apache.commons.pool2.PooledObjectFactory<PoolableConnection>

Throws:

SQLException

Since:

2.9.0

getCacheState

public boolean getCacheState()

Gets the cache state to propagate in makeObject().

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

Gets how many connections were created in makeObject().

Returns:

the connection count.

getConnectionInitSqls

public Collection<String> getConnectionInitSqls()

Gets the collection of initialization SQL statements.

Returns:

The collection of initialization SQL statements.

Since:

2.6.0

getDataSourceJmxName

public ObjectName getDataSourceJmxName()

Gets data source JMX ObjectName.

Returns:

The data source JMX ObjectName.

Since:

2.6.0.

getDataSourceJmxObjectName

public ObjectName getDataSourceJmxObjectName()

Gets the data source JMX ObjectName.

Returns:

The data source JMX ObjectName.

Since:

2.6.0

getDefaultAutoCommit

public Boolean getDefaultAutoCommit()

Gets the Default auto-commit value.

Returns:

The default auto-commit value.

Since:

2.6.0

getDefaultCatalog

public String getDefaultCatalog()

Gets the default catalog.

Returns:

The default catalog.

Since:

2.6.0

getDefaultQueryTimeout

@Deprecated
public Integer getDefaultQueryTimeout()

Deprecated.

Use getDefaultQueryTimeoutDuration().

Gets the default query timeout in seconds.

Returns:

The default query timeout in seconds.

getDefaultQueryTimeoutDuration

public Duration getDefaultQueryTimeoutDuration()

Gets the default query timeout Duration.

Returns:

The default query timeout Duration.

Since:

2.10.0

getDefaultQueryTimeoutSeconds

@Deprecated
public Integer getDefaultQueryTimeoutSeconds()

Deprecated.

Use getDefaultQueryTimeoutDuration().

Gets the default query timeout in seconds.

Returns:

The default query timeout in seconds.

Since:

2.6.0

getDefaultReadOnly

public Boolean getDefaultReadOnly()

Gets the default read-only-value.

Returns:

The default read-only-value.

Since:

2.6.0

getDefaultSchema

public String getDefaultSchema()

Gets the default schema.

Returns:

The default schema.

Since:

2.6.0

getDefaultTransactionIsolation

public int getDefaultTransactionIsolation()

Gets the default transaction isolation.

Returns:

The default transaction isolation.

Since:

2.6.0

getDisconnectionIgnoreSqlCodes

public Collection<String> getDisconnectionIgnoreSqlCodes()

Gets the collection of SQL State codes that are not considered fatal disconnection codes.

This method returns the collection of SQL State codes that have been set to be ignored when determining if a SQLException signals a disconnection. These codes are excluded from being treated as fatal even if they match the typical disconnection criteria.

Returns:

a Collection of SQL State codes that should be ignored for disconnection checks.

Since:

2.13.0

getDisconnectionSqlCodes

public Collection<String> getDisconnectionSqlCodes()

Gets 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()

Gets the maximum number of open prepared statements.

Returns:

The maximum number of open prepared statements.

getPool

public org.apache.commons.pool2.ObjectPool<PoolableConnection> getPool()

Returns the ObjectPool in which Connections are pooled.

Returns:

the connection pool

getPoolStatements

public boolean getPoolStatements()

Tests whether to pool statements.

Returns:

Whether to pool statements.

Since:

2.6.0.

getValidationQuery

public String getValidationQuery()

Gets the validation query.

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

Initializes the given connection with the collection of SQL statements set in setConnectionInitSql(Collection).

Parameters:

conn - the connection to initialize.

Throws:

SQLException - if a database access error occurs or this method is called on a closed connection.

See Also:

• setConnectionInitSql(Collection)

isAutoCommitOnReturn

public boolean isAutoCommitOnReturn()

Tests whether to set auto-commit on passivateObject(PooledObject).

Returns:

Whether to set auto-commit on passivateObject(PooledObject).

Since:

2.6.0

isEnableAutoCommitOnReturn

@Deprecated
public boolean isEnableAutoCommitOnReturn()

Deprecated.

Use isAutoCommitOnReturn().

Tests whether to set auto-commit on passivateObject(PooledObject).

Returns:

Whether to set auto-commit on passivateObject(PooledObject).

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

Tests whether to rollback on return.

Returns:

Whether to rollback on return.

makeObject

public org.apache.commons.pool2.PooledObject<PoolableConnection> makeObject()
                                                                     throws SQLException

Specified by:

makeObject in interface org.apache.commons.pool2.PooledObjectFactory<PoolableConnection>

Throws:

SQLException

passivateObject

public void passivateObject(org.apache.commons.pool2.PooledObject<PoolableConnection> p)
                     throws SQLException

Specified by:

passivateObject in interface org.apache.commons.pool2.PooledObjectFactory<PoolableConnection>

Throws:

SQLException

setAutoCommitOnReturn

public void setAutoCommitOnReturn(boolean autoCommitOnReturn)

Sets whether to set auto-commit on passivateObject(PooledObject).

Parameters:

autoCommitOnReturn - whether to set auto-commit.

setCacheState

public void setCacheState(boolean cacheState)

Sets the cache state to propagate in makeObject().

Parameters:

cacheState - the cache state to propagate.

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 Connections. Using null turns off connection initialization.

Parameters:

connectionInitSqls - SQL statement to initialize 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

setDefaultCatalog

public void setDefaultCatalog(String defaultCatalog)

Sets the default "catalog" setting for borrowed Connections

Parameters:

defaultCatalog - the default "catalog" setting for borrowed Connections

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 Connections

Parameters:

defaultReadOnly - the default "read only" setting for borrowed Connections

setDefaultSchema

public void setDefaultSchema(String defaultSchema)

Sets the default "schema" setting for borrowed Connections

Parameters:

defaultSchema - the default "schema" setting for borrowed Connections

Since:

2.5.0

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

setDisconnectionIgnoreSqlCodes

public void setDisconnectionIgnoreSqlCodes(Collection<String> disconnectionIgnoreSqlCodes)

Sets the disconnection SQL codes to ignore.

Parameters:

disconnectionIgnoreSqlCodes - The collection of SQL State codes to be ignored.

Throws:

IllegalArgumentException - if any SQL state codes overlap with those in disconnectionSqlCodes.

Since:

2.13.0

See Also:

• getDisconnectionIgnoreSqlCodes()

setDisconnectionSqlCodes

public void setDisconnectionSqlCodes(Collection<String> disconnectionSqlCodes)

Sets the disconnection SQL codes.

Parameters:

disconnectionSqlCodes - The disconnection SQL codes.

Throws:

IllegalArgumentException - if any SQL state codes overlap with those in disconnectionIgnoreSqlCodes.

Since:

2.1

See Also:

• getDisconnectionSqlCodes()

setEnableAutoCommitOnReturn

@Deprecated
public void setEnableAutoCommitOnReturn(boolean autoCommitOnReturn)

Deprecated.

Sets whether to set auto-commit on passivateObject(PooledObject).

Parameters:

autoCommitOnReturn - whether to set auto-commit.

setFastFailValidation

public void setFastFailValidation(boolean fastFailValidation)

Sets whether connections created by this factory will fast fail validation.

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(org.apache.commons.pool2.ObjectPool<PoolableConnection> pool)

Sets the ObjectPool in which to pool Connections.

Parameters:

pool - the ObjectPool in which to pool those Connections

setPoolStatements

public void setPoolStatements(boolean poolStatements)

Sets whether to pool statements.

Parameters:

poolStatements - whether to pool statements.

setRollbackOnReturn

public void setRollbackOnReturn(boolean rollbackOnReturn)

Sets whether to rollback on return.

Parameters:

rollbackOnReturn - whether to rollback on return.

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(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(org.apache.commons.pool2.PooledObject<PoolableConnection> p)

Specified by:

validateObject in interface org.apache.commons.pool2.PooledObjectFactory<PoolableConnection>