- All Known Subinterfaces:
XAConnection
PooledConnection
object
represents a physical connection to a data source. The connection
can be recycled rather than being closed when an application is
finished with it, thus reducing the number of connections that
need to be made.
An application programmer does not use the PooledConnection
interface directly; rather, it is used by a middle tier infrastructure
that manages the pooling of connections.
When an application calls the method DataSource.getConnection
,
it gets back a Connection
object. If connection pooling is
being done, that Connection
object is actually a handle to
a PooledConnection
object, which is a physical connection.
The connection pool manager, typically the application server, maintains
a pool of PooledConnection
objects. If there is a
PooledConnection
object available in the pool, the
connection pool manager returns a Connection
object that
is a handle to that physical connection.
If no PooledConnection
object is available, the
connection pool manager calls the ConnectionPoolDataSource
method getPoolConnection
to create a new physical connection. The
JDBC driver implementing ConnectionPoolDataSource
creates a
new PooledConnection
object and returns a handle to it.
When an application closes a connection, it calls the Connection
method close
. When connection pooling is being done,
the connection pool manager is notified because it has registered itself as
a ConnectionEventListener
object using the
ConnectionPool
method addConnectionEventListener
.
The connection pool manager deactivates the handle to
the PooledConnection
object and returns the
PooledConnection
object to the pool of connections so that
it can be used again. Thus, when an application closes its connection,
the underlying physical connection is recycled rather than being closed.
If the connection pool manager wraps or provides a proxy to the logical
handle returned from a call to PoolConnection.getConnection
, the pool
manager must do one of the following when the connection pool manager
closes or returns the PooledConnection
to the pool in response to
the application calling Connection.close
:
- call
endRequest
on the logicalConnection
handle - call
close
on the logicalConnection
handle
The physical connection is not closed until the connection pool manager
calls the PooledConnection
method close
.
This method is generally called to have an orderly shutdown of the server or
if a fatal error has made the connection unusable.
A connection pool manager is often also a statement pool manager, maintaining
a pool of PreparedStatement
objects.
When an application closes a prepared statement, it calls the
PreparedStatement
method close
. When Statement
pooling is being done,
the pool manager is notified because it has registered itself as
a StatementEventListener
object using the
ConnectionPool
method addStatementEventListener
.
Thus, when an application closes its PreparedStatement
,
the underlying prepared statement is recycled rather than being closed.
- Since:
- 1.4
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Registers the given event listener so that it will be notified when an event occurs on thisPooledConnection
object.void
Registers aStatementEventListener
with thisPooledConnection
object.void
close()
Closes the physical connection that thisPooledConnection
object represents.Creates and returns aConnection
object that is a handle for the physical connection that thisPooledConnection
object represents.void
Removes the given event listener from the list of components that will be notified when an event occurs on thisPooledConnection
object.void
Removes the specifiedStatementEventListener
from the list of components that will be notified when the driver detects that aPreparedStatement
has been closed or is invalid.
-
Method Details
-
getConnection
Creates and returns aConnection
object that is a handle for the physical connection that thisPooledConnection
object represents. The connection pool manager calls this method when an application has called the methodDataSource.getConnection
and there are noPooledConnection
objects available. See theinterface description
for more information.- Returns:
- a
Connection
object that is a handle to thisPooledConnection
object - Throws:
SQLException
- if a database access error occursSQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- 1.4
-
close
Closes the physical connection that thisPooledConnection
object represents. An application never calls this method directly; it is called by the connection pool module, or manager.See the
interface description
for more information.- Throws:
SQLException
- if a database access error occursSQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- 1.4
-
addConnectionEventListener
Registers the given event listener so that it will be notified when an event occurs on thisPooledConnection
object.- Parameters:
listener
- a component, usually the connection pool manager, that has implemented theConnectionEventListener
interface and wants to be notified when the connection is closed or has an error- See Also:
-
removeConnectionEventListener
Removes the given event listener from the list of components that will be notified when an event occurs on thisPooledConnection
object.- Parameters:
listener
- a component, usually the connection pool manager, that has implemented theConnectionEventListener
interface and been registered with thisPooledConnection
object as a listener- See Also:
-
addStatementEventListener
Registers aStatementEventListener
with thisPooledConnection
object. Components that wish to be notified whenPreparedStatement
s created by the connection are closed or are detected to be invalid may use this method to register aStatementEventListener
with thisPooledConnection
object.- Parameters:
listener
- an component which implements theStatementEventListener
interface that is to be registered with thisPooledConnection
object- Since:
- 1.6
-
removeStatementEventListener
Removes the specifiedStatementEventListener
from the list of components that will be notified when the driver detects that aPreparedStatement
has been closed or is invalid.- Parameters:
listener
- the component which implements theStatementEventListener
interface that was previously registered with thisPooledConnection
object- Since:
- 1.6
-