1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
/*
* 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);
}
|
