PooledConnection (Apache Tomcat 9.0.0.M9 API Documentation)

java.lang.Object
- org.apache.tomcat.jdbc.pool.PooledConnection

```
public class PooledConnection
extends Object
```
Represents a pooled connection and holds a reference to the Connection object

Version:

1.0

Field Summary

Fields
Modifier and Type	Field and Description
`protected ConnectionPool`	`parent` The parent
`protected PoolConfiguration`	`poolProperties` The properties for the connection pool
`static String`	`PROP_PASSWORD`
`static 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 XAConnection`	`xaConnection` If using a XAConnection underneath.

Constructor Summary

Constructors
Constructor and Description

PooledConnection(PoolConfiguration prop, ConnectionPool parent)
Constructor

Constructors
Constructor and Description
`PooledConnection(PoolConfiguration prop, ConnectionPool parent)` Constructor

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`checkUser(String username, String password)` Deprecated. use `shouldForceReconnect(String, String)` method kept since it was public, to avoid changing interface.
`void`	`connect()` Connects the underlying connection to the database.
`protected void`	`connectUsingDataSource()`
`protected void`	`connectUsingDriver()`
`long`	`getAbandonTimeout()` Returns abandon timeout in milliseconds
`HashMap<Object,Object>`	`getAttributes()`
`Connection`	`getConnection()` Returns the underlying connection
`long`	`getConnectionVersion()`
`JdbcInterceptor`	`getHandler()` Returns the first handler in the interceptor chain
`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.
`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`	`getStackTrace()` Returns the stack trace from when this connection was borrowed.
`long`	`getTimestamp()` Return the timestamps of last pool action.
`XAConnection`	`getXAConnection()` Returns the underlying XA connection
`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`	`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 Detail
  - 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 Detail
  - PooledConnection
```
public PooledConnection(PoolConfiguration prop,
                        ConnectionPool parent)
```
    Constructor
    
    Parameters:
    
    prop - - pool properties
    
    parent - - the parent connection pool
- Method Detail
  - getConnectionVersion
```
public long getConnectionVersion()
```
  - 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()
```
    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.
    
    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()
```
  - 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[])
    
    Returns:
    
    the timestamp of the last pool action as defined by System.currentTimeMillis()
  - isDiscarded
```
public boolean isDiscarded()
```
    Returns the discarded flag.
    
    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.
    
    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).
    
    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.
    
    Returns:
    
    true if the method release() has been called
  - getAttributes
```
public HashMap<Object,Object> getAttributes()
```

Class PooledConnection

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PROP_USER

PROP_PASSWORD

VALIDATE_BORROW

VALIDATE_RETURN

VALIDATE_IDLE

VALIDATE_INIT

poolProperties

xaConnection

parent

Constructor Detail

PooledConnection

Method Detail

getConnectionVersion

checkUser

shouldForceReconnect

connect

connectUsingDataSource

connectUsingDriver

isInitialized

isMaxAgeExpired

reconnect

getAbandonTimeout

validate

validate

getReleaseTime

release

setStackTrace

getStackTrace

setTimestamp

isSuspect

setSuspect

setDiscarded

setLastValidated

setPoolProperties

getTimestamp

isDiscarded

getLastValidated

getPoolProperties

lock

unlock

getConnection

getXAConnection

getLastConnected

getHandler

setHandler

toString

isReleased

getAttributes