001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.sql;
019:
020: import java.sql.SQLException;
021: import java.sql.Connection;
022:
023: /**
024: * An interface which provides facilities for handling connections to a database
025: * which are pooled.
026: * <p>
027: * Typically, a PooledConnection is recycled when it is no longer required by an
028: * application, rather than being closed and discarded. The reason for treating
029: * connections in this way is that it can be an expensive process both to
030: * establish a connection to a database and to destroy the connection. Reusing
031: * connections through a pool is a way of improving system performance and
032: * reducing overhead.
033: * <p>
034: * It is not intended that an application use the PooledConnection interface
035: * directly. The PooledConnection interface is intended for use by a component
036: * called a Connection Pool Manager, typically part of the infrastructure that
037: * supports use of the database by applications.
038: * <p>
039: * Applications obtain connections to the database by calling the
040: * <code>DataSource.getConnection</code> method. Under the covers, the
041: * Connection Pool Manager will get a PooledConnection object from its
042: * connection pool and passes back a Connection object that wraps or references
043: * the PooledConnection object. A new PooledConnection object will only be
044: * created if the pool is empty.
045: * <p>
046: * When the application is finished using a PooledConnection, the application
047: * calls the <code>Connection.close</code> method. The Connection Pool Manager
048: * is notified via a ConnectionEvent from the Connection that this has happened
049: * (the Pool Manager registers itself with the Connection before the Connection
050: * is given to the application). The Pool Manager removes the underlying
051: * PooledConnection object from the Connection and returns it to the pool for
052: * reuse - the PooledConnection is thus recycled rather than being destroyed.
053: * <p>
054: * The connection to the database represented by the PooledConnection is kept
055: * open until the PooledConnection object itself is deactivated by the
056: * Connection Pool Manager, which calls the <code>PooledConnection.close</code>
057: * method. This is typically done if there are too many inactive connections in
058: * the pool, if the PooledConnection encounters a problem that makes it unusable
059: * or if the whole system is being shut down.
060: *
061: */
062: public interface PooledConnection {
063:
064: /**
065: * Registers the supplied ConnectionEventListener with this
066: * PooledConnection. Once registered, the ConnectionEventListener will
067: * receive ConnectionEvent events when they occur in the PooledConnection.
068: *
069: * @param theListener
070: * an object which implements the ConnectionEventListener
071: * interface.
072: */
073: public void addConnectionEventListener(
074: ConnectionEventListener theListener);
075:
076: /**
077: * Closes the connection to the database held by this PooledConnection. This
078: * method should not be called directly by application code - it is intended
079: * for use by the Connection Pool manager component.
080: *
081: * @throws SQLException
082: * if there is a problem accessing the database.
083: */
084: public void close() throws SQLException;
085:
086: /**
087: * Creates a connection to the database. This method is typically called by
088: * the Connection Pool manager when an application invokes the method
089: * <code>DataSource.getConnection</code> and there are no PooledConnection
090: * objects available in the connection pool.
091: *
092: * @return a Connection object that is a handle to this PooledConnection
093: * object.
094: * @throws SQLException
095: * if there is a problem accessing the database.
096: */
097: public Connection getConnection() throws SQLException;
098:
099: /**
100: * Deregister the supplied ConnectionEventListener from this
101: * PooledConnection. Once deregistered, the ConnectionEventListener will not
102: * longer receive events occurring in the PooledConnection.
103: *
104: * @param theListener
105: * an object which implements the ConnectionEventListener
106: * interface. This object should have previously been registered
107: * with the PooledConnection using the
108: * <code>addConnectionEventListener</code> method.
109: */
110: public void removeConnectionEventListener(
111: ConnectionEventListener theListener);
112: }
|