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 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 | Description
    --- | ---
    `PooledConnection​(PoolConfiguration prop, ConnectionPool parent)` | Constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    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 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()

      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`