https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.sql;

import java.sql.Connection;
import java.sql.SQLException;


An object that provides hooks for connection pool management.
A 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 logical Connection handle 
  • call close on the logical Connection 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
/**
 * 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>ConnectionPoolDataSource</code>
 * method <code>getPoolConnection</code> to create a new physical connection.  The
 *  JDBC driver implementing <code>ConnectionPoolDataSource</code> creates a
 *  new <code>PooledConnection</code> object 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>
 * If the connection pool manager wraps or provides a proxy to the logical
 * handle returned from a call to {@code PoolConnection.getConnection}, the pool
 * manager must do one of the following when the connection pool manager
 * closes or returns the {@code PooledConnection} to the pool in response to
 * the application calling {@code Connection.close}:
 * <ul>
 * <li>call {@code endRequest} on the logical {@code Connection} handle
 * <li>call {@code close} on the logical {@code Connection} handle
 * </ul>
 * <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.
 *
 * <p>
 * A connection pool manager is often also a statement pool manager, maintaining
 *  a pool of <code>PreparedStatement</code> objects.
 *  When an application closes a prepared statement, it calls the
 *  <code>PreparedStatement</code>
 * method <code>close</code>. When <code>Statement</code> pooling is being done,
 * the pool manager is notified because it has registered itself as
 * a <code>StatementEventListener</code> object using the
 * <code>ConnectionPool</code> method <code>addStatementEventListener</code>.
 *  Thus, when an application closes its  <code>PreparedStatement</code>,
 * the underlying prepared statement is recycled rather than being closed.
 *
 * @since 1.4
 */

public interface PooledConnection {

  
Creates and returns a Connection object that is a handle
for the physical connection that
this PooledConnection object represents.
The connection pool manager calls this method when an application has
called the method DataSource.getConnection and there are
no PooledConnection objects available. See the interface description for more information. 
Throws:
Returns: a Connection object that is a handle to
         this PooledConnection object
Since:1.4
/**
   * 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
   * @exception java.sql.SQLFeatureNotSupportedException if the JDBC driver does not support
   * this method
   * @since 1.4
   */
  Connection getConnection() throws SQLException;

  
Closes the physical connection that this PooledConnection
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:
Since:1.4
/**
   * 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
   * @exception java.sql.SQLFeatureNotSupportedException if the JDBC driver does not support
   * this method
   * @since 1.4
   */
  void close() throws SQLException;

  
Registers the given event listener so that it will be notified
when an event occurs on this PooledConnection object.

Params:
  • listener – a component, usually the connection pool manager,
       that has implemented the
       ConnectionEventListener interface and wants to be
       notified when the connection is closed or has an error
See Also:
/**
   * 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
PooledConnection object.

Params:
  • listener – a component, usually the connection pool manager,
       that has implemented the
       ConnectionEventListener interface and
       been registered with this PooledConnection object as
       a listener
See Also:
/**
   * 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);

        
Registers a StatementEventListener with this PooledConnection object.  Components that
wish to be notified when  PreparedStatements created by the
connection are closed or are detected to be invalid may use this method
to register a StatementEventListener with this PooledConnection object.

Params:
  • listener –      an component which implements the StatementEventListener
                                     interface that is to be registered with this PooledConnection object
Since:1.6
/**
         * Registers a <code>StatementEventListener</code> with this <code>PooledConnection</code> object.  Components that
         * wish to be notified when  <code>PreparedStatement</code>s created by the
         * connection are closed or are detected to be invalid may use this method
         * to register a <code>StatementEventListener</code> with this <code>PooledConnection</code> object.
         *
         * @param listener      an component which implements the <code>StatementEventListener</code>
         *                                      interface that is to be registered with this <code>PooledConnection</code> object
         *
         * @since 1.6
         */
        public void addStatementEventListener(StatementEventListener listener);

        
Removes the specified StatementEventListener from the list of
components that will be notified when the driver detects that a
PreparedStatement has been closed or is invalid.

Params:
  • listener –      the component which implements the
                                     StatementEventListener interface that was previously
                                     registered with this PooledConnection object
Since:1.6
/**
         * Removes the specified <code>StatementEventListener</code> from the list of
         * components that will be notified when the driver detects that a
         * <code>PreparedStatement</code> has been closed or is invalid.
         *
         * @param listener      the component which implements the
         *                                      <code>StatementEventListener</code> interface that was previously
         *                                      registered with this <code>PooledConnection</code> object
         *
         * @since 1.6
         */
        public void removeStatementEventListener(StatementEventListener listener);

 }