1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package javax.sql;
19
20import java.sql.SQLException;
21import java.sql.Connection;
22
23/**
24 * An interface which provides facilities for handling connections to a database
25 * which are pooled.
26 * <p>
27 * Typically, a {@code PooledConnection} is recycled when it is no longer
28 * required by an application, rather than being closed and discarded. The
29 * reason for treating connections in this way is that it can be an expensive
30 * process both to establish a connection to a database and to destroy the
31 * connection. Reusing connections through a pool is a way of improving system
32 * performance and reducing overhead.
33 * <p>
34 * It is not intended that an application uses the {@code PooledConnection}
35 * interface directly. The {@code PooledConnection} interface is intended for
36 * use by a component called a connection pool manager, typically part of the
37 * infrastructure that supports use of the database by applications.
38 * <p>
39 * Applications obtain connections to the database by calling the
40 * {@link DataSource#getConnection} method. Behind the scenes, the connection
41 * pool manager will get a {@code PooledConnection} object from its connection
42 * pool and passes back a connection object that wraps or references the {@code
43 * PooledConnection} object. A new {@code PooledConnection} object will only be
44 * created if the pool is empty.
45 * <p>
46 * When the application is finished using a {@code PooledConnection}, the
47 * application calls the {@link Connection#close} method. The connection pool
48 * manager is notified via a {@link ConnectionEvent} from the connection that
49 * this has happened (the pool manager registers itself with the connection
50 * before the connection is given to the application). The pool manager removes
51 * the underlying {@code PooledConnection} object from the connection and
52 * returns it to the pool for reuse - the {@code PooledConnection} is thus
53 * recycled rather than being destroyed.
54 * <p>
55 * The connection to the database represented by the {@code PooledConnection} is
56 * kept open until the {@code PooledConnection} object itself is deactivated by
57 * the connection pool manager, which calls {@code PooledConnection.close()}.
58 * This is typically done if there are too many inactive connections in the
59 * pool, if the {@code PooledConnection} encounters a problem that makes it
60 * unusable or if the whole system is being shut down.
61 */
62public interface PooledConnection {
63
64    /**
65     * Registers the supplied {@code ConnectionEventListener} with this {@code
66     * PooledConnection}. Once registered, the {@code ConnectionEventListener}
67     * will receive {@link ConnectionEvent} events when they occur in the
68     * {@code PooledConnection}.
69     *
70     * @param theListener
71     *            an object which implements the {@code ConnectionEventListener}
72     *            interface.
73     */
74    public void addConnectionEventListener(ConnectionEventListener theListener);
75
76    /**
77     * Closes the connection to the database held by this {@code
78     * PooledConnection}. This method should not be called directly by
79     * application code - it is intended only for the connection pool manager
80     * component.
81     *
82     * @throws SQLException
83     *             if there is a problem accessing the database.
84     */
85    public void close() throws SQLException;
86
87    /**
88     * Creates a connection to the database. This method is typically called by
89     * the connection pool manager when an application invokes the method
90     * {@code DataSource.getConnection()} and there are no {@code
91     * PooledConnection} objects available in the connection pool.
92     *
93     * @return a {@code Connection} object.
94     * @throws SQLException
95     *             if there is a problem accessing the database.
96     */
97    public Connection getConnection() throws SQLException;
98
99    /**
100     * Unregisters the supplied {@code ConnectionEventListener} from this {@code
101     * PooledConnection}. Once unregistered, the {@code ConnectionEventListener}
102     * will no longer receive events occurring in the {@code PooledConnection}.
103     *
104     * @param theListener
105     *            an object which implements the {@code ConnectionEventListener}
106     *            interface. This object should have previously been registered
107     *            with the {@code PooledConnection} using the {@code
108     *            addConnectionEventListener} method.
109     */
110    public void removeConnectionEventListener(
111            ConnectionEventListener theListener);
112}
113