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 18 package javax.sql; 19 20 import java.sql.Connection; 21 import java.sql.SQLException; 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 */ 62 public 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 /** 114 * Add a StatementEventListener to this PooledConnection object. 115 * 116 * @param listener 117 * A StatementEventListener object which is to be added with this 118 * PooledConnection object 119 * @since 1.6 120 */ 121 public void addStatementEventListener(StatementEventListener listener); 122 123 /** 124 * Remove a StatementEventListener from this PooledConnection object. 125 * 126 * @param listener 127 * A StatementEventListener object which is to be removed form 128 * this PooledConnection object 129 * @since 1.6 130 */ 131 public void removeStatementEventListener(StatementEventListener listener); 132 } 133
