| /* |
| * 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 <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 <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 <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 <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); |
| |
| /** |
| * 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 <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); |
| |
| } |