PooledConnection (Apache Tomcat 11.0.5 API Documentation)
Description: declaration: package: org.apache.tomcat.jdbc.pool, class: PooledConnection

# 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`