javax.sql: public interface: PooledConnection

javax.sql
public interface: PooledConnection [javadoc | source]

All Known Implementing Classes:
XAConnection

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 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 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 {@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.
Method from javax.sql.PooledConnection Summary:
addConnectionEventListener, addStatementEventListener, close, getConnection, removeConnectionEventListener, removeStatementEventListener
Method from javax.sql.PooledConnection Detail:

public void addConnectionEventListener(ConnectionEventListener theListener)
Registers the supplied {@code ConnectionEventListener} with this {@code PooledConnection}. Once registered, the {@code ConnectionEventListener} will receive ConnectionEvent events when they occur in the {@code PooledConnection}.
public void addStatementEventListener(StatementEventListener listener)
Add a StatementEventListener to this PooledConnection object.
public void close() throws SQLException
Closes the connection to the database held by this {@code PooledConnection}. This method should not be called directly by application code - it is intended only for the connection pool manager component.
public Connection getConnection() throws SQLException
Creates a connection to the database. This method is typically called by the connection pool manager when an application invokes the method {@code DataSource.getConnection()} and there are no {@code PooledConnection} objects available in the connection pool.
public void removeConnectionEventListener(ConnectionEventListener theListener)
Unregisters the supplied {@code ConnectionEventListener} from this {@code PooledConnection}. Once unregistered, the {@code ConnectionEventListener} will no longer receive events occurring in the {@code PooledConnection}.
public void removeStatementEventListener(StatementEventListener listener)
Remove a StatementEventListener from this PooledConnection object.