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