- 
- All Known Subinterfaces:
- XAConnection
 
 public interface PooledConnectionAn object that provides hooks for connection pool management. APooledConnectionobject 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 PooledConnectioninterface 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 aConnectionobject. If connection pooling is being done, thatConnectionobject is actually a handle to aPooledConnectionobject, which is a physical connection.The connection pool manager, typically the application server, maintains a pool of PooledConnectionobjects. If there is aPooledConnectionobject available in the pool, the connection pool manager returns aConnectionobject that is a handle to that physical connection. If noPooledConnectionobject is available, the connection pool manager calls theConnectionPoolDataSourcemethodgetPoolConnectionto create a new physical connection. The JDBC driver implementingConnectionPoolDataSourcecreates a newPooledConnectionobject and returns a handle to it.When an application closes a connection, it calls the Connectionmethodclose. When connection pooling is being done, the connection pool manager is notified because it has registered itself as aConnectionEventListenerobject using theConnectionPoolmethodaddConnectionEventListener. The connection pool manager deactivates the handle to thePooledConnectionobject and returns thePooledConnectionobject 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 thePooledConnectionto the pool in response to the application callingConnection.close:- call endRequeston the logicalConnectionhandle
- call closeon the logicalConnectionhandle
 The physical connection is not closed until the connection pool manager calls the PooledConnectionmethodclose. 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 PreparedStatementobjects. When an application closes a prepared statement, it calls thePreparedStatementmethodclose. WhenStatementpooling is being done, the pool manager is notified because it has registered itself as aStatementEventListenerobject using theConnectionPoolmethodaddStatementEventListener. Thus, when an application closes itsPreparedStatement, the underlying prepared statement is recycled rather than being closed.- Since:
- 1.4
 
- 
- 
Method SummaryAll Methods Instance Methods Abstract Methods Modifier and Type Method Description voidaddConnectionEventListener(ConnectionEventListener listener)Registers the given event listener so that it will be notified when an event occurs on thisPooledConnectionobject.voidaddStatementEventListener(StatementEventListener listener)Registers aStatementEventListenerwith thisPooledConnectionobject.voidclose()Closes the physical connection that thisPooledConnectionobject represents.ConnectiongetConnection()Creates and returns aConnectionobject that is a handle for the physical connection that thisPooledConnectionobject represents.voidremoveConnectionEventListener(ConnectionEventListener listener)Removes the given event listener from the list of components that will be notified when an event occurs on thisPooledConnectionobject.voidremoveStatementEventListener(StatementEventListener listener)Removes the specifiedStatementEventListenerfrom the list of components that will be notified when the driver detects that aPreparedStatementhas been closed or is invalid.
 
- 
- 
- 
Method Detail- 
getConnectionConnection getConnection() throws SQLException Creates and returns aConnectionobject that is a handle for the physical connection that thisPooledConnectionobject represents. The connection pool manager calls this method when an application has called the methodDataSource.getConnectionand there are noPooledConnectionobjects available. See theinterface descriptionfor more information.- Returns:
- a Connectionobject that is a handle to thisPooledConnectionobject
- Throws:
- SQLException- if a database access error occurs
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.4
 
 - 
closevoid close() throws SQLExceptionCloses the physical connection that thisPooledConnectionobject represents. An application never calls this method directly; it is called by the connection pool module, or manager.See the interface descriptionfor more information.- Throws:
- SQLException- if a database access error occurs
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.4
 
 - 
addConnectionEventListenervoid addConnectionEventListener(ConnectionEventListener listener) Registers the given event listener so that it will be notified when an event occurs on thisPooledConnectionobject.- Parameters:
- listener- a component, usually the connection pool manager, that has implemented the- ConnectionEventListenerinterface and wants to be notified when the connection is closed or has an error
- See Also:
- removeConnectionEventListener(javax.sql.ConnectionEventListener)
 
 - 
removeConnectionEventListenervoid removeConnectionEventListener(ConnectionEventListener listener) Removes the given event listener from the list of components that will be notified when an event occurs on thisPooledConnectionobject.- Parameters:
- listener- a component, usually the connection pool manager, that has implemented the- ConnectionEventListenerinterface and been registered with this- PooledConnectionobject as a listener
- See Also:
- addConnectionEventListener(javax.sql.ConnectionEventListener)
 
 - 
addStatementEventListenervoid addStatementEventListener(StatementEventListener listener) Registers aStatementEventListenerwith thisPooledConnectionobject. Components that wish to be notified whenPreparedStatements created by the connection are closed or are detected to be invalid may use this method to register aStatementEventListenerwith thisPooledConnectionobject.- Parameters:
- listener- an component which implements the- StatementEventListenerinterface that is to be registered with this- PooledConnectionobject
- Since:
- 1.6
 
 - 
removeStatementEventListenervoid removeStatementEventListener(StatementEventListener listener) Removes the specifiedStatementEventListenerfrom the list of components that will be notified when the driver detects that aPreparedStatementhas been closed or is invalid.- Parameters:
- listener- the component which implements the- StatementEventListenerinterface that was previously registered with this- PooledConnectionobject
- Since:
- 1.6
 
 
- 
 
-