2362N/A * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * An object that provides hooks for connection pool management. 0N/A * A <code>PooledConnection</code> object 0N/A * represents a physical connection to a data source. The connection 0N/A * can be recycled rather than being closed when an application is 0N/A * finished with it, thus reducing the number of connections that 0N/A * An application programmer does not use the <code>PooledConnection</code> 0N/A * interface directly; rather, it is used by a middle tier infrastructure 0N/A * that manages the pooling of connections. 0N/A * When an application calls the method <code>DataSource.getConnection</code>, 0N/A * it gets back a <code>Connection</code> object. If connection pooling is 0N/A * being done, that <code>Connection</code> object is actually a handle to 0N/A * a <code>PooledConnection</code> object, which is a physical connection. 0N/A * The connection pool manager, typically the application server, maintains 0N/A * a pool of <code>PooledConnection</code> objects. If there is a 0N/A * <code>PooledConnection</code> object available in the pool, the 0N/A * connection pool manager returns a <code>Connection</code> object that 0N/A * is a handle to that physical connection. 0N/A * If no <code>PooledConnection</code> object is available, the 0N/A * connection pool manager calls the <code>ConnectionPoolDataSource</code> 0N/A * method <code>getPoolConnection</code> to create a new physical connection. The 0N/A * JDBC driver implementing <code>ConnectionPoolDataSource</code> creates a 0N/A * new <code>PooledConnection</code> object and returns a handle to it. 0N/A * When an application closes a connection, it calls the <code>Connection</code> 0N/A * method <code>close</code>. When connection pooling is being done, 0N/A * the connection pool manager is notified because it has registered itself as 0N/A * a <code>ConnectionEventListener</code> object using the 0N/A * <code>ConnectionPool</code> method <code>addConnectionEventListener</code>. 0N/A * The connection pool manager deactivates the handle to 0N/A * the <code>PooledConnection</code> object and returns the 0N/A * <code>PooledConnection</code> object to the pool of connections so that 0N/A * it can be used again. Thus, when an application closes its connection, 0N/A * the underlying physical connection is recycled rather than being closed. 0N/A * The physical connection is not closed until the connection pool manager 0N/A * calls the <code>PooledConnection</code> method <code>close</code>. 0N/A * This method is generally called to have an orderly shutdown of the server or 0N/A * if a fatal error has made the connection unusable. 0N/A * A connection pool manager is often also a statement pool manager, maintining 0N/A * a pool of <code>PreparedStatement</code> objects. 0N/A * When an application closes a prepared statement, it calls the 0N/A * <code>PreparedStatement</code> 0N/A * method <code>close</code>. When <code>Statement</code> pooling is being done, 0N/A * the pool manager is notified because it has registered itself as 0N/A * a <code>StatementEventListener</code> object using the 0N/A * <code>ConnectionPool</code> method <code>addStatementEventListener</code>. 0N/A * Thus, when an application closes its <code>PreparedStatement</code>, 0N/A * the underlying prepared statement is recycled rather than being closed. 0N/A * Creates and returns a <code>Connection</code> object that is a handle 0N/A * for the physical connection that 0N/A * this <code>PooledConnection</code> object represents. 0N/A * The connection pool manager calls this method when an application has 0N/A * called the method <code>DataSource.getConnection</code> and there are 0N/A * no <code>PooledConnection</code> objects available. See the 0N/A * {@link PooledConnection interface description} for more information. 0N/A * @return a <code>Connection</code> object that is a handle to 0N/A * this <code>PooledConnection</code> object 0N/A * @exception SQLException if a database access error occurs 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Closes the physical connection that this <code>PooledConnection</code> 0N/A * object represents. An application never calls this method directly; 0N/A * it is called by the connection pool module, or manager. 0N/A * See the {@link PooledConnection interface description} for more 0N/A * @exception SQLException if a database access error occurs 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Registers the given event listener so that it will be notified 0N/A * when an event occurs on this <code>PooledConnection</code> object. 0N/A * @param listener a component, usually the connection pool manager, 0N/A * that has implemented the 0N/A * <code>ConnectionEventListener</code> interface and wants to be 0N/A * notified when the connection is closed or has an error 0N/A * @see #removeConnectionEventListener 0N/A * Removes the given event listener from the list of components that 0N/A * will be notified when an event occurs on this 0N/A * <code>PooledConnection</code> object. 0N/A * @param listener a component, usually the connection pool manager, 0N/A * that has implemented the 0N/A * <code>ConnectionEventListener</code> interface and 0N/A * been registered with this <code>PooledConnection</code> object as 0N/A * @see #addConnectionEventListener 0N/A * Registers a <code>StatementEventListener</code> with this <code>PooledConnection</code> object. Components that 0N/A * wish to be notified when <code>PreparedStatement</code>s created by the 0N/A * connection are closed or are detected to be invalid may use this method 0N/A * to register a <code>StatementEventListener</code> with this <code>PooledConnection</code> object. 0N/A * @param listener an component which implements the <code>StatementEventListener</code> 0N/A * interface that is to be registered with this <code>PooledConnection</code> object 0N/A * Removes the specified <code>StatementEventListener</code> from the list of 0N/A * components that will be notified when the driver detects that a 0N/A * <code>PreparedStatement</code> has been closed or is invalid. 0N/A * @param listener the component which implements the 0N/A * <code>StatementEventListener</code> interface that was previously 0N/A * registered with this <code>PooledConnection</code> object