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 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(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 Connections 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 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	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 Connections.
void	setPoolStatements(boolean poolStatements)
void	setRollbackOnReturn(boolean rollbackOnReturn)
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(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 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(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 Connections 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, not null.

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

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

Parameters:

pool - the ObjectPool in which to pool those Connections

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