javax.sql
public
interface
javax.sql.PooledConnection
javax.sql.PooledConnection |
|
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.
Summary
Details
Public Methods
public
void
addConnectionEventListener(ConnectionEventListener theListener)
Registers the supplied ConnectionEventListener with this
PooledConnection. Once registered, the ConnectionEventListener will
receive ConnectionEvent events when they occur in the PooledConnection.
Parameters
theListener
| an object which implements the ConnectionEventListener
interface.
|
public
void
close()
Closes the connection to the database held by this PooledConnection. This
method should not be called directly by application code - it is intended
for use by the Connection Pool manager component.
public
Connection
getConnection()
Creates a connection to the database. This method is typically called by
the Connection Pool manager when an application invokes the method
DataSource.getConnection
and there are no PooledConnection
objects available in the connection pool.
Returns
- a Connection object that is a handle to this PooledConnection
object.
public
void
removeConnectionEventListener(ConnectionEventListener theListener)
Deregister the supplied ConnectionEventListener from this
PooledConnection. Once deregistered, the ConnectionEventListener will not
longer receive events occurring in the PooledConnection.
Parameters
theListener
| an object which implements the ConnectionEventListener
interface. This object should have previously been registered
with the PooledConnection using the
addConnectionEventListener method.
|