Interface PooledConnection
-
- All Known Subinterfaces:
- XAConnection
public interface PooledConnection
An object that provides hooks for connection pool management. APooledConnection
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 aConnection
object. If connection pooling is being done, thatConnection
object is actually a handle to aPooledConnection
object, which is a physical connection.The connection pool manager, typically the application server, maintains a pool of
PooledConnection
objects. If there is aPooledConnection
object available in the pool, the connection pool manager returns aConnection
object that is a handle to that physical connection. If noPooledConnection
object is available, the connection pool manager calls theConnectionPoolDataSource
methodgetPoolConnection
to create a new physical connection. The JDBC driver implementingConnectionPoolDataSource
creates a newPooledConnection
object and returns a handle to it.When an application closes a connection, it calls the
Connection
methodclose
. When connection pooling is being done, the connection pool manager is notified because it has registered itself as aConnectionEventListener
object using theConnectionPool
methodaddConnectionEventListener
. The connection pool manager deactivates the handle to thePooledConnection
object and returns thePooledConnection
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.The physical connection is not closed until the connection pool manager calls the
PooledConnection
methodclose
. 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 thePreparedStatement
methodclose
. WhenStatement
pooling is being done, the pool manager is notified because it has registered itself as aStatementEventListener
object using theConnectionPool
methodaddStatementEventListener
. Thus, when an application closes itsPreparedStatement
, the underlying prepared statement is recycled rather than being closed.- Since:
- 1.4
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method and Description void
addConnectionEventListener(ConnectionEventListener listener)
Registers the given event listener so that it will be notified when an event occurs on thisPooledConnection
object.void
addStatementEventListener(StatementEventListener listener)
Registers aStatementEventListener
with thisPooledConnection
object.void
close()
Closes the physical connection that thisPooledConnection
object represents.Connection
getConnection()
Creates and returns aConnection
object that is a handle for the physical connection that thisPooledConnection
object represents.void
removeConnectionEventListener(ConnectionEventListener listener)
Removes the given event listener from the list of components that will be notified when an event occurs on thisPooledConnection
object.void
removeStatementEventListener(StatementEventListener listener)
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 Detail
getConnection
Connection getConnection() throws SQLException
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 occurs -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.4
close
void close() throws SQLException
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 occurs -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.4
addConnectionEventListener
void addConnectionEventListener(ConnectionEventListener listener)
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(javax.sql.ConnectionEventListener)
removeConnectionEventListener
void removeConnectionEventListener(ConnectionEventListener listener)
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:
-
addConnectionEventListener(javax.sql.ConnectionEventListener)
addStatementEventListener
void addStatementEventListener(StatementEventListener listener)
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
void removeStatementEventListener(StatementEventListener listener)
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
-
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2022, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.