PooledConnection.java revision 89c1feb0a69a7707b271086e749975b3f7acacf7 
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 * <p>
35 * It is not intended that an application uses the {@code PooledConnection}
36 * interface directly. The {@code PooledConnection} interface is intended for
37 * use by a component called a connection pool manager, typically part of the
38 * infrastructure that supports use of the database by applications.
39 * </p>
40 * <p>
41 * Applications obtain connections to the database by calling the
42 * {@link DataSource#getConnection} method. Behind the scenes, the connection
43 * pool manager will get a {@code PooledConnection} object from its connection
44 * pool and passes back a connection object that wraps or references the {@code
45 * PooledConnection} object. A new {@code PooledConnection} object will only be
46 * created if the pool is empty.
47 * </p>
48 * <p>
49 * When the application is finished using a {@code PooledConnection}, the
50 * application calls the {@link Connection#close} method. The connection pool
51 * manager is notified via a {@link ConnectionEvent} from the connection that
52 * this has happened (the pool manager registers itself with the connection
53 * before the connection is given to the application). The pool manager removes
54 * the underlying {@code PooledConnection} object from the connection and
55 * returns it to the pool for reuse - the {@code PooledConnection} is thus
56 * recycled rather than being destroyed.
57 * </p>
58 * <p>
59 * The connection to the database represented by the {@code PooledConnection} is
60 * kept open until the {@code PooledConnection} object itself is deactivated by
61 * the connection pool manager, which calls {@code PooledConnection.close()}.
62 * This is typically done if there are too many inactive connections in the
63 * pool, if the {@code PooledConnection} encounters a problem that makes it
64 * unusable or if the whole system is being shut down.
65 * </p>
66 *
67 * @since Android 1.0
68 */
69public interface PooledConnection {
70
71    /**
72     * Registers the supplied {@code ConnectionEventListener} with this {@code
73     * PooledConnection}. Once registered, the {@code ConnectionEventListener}
74     * will receive {@link ConnectionEvent} events when they occur in the
75     * {@code PooledConnection}.
76     *
77     * @param theListener
78     *            an object which implements the {@code ConnectionEventListener}
79     *            interface.
80     * @since Android 1.0
81     */
82    public void addConnectionEventListener(ConnectionEventListener theListener);
83
84    /**
85     * Closes the connection to the database held by this {@code
86     * PooledConnection}. This method should not be called directly by
87     * application code - it is intended only for the connection pool manager
88     * component.
89     *
90     * @throws SQLException
91     *             if there is a problem accessing the database.
92     * @since Android 1.0
93     */
94    public void close() throws SQLException;
95
96    /**
97     * Creates a connection to the database. This method is typically called by
98     * the connection pool manager when an application invokes the method
99     * {@code DataSource.getConnection()} and there are no {@code
100     * PooledConnection} objects available in the connection pool.
101     *
102     * @return a {@code Connection} object.
103     * @throws SQLException
104     *             if there is a problem accessing the database.
105     * @since Android 1.0
106     */
107    public Connection getConnection() throws SQLException;
108
109    /**
110     * Unregisters the supplied {@code ConnectionEventListener} from this {@code
111     * PooledConnection}. Once unregistered, the {@code ConnectionEventListener}
112     * will no longer receive events occurring in the {@code PooledConnection}.
113     *
114     * @param theListener
115     *            an object which implements the {@code ConnectionEventListener}
116     *            interface. This object should have previously been registered
117     *            with the {@code PooledConnection} using the {@code
118     *            addConnectionEventListener} method.
119     * @since Android 1.0
120     */
121    public void removeConnectionEventListener(
122            ConnectionEventListener theListener);
123}
124