javax.sql.PooledConnection

javax.sql.PooledConnection is a pooled connection interface.

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 getPoolConnection method of the ConnectionPoolDataSource interface 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 close() method of the Connection object. When connection pooling is completed, the connection pool manager is notified because it has registered itself as a ConnectionEventListener object by using the addConnectionEventListener() method of the PooledConnection interface. 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 object or returns a PooledConnection object 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 close() method of the PooledConnection interface. 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 PreparedStatement object, it calls the close() method of the PreparedStatement interface. When statement pooling is completed, the pool manager is notified because it has registered itself as a StatementEventListener object by using the addStatementEventListener() method of the PooledConnection interface. Therefore, when an application closes its PreparedStatement object, the underlying prepared statement is recycled rather than closed.

Methods