/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package javax.sql;
import java.sql.Connection;
import java.sql.SQLException;
/**
* An interface which provides facilities for handling connections to a database
* which are pooled.
* <p>
* Typically, a {@code PooledConnection} is recycled when it is no longer
* required by an application, rather than being closed and discarded. The
* reason for treating connections in this way is that it can be an expensive
* process both to establish a connection to a database and to destroy the
* connection. Reusing connections through a pool is a way of improving system
* performance and reducing overhead.
* <p>
* It is not intended that an application uses the {@code PooledConnection}
* interface directly. The {@code PooledConnection} interface is intended for
* use by a component called a connection pool manager, typically part of the
* infrastructure that supports use of the database by applications.
* <p>
* Applications obtain connections to the database by calling the
* {@link DataSource#getConnection} method. Behind the scenes, the connection
* pool manager will get a {@code PooledConnection} object from its connection
* pool and passes back a connection object that wraps or references the {@code
* PooledConnection} object. A new {@code PooledConnection} object will only be
* created if the pool is empty.
* <p>
* When the application is finished using a {@code PooledConnection}, the
* application calls the {@link Connection#close} method. The connection pool
* manager is notified via a {@link ConnectionEvent} from the connection that
* this has happened (the pool manager registers itself with the connection
* before the connection is given to the application). The pool manager removes
* the underlying {@code PooledConnection} object from the connection and
* returns it to the pool for reuse - the {@code PooledConnection} is thus
* recycled rather than being destroyed.
* <p>
* The connection to the database represented by the {@code PooledConnection} is
* kept open until the {@code PooledConnection} object itself is deactivated by
* the connection pool manager, which calls {@code PooledConnection.close()}.
* This is typically done if there are too many inactive connections in the
* pool, if the {@code PooledConnection} encounters a problem that makes it
* unusable or if the whole system is being shut down.
*/
public interface PooledConnection {
/**
* Registers the supplied {@code ConnectionEventListener} with this {@code
* PooledConnection}. Once registered, the {@code ConnectionEventListener}
* will receive {@link ConnectionEvent} events when they occur in the
* {@code PooledConnection}.
*
* @param theListener
* an object which implements the {@code ConnectionEventListener}
* interface.
*/
public void addConnectionEventListener(ConnectionEventListener theListener);
/**
* Closes the connection to the database held by this {@code
* PooledConnection}. This method should not be called directly by
* application code - it is intended only for the connection pool manager
* component.
*
* @throws SQLException
* if there is a problem accessing the database.
*/
public void close() throws SQLException;
/**
* Creates a connection to the database. This method is typically called by
* the connection pool manager when an application invokes the method
* {@code DataSource.getConnection()} and there are no {@code
* PooledConnection} objects available in the connection pool.
*
* @return a {@code Connection} object.
* @throws SQLException
* if there is a problem accessing the database.
*/
public Connection getConnection() throws SQLException;
/**
* Unregisters the supplied {@code ConnectionEventListener} from this {@code
* PooledConnection}. Once unregistered, the {@code ConnectionEventListener}
* will no longer receive events occurring in the {@code PooledConnection}.
*
* @param theListener
* an object which implements the {@code ConnectionEventListener}
* interface. This object should have previously been registered
* with the {@code PooledConnection} using the {@code
* addConnectionEventListener} method.
*/
public void removeConnectionEventListener(
ConnectionEventListener theListener);
/**
* Add a StatementEventListener to this PooledConnection object.
*
* @param listener
* A StatementEventListener object which is to be added with this
* PooledConnection object
* @since 1.6
*/
public void addStatementEventListener(StatementEventListener listener);
/**
* Remove a StatementEventListener from this PooledConnection object.
*
* @param listener
* A StatementEventListener object which is to be removed form
* this PooledConnection object
* @since 1.6
*/
public void removeStatementEventListener(StatementEventListener listener);
}