Package org.apache.tomcat.dbcp.dbcp2

Class PoolableConnection

java.lang.Object

org.apache.tomcat.dbcp.dbcp2.AbandonedTrace

org.apache.tomcat.dbcp.dbcp2.DelegatingConnection<java.sql.Connection>

org.apache.tomcat.dbcp.dbcp2.PoolableConnection

All Implemented Interfaces:

java.lang.AutoCloseable, java.sql.Connection, java.sql.Wrapper, PoolableConnectionMXBean, TrackedUse

Direct Known Subclasses:

PoolableManagedConnection

public class PoolableConnection
extends DelegatingConnection<java.sql.Connection>
implements PoolableConnectionMXBean

A delegating connection that, rather than closing the underlying connection, returns itself to an ObjectPool when closed.

Since:

2.0

Field Summary

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Constructor Summary

Constructors

Constructor	Description
PoolableConnection(java.sql.Connection conn, ObjectPool<PoolableConnection> pool, javax.management.ObjectName jmxName)	Constructs a new instance.
PoolableConnection(java.sql.Connection conn, ObjectPool<PoolableConnection> pool, javax.management.ObjectName jmxObjectName, java.util.Collection<java.lang.String> disconnectSqlCodes, boolean fastFailValidation)	Constructs a new instance.
PoolableConnection(java.sql.Connection conn, ObjectPool<PoolableConnection> pool, javax.management.ObjectName jmxObjectName, java.util.Collection<java.lang.String> disconnectSqlCodes, java.util.Collection<java.lang.String> disconnectionIgnoreSqlCodes, boolean fastFailValidation)	Creates a new PoolableConnection instance.

Method Summary

Modifier and Type	Method	Description
void	abort(java.util.concurrent.Executor executor)	Abort my underlying Connection.
void	close()	Returns this instance to my containing pool.
java.util.Collection<java.lang.String>	getDisconnectionSqlCodes()	Gets the disconnection SQL codes.
java.lang.String	getToString()	Gets the value of the DelegatingConnection.toString() method via a bean getter, so it can be read as a property via JMX.
protected void	handleException(java.sql.SQLException e)	Handles the given exception by throwing it.
boolean	isClosed()	See Connection.isClosed().
boolean	isFastFailValidation()	Tests whether to fail-fast.
protected void	passivate()	Clears the list of objects being traced by this object.
void	reallyClose()	Closes the underlying Connection.
void	setLastUsed()	Sets the time this object was last used to the current time in milliseconds.
void	validate(java.lang.String sql, int timeoutSeconds)	Deprecated. Use validate(String, Duration).
void	validate(java.lang.String sql, java.time.Duration timeoutDuration)	Validates the connection, using the following algorithm: If fastFailValidation (constructor argument) is true and this connection has previously thrown a fatal disconnection exception, a SQLException is thrown. If sql is null, the driver's #isValid(timeout) is called.

Methods inherited from class org.apache.tomcat.dbcp.dbcp2.DelegatingConnection

activate, checkOpen, clearCachedState, clearWarnings, closeInternal, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCacheState, getCatalog, getClientInfo, getClientInfo, getDefaultQueryTimeout, getDefaultQueryTimeoutDuration, getDelegate, getDelegateInternal, getHoldability, getInnermostDelegate, getInnermostDelegateInternal, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, handleExceptionNoThrow, innermostDelegateEquals, isClosedInternal, isReadOnly, isValid, isValid, isWrapperFor, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCacheState, setCatalog, setClientInfo, setClientInfo, setClosedInternal, setDefaultQueryTimeout, setDefaultQueryTimeout, setDelegate, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap, toString, unwrap

Methods inherited from class org.apache.tomcat.dbcp.dbcp2.AbandonedTrace

addTrace, clearTrace, close, getLastUsed, getLastUsedInstant, getTrace, removeThisTrace, removeTrace, setLastUsed, setLastUsed

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.sql.Connection

beginRequest, endRequest, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid

Methods inherited from interface org.apache.tomcat.dbcp.dbcp2.PoolableConnectionMXBean

clearCachedState, clearWarnings, getAutoCommit, getCacheState, getCatalog, getHoldability, getSchema, getTransactionIsolation, isReadOnly, setAutoCommit, setCacheState, setCatalog, setHoldability, setReadOnly, setSchema, setTransactionIsolation

Constructor Detail

PoolableConnection

public PoolableConnection(java.sql.Connection conn,
                          ObjectPool<PoolableConnection> pool,
                          javax.management.ObjectName jmxName)

Constructs a new instance.

Parameters:

conn - my underlying connection

pool - the pool to which I should return when closed

jmxName - JMX name

PoolableConnection

public PoolableConnection(java.sql.Connection conn,
                          ObjectPool<PoolableConnection> pool,
                          javax.management.ObjectName jmxObjectName,
                          java.util.Collection<java.lang.String> disconnectSqlCodes,
                          boolean fastFailValidation)

Constructs a new instance.

Parameters:

conn - my underlying connection

pool - the pool to which I should return when closed

jmxObjectName - JMX name

disconnectSqlCodes - SQL State codes considered fatal disconnection errors

fastFailValidation - true means fatal disconnection errors cause subsequent validations to fail immediately (no attempt to run query or isValid)

PoolableConnection

public PoolableConnection(java.sql.Connection conn,
                          ObjectPool<PoolableConnection> pool,
                          javax.management.ObjectName jmxObjectName,
                          java.util.Collection<java.lang.String> disconnectSqlCodes,
                          java.util.Collection<java.lang.String> disconnectionIgnoreSqlCodes,
                          boolean fastFailValidation)

Creates a new PoolableConnection instance.

Parameters:

conn - my underlying connection

pool - the pool to which I should return when closed

jmxObjectName - JMX name

disconnectSqlCodes - SQL State codes considered fatal disconnection errors

disconnectionIgnoreSqlCodes - SQL State codes that should be ignored when determining fatal disconnection errors

fastFailValidation - true means fatal disconnection errors cause subsequent validations to fail immediately (no attempt to run query or isValid)

Since:

2.13.0

Method Detail

abort

public void abort(java.util.concurrent.Executor executor)
           throws java.sql.SQLException

Abort my underlying Connection.

Specified by:

abort in interface java.sql.Connection

Overrides:

abort in class DelegatingConnection<java.sql.Connection>

Throws:

java.sql.SQLException

Since:

2.9.0

close

public void close()
           throws java.sql.SQLException

Returns this instance to my containing pool.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.sql.Connection

Specified by:

close in interface PoolableConnectionMXBean

Overrides:

close in class DelegatingConnection<java.sql.Connection>

Throws:

java.sql.SQLException - Ignored here, for subclasses.

getDisconnectionSqlCodes

public java.util.Collection<java.lang.String> getDisconnectionSqlCodes()

Gets the disconnection SQL codes.

Returns:

The disconnection SQL codes.

Since:

2.6.0

getToString

public java.lang.String getToString()

Gets the value of the DelegatingConnection.toString() method via a bean getter, so it can be read as a property via JMX.

Specified by:

getToString in interface PoolableConnectionMXBean

Returns:

the value of the Object.toString().

handleException

protected void handleException(java.sql.SQLException e)
                        throws java.sql.SQLException

Description copied from class: DelegatingConnection

Handles the given exception by throwing it.

Overrides:

handleException in class DelegatingConnection<java.sql.Connection>

Parameters:

e - the exception to throw.

Throws:

java.sql.SQLException - the exception to throw.

isClosed

public boolean isClosed()
                 throws java.sql.SQLException

See Connection.isClosed().

This method should not be used by a client to determine whether or not a connection should be return to the connection pool (by calling close()). Clients should always attempt to return a connection to the pool once it is no longer required.

Specified by:

isClosed in interface java.sql.Connection

Specified by:

isClosed in interface PoolableConnectionMXBean

Overrides:

isClosed in class DelegatingConnection<java.sql.Connection>

Returns:

See Connection.isClosed().

Throws:

java.sql.SQLException - See Connection.isClosed().

isFastFailValidation

public boolean isFastFailValidation()

Tests whether to fail-fast.

Returns:

Whether to fail-fast.

Since:

2.6.0

passivate

protected void passivate()
                  throws java.sql.SQLException

Description copied from class: DelegatingConnection

Clears the list of objects being traced by this object.

Overrides:

passivate in class DelegatingConnection<java.sql.Connection>

Throws:

java.sql.SQLException - Thrown if not all traced objects were closed.

reallyClose

public void reallyClose()
                 throws java.sql.SQLException

Closes the underlying Connection.

Specified by:

reallyClose in interface PoolableConnectionMXBean

Throws:

java.sql.SQLException - Thrown if the connection can be closed.

setLastUsed

public void setLastUsed()

Description copied from class: AbandonedTrace

Sets the time this object was last used to the current time in milliseconds.

Overrides:

setLastUsed in class AbandonedTrace

validate

public void validate(java.lang.String sql,
                     java.time.Duration timeoutDuration)
              throws java.sql.SQLException

Validates the connection, using the following algorithm:

1. If fastFailValidation (constructor argument) is true and this connection has previously thrown a fatal disconnection exception, a SQLException is thrown.
2. If sql is null, the driver's #isValid(timeout) is called. If it returns false, SQLException is thrown; otherwise, this method returns successfully.
3. If sql is not null, it is executed as a query and if the resulting ResultSet contains at least one row, this method returns successfully. If not, SQLException is thrown.

Parameters:

sql - The validation SQL query.

timeoutDuration - The validation timeout in seconds.

Throws:

java.sql.SQLException - Thrown when validation fails or an SQLException occurs during validation

Since:

2.10.0

validate

@Deprecated
public void validate(java.lang.String sql,
                     int timeoutSeconds)
              throws java.sql.SQLException

Deprecated.

Use validate(String, Duration).

Validates the connection, using the following algorithm:

1. If fastFailValidation (constructor argument) is true and this connection has previously thrown a fatal disconnection exception, a SQLException is thrown.
2. If sql is null, the driver's #isValid(timeout) is called. If it returns false, SQLException is thrown; otherwise, this method returns successfully.
3. If sql is not null, it is executed as a query and if the resulting ResultSet contains at least one row, this method returns successfully. If not, SQLException is thrown.

Parameters:

sql - The validation SQL query.

timeoutSeconds - The validation timeout in seconds.

Throws:

java.sql.SQLException - Thrown when validation fails or an SQLException occurs during validation