org.apache.tomcat.jdbc.pool

## Class PooledConnection

- 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
  Author:
    Filip Hanik

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `checkUser(String username, String password)`
    `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` | `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.
    `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

          public boolean checkUser(String username,
                          String password)

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

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

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

    - #### 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()

Copyright © 2000-2016 Apache Software Foundation. All Rights Reserved.