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:
  `true`if 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`