javax.sql.PooledConnection

javax.sql.PooledConnection is a connection interface created by a connection pool.

Description

javax.sql.PooledConnection provides hooks for connection pool management. A PooledConnection object represents a physical connection to a data source. When an application finishes using a connection, the connection can be recycled rather than closed, thus reducing the number of connections that need to be established.

An application programmer does not directly use the PooledConnection interface. The interface is instead used by a middle-tier infrastructure that manages connection pools.

When an application calls the DataSource.getConnection method, a Connection object is returned. If connection pooling is in progress, the Connection object is actually a handle to a PooledConnection object, which is a physical connection.

The connection pool manager, typically the application server, maintains a pool of PooledConnection objects. If a PooledConnection object is available in the pool, the connection pool manager returns a Connection object that is a handle to the physical connection. If no PooledConnection object is available, the connection pool manager calls the ConnectionPoolDataSource method getPoolConnection to create a new physical connection. The JDBC driver that implements ConnectionPoolDataSource creates a new PooledConnection object and returns a handle to it.

When an application closes a connection, it calls the Connection method close(). When connection pooling is completed, the connection pool manager is notified because it has registered itself as a ConnectionEventListener object by using the ConnectionPool method addConnectionEventListener(). The connection pool manager deactivates the handle to the PooledConnection object and returns the PooledConnection object to the pool of connections so that it can be used again. Thus, when an application closes its connection, the underlying physical connection is recycled rather than closed.

For a logical handle returned by the call of PoolConnection.getConnection, if the connection pool manager packages or provides a corresponding proxy, the pool manager must execute one of the following operations to call Connection.close() when the connection pool manager closes a PooledConnection or returns a PooledConnection to the pool in response to the application:

• Call endRequest() on the logical connection handle;

• Call close() on the logical connection handle.

The physical connection is not closed until the connection pool manager calls the PooledConnection method close(). This method is generally called to orderly shut down the server or called when a fatal error has rendered the connection unusable.

A connection pool manager is often also a statement pool manager that maintains a pool of PreparedStatement objects. When an application closes a prepared statement, it calls the PreparedStatement method close(). When Statement pooling is completed, the pool manager is notified because it has registered itself as a StatementEventListener object by using the ConnectionPool method addStatementEventListener(). Therefore, when an application closes its PreparedStatement, the underlying prepared statement is recycled rather than closed.

Methods