javax.sql.PooledConnection Maven / Gradle / Ivy
/*
* Copyright (c) 2000, 2020, 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} 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 {@code PooledConnection}
* interface directly; rather, it is used by a middle tier infrastructure
* that manages the pooling of connections.
*
* When an application calls the method {@code DataSource.getConnection},
* it gets back a {@code Connection} object. If connection pooling is
* being done, that {@code Connection} object is actually a handle to
* a {@code PooledConnection} object, which is a physical connection.
*
* The connection pool manager, typically the application server, maintains
* a pool of {@code PooledConnection} objects. If there is a
* {@code PooledConnection} object available in the pool, the
* connection pool manager returns a {@code Connection} object that
* is a handle to that physical connection.
* If no {@code PooledConnection} object is available, the
* connection pool manager calls the {@code ConnectionPoolDataSource}
* method {@code getPoolConnection} to create a new physical connection. The
* JDBC driver implementing {@code ConnectionPoolDataSource} creates a
* new {@code PooledConnection} object and returns a handle to it.
*
* When an application closes a connection, it calls the {@code Connection}
* method {@code close}. When connection pooling is being done,
* the connection pool manager is notified because it has registered itself as
* a {@code ConnectionEventListener} object using the
* {@code ConnectionPool} method {@code addConnectionEventListener}.
* The connection pool manager deactivates the handle to
* the {@code PooledConnection} object and returns the
* {@code 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 {@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}:
*
* - call {@code endRequest} on the logical {@code Connection} handle
*
- call {@code close} on the logical {@code Connection} handle
*
*
* The physical connection is not closed until the connection pool manager
* calls the {@code PooledConnection} method {@code 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 {@code PreparedStatement} objects.
* When an application closes a prepared statement, it calls the
* {@code PreparedStatement}
* method {@code close}. When {@code Statement} pooling is being done,
* the pool manager is notified because it has registered itself as
* a {@code StatementEventListener} object using the
* {@code ConnectionPool} method {@code addStatementEventListener}.
* Thus, when an application closes its {@code PreparedStatement},
* the underlying prepared statement is recycled rather than being closed.
*
* @since 1.4
*/
public interface PooledConnection {
/**
* Creates and returns a {@code Connection} object that is a handle
* for the physical connection that
* this {@code PooledConnection} object represents.
* The connection pool manager calls this method when an application has
* called the method {@code DataSource.getConnection} and there are
* no {@code PooledConnection} objects available. See the
* {@link PooledConnection interface description} for more information.
*
* @return a {@code Connection} object that is a handle to
* this {@code PooledConnection} object
* @throws SQLException if a database access error occurs
* @throws 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}
* object represents. An application never calls this method directly;
* it is called by the connection pool module, or manager.
*
* See the {@link PooledConnection interface description} for more
* information.
*
* @throws SQLException if a database access error occurs
* @throws 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} object.
*
* @param listener a component, usually the connection pool manager,
* that has implemented the
* {@code ConnectionEventListener} 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} object.
*
* @param listener a component, usually the connection pool manager,
* that has implemented the
* {@code ConnectionEventListener} interface and
* been registered with this {@code PooledConnection} object as
* a listener
* @see #addConnectionEventListener
*/
void removeConnectionEventListener(ConnectionEventListener listener);
/**
* Registers a {@code StatementEventListener} with this {@code PooledConnection} object. Components that
* wish to be notified when {@code PreparedStatement}s created by the
* connection are closed or are detected to be invalid may use this method
* to register a {@code StatementEventListener} with this {@code PooledConnection} object.
*
* @param listener an component which implements the {@code StatementEventListener}
* interface that is to be registered with this {@code PooledConnection} object
*
* @since 1.6
*/
public void addStatementEventListener(StatementEventListener listener);
/**
* Removes the specified {@code StatementEventListener} from the list of
* components that will be notified when the driver detects that a
* {@code PreparedStatement} has been closed or is invalid.
*
* @param listener the component which implements the
* {@code StatementEventListener} interface that was previously
* registered with this {@code PooledConnection} object
*
* @since 1.6
*/
public void removeStatementEventListener(StatementEventListener listener);
}