An interface which provides facilities for handling connections to a database which are pooled.
Typically, a 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 use the PooledConnection interface directly. The 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 DataSource.getConnection method. Under the covers, the Connection Pool Manager will get a PooledConnection object from its connection pool and passes back a Connection object that wraps or references the PooledConnection object. A new PooledConnection object will only be created if the pool is empty.
When the application is finished using a PooledConnection, the application calls the Connection.close method. The Connection Pool Manager is notified via a 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 PooledConnection object from the Connection and returns it to the pool for reuse - the PooledConnection is thus recycled rather than being destroyed.
The connection to the database represented by the PooledConnection is kept open until the PooledConnection object itself is deactivated by the Connection Pool Manager, which calls the PooledConnection.close method. This is typically done if there are too many inactive connections in the pool, if the PooledConnection encounters a problem that makes it unusable or if the whole system is being shut down.