libcore/luni/src/main/java/javax/sql/PooledConnection.java

   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 }