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 java.lang.Object
implements PooledObjectFactory<PoolableConnection>

A PooledObjectFactory that creates PoolableConnections.

Since:

2.0

Constructor Summary

Constructors

Constructor	Description
PoolableConnectionFactory(ConnectionFactory connFactory, javax.management.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.
protected boolean	getCacheState()
protected ConnectionFactory	getConnectionFactory()
protected java.util.concurrent.atomic.AtomicLong	getConnectionIndex()
protected javax.management.ObjectName	getDataSourceJmxName()
java.lang.Integer	getDefaultQueryTimeout()
java.util.Collection<java.lang.String>	getDisconnectionSqlCodes()	SQL_STATE codes considered to signal fatal conditions.
protected int	getMaxOpenPreparedStatements()
ObjectPool<PoolableConnection>	getPool()	Returns the ObjectPool in which Connections are pooled.
protected boolean	getPoolStatements()
protected void	initializeConnection(java.sql.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()	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	setCacheState(boolean cacheState)
void	setConnectionInitSql(java.util.Collection<java.lang.String> connectionInitSqls)	Sets the SQL statements I use to initialize newly created Connections.
void	setDefaultAutoCommit(java.lang.Boolean defaultAutoCommit)	Sets the default "auto commit" setting for borrowed Connections
void	setDefaultCatalog(java.lang.String defaultCatalog)	Sets the default "catalog" setting for borrowed Connections
void	setDefaultQueryTimeout(java.lang.Integer defaultQueryTimeoutSeconds)
void	setDefaultReadOnly(java.lang.Boolean defaultReadOnly)	Sets the default "read only" setting for borrowed Connections
void	setDefaultSchema(java.lang.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(java.util.Collection<java.lang.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	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(java.lang.String validationQuery)	Sets the query I use to validate Connections.
void	setValidationQueryTimeout(int validationQueryTimeoutSeconds)	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,
                                 javax.management.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 Detail

setValidationQuery

public void setValidationQuery(java.lang.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 validationQueryTimeoutSeconds)

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

setConnectionInitSql

public void setConnectionInitSql(java.util.Collection<java.lang.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(java.lang.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(java.lang.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(java.lang.String defaultCatalog)

Sets the default "catalog" setting for borrowed Connections

Parameters:

defaultCatalog - the default "catalog" setting for borrowed Connections

setDefaultSchema

public void setDefaultSchema(java.lang.String defaultSchema)

Sets the default "schema" setting for borrowed Connections

Parameters:

defaultSchema - the default "schema" setting for borrowed Connections

Since:

2.5.0

setCacheState

public void setCacheState(boolean cacheState)

setPoolStatements

public void setPoolStatements(boolean poolStatements)

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.

setMaxOpenPreparedStatements

public void setMaxOpenPreparedStatements(int maxOpenPreparedStatements)

Sets the maximum number of open prepared statements.

Parameters:

maxOpenPreparedStatements - The maximum number of open prepared statements.

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 lifetime in milliseconds.

isEnableAutoCommitOnReturn

public boolean isEnableAutoCommitOnReturn()

setEnableAutoCommitOnReturn

public void setEnableAutoCommitOnReturn(boolean enableAutoCommitOnReturn)

isRollbackOnReturn

public boolean isRollbackOnReturn()

setRollbackOnReturn

public void setRollbackOnReturn(boolean rollbackOnReturn)

getDefaultQueryTimeout

public java.lang.Integer getDefaultQueryTimeout()

setDefaultQueryTimeout

public void setDefaultQueryTimeout(java.lang.Integer defaultQueryTimeoutSeconds)

getDisconnectionSqlCodes

public java.util.Collection<java.lang.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(java.util.Collection<java.lang.String> disconnectionSqlCodes)

Parameters:

disconnectionSqlCodes - The disconnection SQL 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, 2.5.0 Defaults to true, previous versions defaulted to false.

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 java.lang.Exception

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:

java.lang.Exception - if there is a problem creating a new instance, this will be propagated to the code requesting an object.

initializeConnection

protected void initializeConnection(java.sql.Connection conn)
                             throws java.sql.SQLException

Throws:

java.sql.SQLException

destroyObject

public void destroyObject(PooledObject<PoolableConnection> p)
                   throws java.lang.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:

java.lang.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 java.sql.SQLException

Throws:

java.sql.SQLException

passivateObject

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

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:

java.lang.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 java.lang.Exception

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:

java.lang.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 javax.management.ObjectName getDataSourceJmxName()

getConnectionIndex

protected java.util.concurrent.atomic.AtomicLong getConnectionIndex()