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 uses 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
getConnection()
method. Behind the scenes, 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 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 PooledConnection.close()
.
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.
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Registers the supplied
ConnectionEventListener with this PooledConnection . | |||||||||||
Add a StatementEventListener to this PooledConnection object.
| |||||||||||
Closes the connection to the database held by this
PooledConnection . | |||||||||||
Creates a connection to the database.
| |||||||||||
Unregisters the supplied
ConnectionEventListener from this PooledConnection . | |||||||||||
Remove a StatementEventListener from this PooledConnection object.
|
Registers the supplied ConnectionEventListener
with this PooledConnection
. Once registered, the ConnectionEventListener
will receive ConnectionEvent
events when they occur in the
PooledConnection
.
theListener | an object which implements the ConnectionEventListener
interface.
|
---|
Add a StatementEventListener to this PooledConnection object.
listener | A StatementEventListener object which is to be added with this PooledConnection object |
---|
Closes the connection to the database held by this PooledConnection
. This method should not be called directly by
application code - it is intended only for the connection pool manager
component.
SQLException | if there is a problem accessing the database. |
---|
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.
Connection
object.SQLException | if there is a problem accessing the database. |
---|
Unregisters the supplied ConnectionEventListener
from this PooledConnection
. Once unregistered, the ConnectionEventListener
will no longer receive events occurring in the PooledConnection
.
theListener | an object which implements the ConnectionEventListener
interface. This object should have previously been registered
with the PooledConnection using the addConnectionEventListener method.
|
---|
Remove a StatementEventListener from this PooledConnection object.
listener | A StatementEventListener object which is to be removed form this PooledConnection object |
---|