- /*
- * @(#)PooledConnection.java 1.12 03/12/19
- *
- * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
- * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- */
-
- package javax.sql;
-
- import java.sql.Connection;
- import java.sql.SQLException;
-
- /**
- * An object that provides hooks for connection pool management.
- * A <code>PooledConnection</code> 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.
- * <P>
- * An application programmer does not use the <code>PooledConnection</code>
- * interface directly; rather, it is used by a middle tier infrastructure
- * that manages the pooling of connections.
- * <P>
- * When an application calls the method <code>DataSource.getConnection</code>,
- * it gets back a <code>Connection</code> object. If connection pooling is
- * being done, that <code>Connection</code> object is actually a handle to
- * a <code>PooledConnection</code> object, which is a physical connection.
- * <P>
- * The connection pool manager, typically the application server, maintains
- * a pool of <code>PooledConnection</code> objects. If there is a
- * <code>PooledConnection</code> object available in the pool, the
- * connection pool manager returns a <code>Connection</code> object that
- * is a handle to that physical connection.
- * If no <code>PooledConnection</code> object is available, the
- * connection pool manager calls the <code>PooledConnection</code>
- * method <code>getConnection</code> to create a new physical connection and
- * returns a handle to it.
- * <P>
- * When an application closes a connection, it calls the <code>Connection</code>
- * method <code>close</code>. When connection pooling is being done,
- * the connection pool manager is notified because it has registered itself as
- * a <code>ConnectionEventListener</code> object using the
- * <code>ConnectionPool</code> method <code>addConnectionEventListener</code>.
- * The connection pool manager deactivates the handle to
- * the <code>PooledConnection</code> object and returns the
- * <code>PooledConnection</code> 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.
- * <P>
- * The physical connection is not closed until the connection pool manager
- * calls the <code>PooledConnection</code> method <code>close</code>.
- * This method is generally called to have an orderly shutdown of the server or
- * if a fatal error has made the connection unusable.
- *
- * @since 1.4
- */
-
- public interface PooledConnection {
-
- /**
- * Creates and returns a <code>Connection</code> object that is a handle
- * for the physical connection that
- * this <code>PooledConnection</code> object represents.
- * The connection pool manager calls this method when an application has
- * called the method <code>DataSource.getConnection</code> and there are
- * no <code>PooledConnection</code> objects available. See the
- * {@link PooledConnection interface description} for more information.
- *
- * @return a <code>Connection</code> object that is a handle to
- * this <code>PooledConnection</code> object
- * @exception SQLException if a database access error occurs
- */
- Connection getConnection() throws SQLException;
-
- /**
- * Closes the physical connection that this <code>PooledConnection</code>
- * object represents. An application never calls this method directly;
- * it is called by the connection pool module, or manager.
- * <P>
- * See the {@link PooledConnection interface description} for more
- * information.
- *
- * @exception SQLException if a database access error occurs
- */
- void close() throws SQLException;
-
- /**
- * Registers the given event listener so that it will be notified
- * when an event occurs on this <code>PooledConnection</code> object.
- *
- * @param listener a component, usually the connection pool manager,
- * that has implemented the
- * <code>ConnectionEventListener</code> interface and wants to be
- * notified when the connection is closed or has an error
- * @see #removeConnectionEventListener
- */
- void addConnectionEventListener(ConnectionEventListener listener);
-
- /**
- * Removes the given event listener from the list of components that
- * will be notified when an event occurs on this
- * <code>PooledConnection</code> object.
- *
- * @param listener a component, usually the connection pool manager,
- * that has implemented the
- * <code>ConnectionEventListener</code> interface and
- * been registered with this <code>PooledConnection</code> object as
- * a listener
- * @see #addConnectionEventListener
- */
- void removeConnectionEventListener(ConnectionEventListener listener);
-
- }