An object that provides hooks for connection pool management. A
object represents a physical connection to a data source. The connection can be recycled rather than being closed when an application is finished with it, thus reducing the number of connections that need to be made.
An application programmer does not use the
PooledConnection interface directly; rather, it is used by a middle tier infrastructure that manages the pooling of connections.
When an application calls the method
DataSource.getConnection, it gets back a
Connection object. If connection pooling is being done, that
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 there is a
PooledConnection object available in the pool, the connection pool manager returns a
Connection object that is a handle to that physical connection. If no
PooledConnection object is available, the connection pool manager calls the
getPoolConnection to create a new physical connection. The JDBC driver implementing
ConnectionPoolDataSource creates a new
PooledConnection object and returns a handle to it.
When an application closes a connection, it calls the
close. When connection pooling is being done, the connection pool manager is notified because it has registered itself as a
ConnectionEventListener object using the
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 being closed.
If the connection pool manager wraps or provides a proxy to the logical handle returned from a call to
PoolConnection.getConnection, the pool manager must do one of the following when the connection pool manager closes or returns the
PooledConnection to the pool in response to the application calling
endRequest on the logical
close on the logical
The physical connection is not closed until the connection pool manager calls the
close. This method is generally called to have an orderly shutdown of the server or if a fatal error has made the connection unusable.
A connection pool manager is often also a statement pool manager, maintaining a pool of
PreparedStatement objects. When an application closes a prepared statement, it calls the
Statement pooling is being done, the pool manager is notified because it has registered itself as a
StatementEventListener object using the
addStatementEventListener. Thus, when an application closes its
PreparedStatement, the underlying prepared statement is recycled rather than being closed.