Package org.apache.tomcat.jdbc.pool

Class PooledConnection

java.lang.Object

org.apache.tomcat.jdbc.pool.PooledConnection

All Implemented Interfaces:

PooledConnectionMBean

public class PooledConnection
extends Object
implements PooledConnectionMBean

Represents a pooled connection and holds a reference to the Connection object

Field Summary

Fields

Modifier and Type	Field	Description
protected ConnectionPool	parent	The parent
protected PoolConfiguration	poolProperties	The properties for the connection pool
static final String	PROP_PASSWORD
static final String	PROP_USER
static final int	VALIDATE_BORROW	Validate when connection is borrowed flag
static final int	VALIDATE_IDLE	Validate when connection is idle flag
static final int	VALIDATE_INIT	Validate when connection is initialized flag
static final int	VALIDATE_RETURN	Validate when connection is returned flag
protected XAConnection	xaConnection	If using a XAConnection underneath.

Constructor Summary

Constructors

Constructor	Description
PooledConnection(PoolConfiguration prop, ConnectionPool parent)	Constructor

Method Summary

Modifier and Type	Method	Description
boolean	checkUser(String username, String password)	Deprecated. use shouldForceReconnect(String, String) method kept since it was public, to avoid changing interface.
void	clearWarnings()
void	connect()	Connects the underlying connection to the database.
protected void	connectUsingDataSource()
protected void	connectUsingDriver()
void	createMBean()
long	getAbandonTimeout()	Returns abandon timeout in milliseconds
HashMap<Object,Object>	getAttributes()
boolean	getAutoCommit()
String	getCatalog()
Connection	getConnection()	Returns the underlying connection
long	getConnectionVersion()
JdbcInterceptor	getHandler()	Returns the first handler in the interceptor chain
int	getHoldability()
long	getLastConnected()	Returns the timestamp of when the connection was last connected to the database.
long	getLastValidated()	Returns the timestamp of the last successful validation query execution.
ObjectName	getObjectName()
PoolConfiguration	getPoolProperties()	Returns the configuration for this connection and pool
long	getReleaseTime()	The time limit for how long the object can remain unused before it is released
String	getSchema()
String	getStackTrace()	Returns the stack trace from when this connection was borrowed.
long	getTimestamp()	Return the timestamps of last pool action.
int	getTransactionIsolation()
XAConnection	getXAConnection()	Returns the underlying XA connection
boolean	isClosed()
boolean	isDiscarded()	Returns the discarded flag.
boolean	isInitialized()
boolean	isMaxAgeExpired()	Returns true if the connection has been connected more than PoolConfiguration.getMaxAge() milliseconds. false otherwise.
boolean	isReadOnly()
boolean	isReleased()	Returns true if this connection has been released and wont be reused.
boolean	isSuspect()
void	lock()	Locks the connection only if either PoolConfiguration.isPoolSweeperEnabled() or PoolConfiguration.getUseLock() return true.
void	reconnect()	Issues a call to disconnect(boolean) with the argument false followed by a call to connect()
boolean	release()	This method is called if (Now - timeCheckedIn > getReleaseTime()) This method disconnects the connection, logs an error in debug mode if it happens then sets the released flag to false.
void	setDiscarded(boolean discarded)	An interceptor can call this method with the value true, and the connection will be closed when it is returned to the pool.
void	setHandler(JdbcInterceptor handler)
void	setLastValidated(long lastValidated)	Set the timestamp the connection was last validated.
void	setPoolProperties(PoolConfiguration poolProperties)	Sets the pool configuration for this connection and connection pool.
void	setStackTrace(String trace)	The pool will set the stack trace when it is check out and checked in
void	setSuspect(boolean suspect)
void	setTimestamp(long timestamp)	Sets a timestamp on this connection.
boolean	shouldForceReconnect(String username, String password)	Returns true if we must force reconnect based on credentials passed in.
String	toString()
void	unlock()	Unlocks the connection only if the sweeper is enabled Otherwise this is a noop for performance
boolean	validate(int validateAction)	Returns true if the object is still valid. if not the pool will call the getExpiredAction() and follow up with one of the four expired methods
boolean	validate(int validateAction, String sql)	Validates a connection.

Methods inherited from class java.lang.Object

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

Field Details

PROP_USER

public static final String PROP_USER

See Also:

• Constant Field Values

PROP_PASSWORD

public static final String PROP_PASSWORD

See Also:

• Constant Field Values

VALIDATE_BORROW

public static final int VALIDATE_BORROW

Validate when connection is borrowed flag

See Also:

• Constant Field Values

VALIDATE_RETURN

public static final int VALIDATE_RETURN

Validate when connection is returned flag

See Also:

• Constant Field Values

VALIDATE_IDLE

public static final int VALIDATE_IDLE

Validate when connection is idle flag

See Also:

• Constant Field Values

VALIDATE_INIT

public static final int VALIDATE_INIT

Validate when connection is initialized flag

See Also:

• Constant Field Values

poolProperties

protected PoolConfiguration poolProperties

The properties for the connection pool

xaConnection

protected volatile XAConnection xaConnection

If using a XAConnection underneath.

parent

protected ConnectionPool parent

The parent

Constructor Details

PooledConnection

public PooledConnection(PoolConfiguration prop,
 ConnectionPool parent)

Constructor

Parameters:

prop - - pool properties

parent - - the parent connection pool

Method Details

getConnectionVersion

public long getConnectionVersion()

Specified by:

getConnectionVersion in interface PooledConnectionMBean

checkUser

@Deprecated
public boolean checkUser(String username,
 String password)

Deprecated.

use shouldForceReconnect(String, String) method kept since it was public, to avoid changing interface.

Parameters:

username - The user name

password - The password

Returns:

trueif the pool does not need to reconnect

shouldForceReconnect

public boolean shouldForceReconnect(String username,
 String password)

Returns true if we must force reconnect based on credentials passed in. Returns false if PoolConfiguration.isAlternateUsernameAllowed() method returns false. Returns false if the username/password has not changed since this connection was connected

Parameters:

username - the username you wish to connect with, pass in null to accept the default username from PoolConfiguration.getUsername()

password - the password you wish to connect with, pass in null to accept the default username from PoolConfiguration.getPassword()

Returns:

true is the pool must reconnect

connect

public void connect()
             throws SQLException

Connects the underlying connection to the database.

Throws:

SQLException - if the method release() has been called.

SQLException - if driver instantiation fails

SQLException - if a call to Driver.connect(String, java.util.Properties) fails.

SQLException - if default properties are configured and a call to Connection.setAutoCommit(boolean), Connection.setCatalog(String), Connection.setTransactionIsolation(int) or Connection.setReadOnly(boolean) fails.

connectUsingDataSource

protected void connectUsingDataSource()
                               throws SQLException

Throws:

SQLException

connectUsingDriver

protected void connectUsingDriver()
                           throws SQLException

Throws:

SQLException

isInitialized

public boolean isInitialized()

Specified by:

isInitialized in interface PooledConnectionMBean

Returns:

true if connect() was called successfully and disconnect has not yet been called

isMaxAgeExpired

public boolean isMaxAgeExpired()

Returns true if the connection has been connected more than PoolConfiguration.getMaxAge() milliseconds. false otherwise.

Specified by:

isMaxAgeExpired in interface PooledConnectionMBean

Returns:

Returns true if the connection has been connected more than PoolConfiguration.getMaxAge() milliseconds. false otherwise.

reconnect

public void reconnect()
               throws SQLException

Issues a call to disconnect(boolean) with the argument false followed by a call to connect()

Throws:

SQLException - if the call to connect() fails.

getAbandonTimeout

public long getAbandonTimeout()

Returns abandon timeout in milliseconds

Returns:

abandon timeout in milliseconds

validate

public boolean validate(int validateAction)

Returns true if the object is still valid. if not the pool will call the getExpiredAction() and follow up with one of the four expired methods

Parameters:

validateAction - The value

Returns:

true if the connection is valid

validate

public boolean validate(int validateAction,
 String sql)

Validates a connection.

Parameters:

validateAction - the action used. One of VALIDATE_BORROW, VALIDATE_IDLE, VALIDATE_INIT or VALIDATE_RETURN

sql - the SQL to be used during validation. If the PoolConfiguration.setInitSQL(String) has been called with a non null value and the action is VALIDATE_INIT the init SQL will be used for validation.

Returns:

true if the connection was validated successfully. It returns true even if validation was not performed, such as when PoolConfiguration.setValidationInterval(long) has been called with a positive value.

false if the validation failed. The caller should close the connection if false is returned since a session could have been left in an unknown state during initialization.

getReleaseTime

public long getReleaseTime()

The time limit for how long the object can remain unused before it is released

Returns:

PoolConfiguration.getMinEvictableIdleTimeMillis()

release

public boolean release()

This method is called if (Now - timeCheckedIn > getReleaseTime()) This method disconnects the connection, logs an error in debug mode if it happens then sets the released flag to false. Any attempts to connect this cached object again will fail per connect() The connection pool uses the atomic return value to decrement the pool size counter.

Returns:

true if this is the first time this method has been called. false if this method has been called before.

setStackTrace

public void setStackTrace(String trace)

The pool will set the stack trace when it is check out and checked in

Parameters:

trace - the stack trace for this connection

getStackTrace

public String getStackTrace()

Returns the stack trace from when this connection was borrowed. Can return null if no stack trace was set.

Returns:

the stack trace or null of no trace was set

setTimestamp

public void setTimestamp(long timestamp)

Sets a timestamp on this connection. A timestamp usually means that some operation performed successfully.

Parameters:

timestamp - the timestamp as defined by System.currentTimeMillis()

isSuspect

public boolean isSuspect()

Specified by:

isSuspect in interface PooledConnectionMBean

setSuspect

public void setSuspect(boolean suspect)

setDiscarded

public void setDiscarded(boolean discarded)

An interceptor can call this method with the value true, and the connection will be closed when it is returned to the pool.

Parameters:

discarded - - only valid value is true

Throws:

IllegalStateException - if this method is called with the value false and the value true has already been set.

setLastValidated

public void setLastValidated(long lastValidated)

Set the timestamp the connection was last validated. This flag is used to keep track when we are using a validation-interval.

Parameters:

lastValidated - a timestamp as defined by System.currentTimeMillis()

setPoolProperties

public void setPoolProperties(PoolConfiguration poolProperties)

Sets the pool configuration for this connection and connection pool. Object is shared with the ConnectionPool

Parameters:

poolProperties - The pool properties

getTimestamp

public long getTimestamp()

Return the timestamps of last pool action. Timestamps are typically set when connections are borrowed from the pool. It is used to keep track of abandon-timeouts. This timestamp can also be reset by the ResetAbandonedTimer.invoke(Object, java.lang.reflect.Method, Object[])

Specified by:

getTimestamp in interface PooledConnectionMBean

Returns:

the timestamp of the last pool action as defined by System.currentTimeMillis()

isDiscarded

public boolean isDiscarded()

Returns the discarded flag.

Specified by:

isDiscarded in interface PooledConnectionMBean

Returns:

the discarded flag. If the value is true, either disconnect(boolean) has been called or it will be called when the connection is returned to the pool.

getLastValidated

public long getLastValidated()

Returns the timestamp of the last successful validation query execution.

Specified by:

getLastValidated in interface PooledConnectionMBean

Returns:

the timestamp of the last successful validation query execution as defined by System.currentTimeMillis()

getPoolProperties

public PoolConfiguration getPoolProperties()

Returns the configuration for this connection and pool

Returns:

the configuration for this connection and pool

lock

public void lock()

Locks the connection only if either PoolConfiguration.isPoolSweeperEnabled() or PoolConfiguration.getUseLock() return true. The per connection lock ensures thread safety is multiple threads are performing operations on the connection. Otherwise this is a noop for performance

unlock

public void unlock()

Unlocks the connection only if the sweeper is enabled Otherwise this is a noop for performance

getConnection

public Connection getConnection()

Returns the underlying connection

Returns:

the underlying JDBC connection as it was returned from the JDBC driver

See Also:

• PooledConnection.getConnection()

getXAConnection

public XAConnection getXAConnection()

Returns the underlying XA connection

Returns:

the underlying XA connection as it was returned from the Datasource

getLastConnected

public long getLastConnected()

Returns the timestamp of when the connection was last connected to the database. ie, a successful call to Driver.connect(String, java.util.Properties).

Specified by:

getLastConnected in interface PooledConnectionMBean

Returns:

the timestamp when this connection was created as defined by System.currentTimeMillis()

getHandler

public JdbcInterceptor getHandler()

Returns the first handler in the interceptor chain

Returns:

the first interceptor for this connection

setHandler

public void setHandler(JdbcInterceptor handler)

toString

public String toString()

Overrides:

toString in class Object

isReleased

public boolean isReleased()

Returns true if this connection has been released and wont be reused.

Specified by:

isReleased in interface PooledConnectionMBean

Returns:

true if the method release() has been called

getAttributes

public HashMap<Object,Object> getAttributes()

createMBean

public void createMBean()

getObjectName

public ObjectName getObjectName()

clearWarnings

public void clearWarnings()

Specified by:

clearWarnings in interface PooledConnectionMBean

isClosed

public boolean isClosed()
                 throws SQLException

Specified by:

isClosed in interface PooledConnectionMBean

Throws:

SQLException

getAutoCommit

public boolean getAutoCommit()
                      throws SQLException

Specified by:

getAutoCommit in interface PooledConnectionMBean

Throws:

SQLException

getCatalog

public String getCatalog()
                  throws SQLException

Specified by:

getCatalog in interface PooledConnectionMBean

Throws:

SQLException

getHoldability

public int getHoldability()
                   throws SQLException

Specified by:

getHoldability in interface PooledConnectionMBean

Throws:

SQLException

isReadOnly

public boolean isReadOnly()
                   throws SQLException

Specified by:

isReadOnly in interface PooledConnectionMBean

Throws:

SQLException

getSchema

public String getSchema()
                 throws SQLException

Specified by:

getSchema in interface PooledConnectionMBean

Throws:

SQLException

getTransactionIsolation

public int getTransactionIsolation()
                            throws SQLException

Specified by:

getTransactionIsolation in interface PooledConnectionMBean

Throws:

SQLException