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

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

Version:
  1.0

### Field Summary

Fields
`protected ConnectionPool` `parent` The parent
`protected PoolConfiguration` `poolProperties` The properties for the connection pool
`static java.lang.String` `PROP_PASSWORD`
`static java.lang.String` `PROP_USER`
`static int` `VALIDATE_BORROW` Validate when connection is borrowed flag
`static int` `VALIDATE_IDLE` Validate when connection is idle flag
`static int` `VALIDATE_INIT` Validate when connection is initialized flag
`static int` `VALIDATE_RETURN` Validate when connection is returned flag
`protected javax.sql.XAConnection` `xaConnection` If using a XAConnection underneath.

### Constructor Summary

Constructors
`PooledConnection​(PoolConfiguration prop, ConnectionPool parent)` Constructor

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`boolean` `checkUser​(java.lang.String username, java.lang.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
`java.util.HashMap<java.lang.Object,​java.lang.Object>` `getAttributes()`
`boolean` `getAutoCommit()`
`java.lang.String` `getCatalog()`
`java.sql.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.
`javax.management.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
`java.lang.String` `getSchema()`
`java.lang.String` `getStackTrace()` Returns the stack trace from when this connection was borrowed.
`long` `getTimestamp()` Return the timestamps of last pool action.
`int` `getTransactionIsolation()`
`javax.sql.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​(java.lang.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​(java.lang.String username, java.lang.String password)` Returns true if we must force reconnect based on credentials passed in.
`java.lang.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, java.lang.String sql)` Validates a connection.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### PROP_USER

    public static final java.lang.String PROP_USER

See Also:
  Constant Field Values

#### PROP_PASSWORD

    public static final java.lang.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 javax.sql.XAConnection xaConnection

If using a XAConnection underneath.

#### parent

    protected ConnectionPool parent

The parent

### Constructor Detail

#### PooledConnection

    public PooledConnection​(PoolConfiguration prop,
                            ConnectionPool parent)

Constructor

Parameters:
  `prop` - - pool properties
  `parent` - - the parent connection pool

### Method Detail

#### getConnectionVersion

    public long getConnectionVersion()

Specified by:
  `getConnectionVersion` in interface `PooledConnectionMBean`

#### checkUser

    @Deprecated
    public boolean checkUser​(java.lang.String username,
                             java.lang.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​(java.lang.String username,
                                        java.lang.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 java.sql.SQLException

Connects the underlying connection to the database.

Throws:
  `java.sql.SQLException` - if the method `release()` has been called.
  `java.sql.SQLException` - if driver instantiation fails
  `java.sql.SQLException` - if a call to `Driver.connect(String, java.util.Properties)` fails.
  `java.sql.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 java.sql.SQLException

Throws:
  `java.sql.SQLException`

#### connectUsingDriver

    protected void connectUsingDriver()
                               throws java.sql.SQLException

Throws:
  `java.sql.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 java.sql.SQLException

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

Throws:
  `java.sql.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,
                            java.lang.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​(java.lang.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 java.lang.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:
  `java.lang.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 java.sql.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 javax.sql.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 java.lang.String toString()

Overrides:
  `toString` in class `java.lang.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 java.util.HashMap<java.lang.Object,​java.lang.Object> getAttributes()

#### createMBean

    public void createMBean()

#### getObjectName

    public javax.management.ObjectName getObjectName()

#### clearWarnings

    public void clearWarnings()

Specified by:
  `clearWarnings` in interface `PooledConnectionMBean`

#### isClosed

    public boolean isClosed()
                     throws java.sql.SQLException

Specified by:
  `isClosed` in interface `PooledConnectionMBean`
Throws:
  `java.sql.SQLException`

#### getAutoCommit

    public boolean getAutoCommit()
                          throws java.sql.SQLException

Specified by:
  `getAutoCommit` in interface `PooledConnectionMBean`
Throws:
  `java.sql.SQLException`

#### getCatalog

    public java.lang.String getCatalog()
                                throws java.sql.SQLException

Specified by:
  `getCatalog` in interface `PooledConnectionMBean`
Throws:
  `java.sql.SQLException`

#### getHoldability

    public int getHoldability()
                       throws java.sql.SQLException

Specified by:
  `getHoldability` in interface `PooledConnectionMBean`
Throws:
  `java.sql.SQLException`

#### isReadOnly

    public boolean isReadOnly()
                       throws java.sql.SQLException

Specified by:
  `isReadOnly` in interface `PooledConnectionMBean`
Throws:
  `java.sql.SQLException`

#### getSchema

    public java.lang.String getSchema()
                               throws java.sql.SQLException

Specified by:
  `getSchema` in interface `PooledConnectionMBean`
Throws:
  `java.sql.SQLException`

#### getTransactionIsolation

    public int getTransactionIsolation()
                                throws java.sql.SQLException

Specified by:
  `getTransactionIsolation` in interface `PooledConnectionMBean`
Throws:
  `java.sql.SQLException`