| An interface which provides facilities for handling connections to a database
which are pooled.
Typically, a {@code PooledConnection} is recycled when it is no longer
required by an application, rather than being closed and discarded. The
reason for treating connections in this way is that it can be an expensive
process both to establish a connection to a database and to destroy the
connection. Reusing connections through a pool is a way of improving system
performance and reducing overhead.
It is not intended that an application uses the {@code PooledConnection}
interface directly. The {@code PooledConnection} interface is intended for
use by a component called a connection pool manager, typically part of the
infrastructure that supports use of the database by applications.
Applications obtain connections to the database by calling the
{@link DataSource#getConnection} method. Behind the scenes, the connection
pool manager will get a {@code PooledConnection} object from its connection
pool and passes back a connection object that wraps or references the {@code
PooledConnection} object. A new {@code PooledConnection} object will only be
created if the pool is empty.
When the application is finished using a {@code PooledConnection}, the
application calls the {@link Connection#close} method. The connection pool
manager is notified via a {@link ConnectionEvent} from the connection that
this has happened (the pool manager registers itself with the connection
before the connection is given to the application). The pool manager removes
the underlying {@code PooledConnection} object from the connection and
returns it to the pool for reuse - the {@code PooledConnection} is thus
recycled rather than being destroyed.
The connection to the database represented by the {@code PooledConnection} is
kept open until the {@code PooledConnection} object itself is deactivated by
the connection pool manager, which calls {@code PooledConnection.close()}.
This is typically done if there are too many inactive connections in the
pool, if the {@code PooledConnection} encounters a problem that makes it
unusable or if the whole system is being shut down.
| 