pooleddatasource.java

c3p0数据库连接池实现源码

/*
 * Distributed as part of c3p0 v.0.9.1-pre6
 *
 * Copyright (C) 2005 Machinery For Change, Inc.
 *
 * Author: Steve Waldman <[e-mail]>
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 2.1, as 
 * published by the Free Software Foundation.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this software; see the file LICENSE.  If not, write to the
 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307, USA.
 */


package com.mchange.v2.c3p0;

import java.sql.SQLException;
import javax.sql.DataSource;
import java.util.Collection;

/**
 *  <p><b>Most clients need never use or know about this interface -- c3p0 pooled DataSources
 *  can be treated like any other DataSource.</b></p>
 *
 *  <p>The functionality in this interface will be only be of interest if 1) for administrative
 *  reasons you like to keep close track of the number and status of all Connections your application
 *  is using; 2) to work around problems encountered while managing a DataSource whose clients are
 *  poorly coded applications that leak Connections, but which you are not permitted to fix; 
 *  or 3) to work around problems that may occur if an underlying jdbc driver / DBMS system is
 *  unreliable. In the third case, most users will be better off not using the present interface
 *  at all, and using the DataSources' <tt>maxIdleTime</tt>, <tt>idleConnectionTestPeriod</tt>,
 *  or <tt>testConnectionOnCheckout</tt> parameters to help your DataSources "automatically" heal. 
 *  But for those who prefer a more direct, manual approach, this interface is for you. It is anticipated
 *  that the methods of this interface will primarily be of use to administrators managing c3p0
 *  PooledDataSources via JMX MBeans.</p>
 *
 *  <a name="peruserpools"><h3>Method Names & Per-User Pools</h3></a>
 *
 *  <p>To understand this interface, you need to realize that a c3p0 PooledDataSource may represent
 *  not just one pool of Connections, but many, if users call the method
 *  <tt>Connection getConnection(String username, String password)</tt> rather than the
 *  no-argument <tt>getConnection()</tt> method. If users make use of non-default username, password
 *  combinations, there will be a separate pool for each set of authentification criteria supplied.</p>
 *
 *  <p>Many methods in this interface have three variants:</p>
 *  <ol>
 *    <li><tt><i>&lt;method-name&gt;</i>DefaultUser()</tt></li>
 *    <li><tt><i>&lt;method-name&gt;</i>(String username, String password)</tt></li>
 *    <li><tt><i>&lt;method-name&gt;</i>AllUsers()</tt></li>
 *  </ol>
 *  <p>The first variant makes use of the pool maintained for the default user --
 *  Connections created by calls to the no argument <tt>getConnection()</tt>,
 *  the second variant lets you keeps track of pools created by calling 
 *  <tt>getConnection( <i>username</i>, <i>password</i> )</tt>, and the third variant
 *  provides aggregate information or performs operation on all pools.</p> 
 *
 *  <p>Under most circumstances, non-default authentication credentials will not
 *  be used, and methods of the first variant are sufficient to manage the DataSource.</p> 
 *
 *  <h3>Soft and Hard Resets</h3>
 *
 *  <p>A properly configured PooledDataSource whose applications are careful to close all checked-out Connections
 *  would never need to use these methods. But, sometimes applications are untrustworthy
 *  and leak Connections, or database administrators suspect that Connections may be corrupt or invalid,
 *  and would like to force a pool to flush and acquire fresh Connections. This interface provides two 
 *  ways to do so.</p>
 *
 *  <ol>
 *    <li><b><tt>hardReset()</tt></b> immediately closes all Connections managed by the DataSource, including
 *    those that are currently checked out, bringing the DataSource back to the state it was in before
 *    the first client called getConnection(). This method is obviously disruptive, and should be with
 *    great care. Administrators who need to work around client applications that leak Connections, can
 *    periodically poll for pool exhaustion (using the methods of this class, or by attempting to retrieve
 *    a Connection and timing out) and use this method clean-up all Connections and start over. But calling
 *    this method risks breaking Connections in current use by valid applications.<br/><br/></li>
 *
 *    <li><b><tt>softResetDefaultUser()</tt></b>, <b><tt>softReset( <i>username</i>, <i>password</i> )</tt></b> and
 *    <b><tt>softResetAllUsers()</tt></b> asks the DataSource to flush its current pool of Connections and
 *    reacquire <i>without</i> invalidating currently checked-out Connections. Currently checked out Connections
 *    are logically removed from the pool, but their destruction is deferred until a client attempts to close() / check-in
 *    the Connection. Administrators who suspect that some Connections in the pool may be invalid, but who do not
 *    wish to rely upon c3p0's automatic testing and detection mechanisms to resolve the problem, may call these
 *    methods to force a refresh without disrupting current clients. Administrators who suspect that clients may be
 *    leaking Connections may minimize disruptive hardReset() calls by using softReset() until the number of unclosed
 *    orphaned connections reaches an unacceptable level. (See <a href="#peruserpools">above</a> to understand
 *    why there are three variants of this method.)</li> 
 *  </ol>
 *
 *  <h3>Understanding Connection Counts</h3>
 *
 *  <p>For each <a href="#peruserpools">per-user pool</a>, four different statistics are available:</p>
 *
 *  <ol>
 *    <li><tt>numConnections</tt> represents the total number of Connections in the pool.<br/><br/></li>
 *    <li><tt>numIdleConnections</tt> represents the number of Connections in the pool that are currently available for checkout.<br/><br/></li> 
 *    <li><tt>numBusyConnections</tt> represents the number of Connections in the pool that are currently checked out. The
 *    invariant <tt>numIdleConnections + numBusyConnections == numConnections</tt> should always hold.<br/><br/></li>
 *    <li><tt>numUnclosedOrphanedConnections</tt> will only be non-zero following a call to <tt>softReset()</tt>. It represents
 *    the number of Connections that were checked out when a soft reset occurred and were therefore
 *    silently excluded from the pool, and which remain unclosed by the client application.</li>
 *  </ol>
 */
public interface PooledDataSource extends DataSource
{
    public String getIdentityToken();
    public String getDataSourceName();
    public void setDataSourceName(String dataSourceName);

    /** @deprecated use getNumConnectionsDefaultUser() */
    public int getNumConnections() throws SQLException;

    /** @deprecated use getNumIdleConnectionsDefaultUser() */
    public int getNumIdleConnections() throws SQLException;

    /** @deprecated use getNumBusyConnectionsDefaultUser() */
    public int getNumBusyConnections() throws SQLException;

    /** @deprecated use getNumUnclosedOrphanedConnectionsDefaultUser() */
    public int getNumUnclosedOrphanedConnections() throws SQLException;

    public int getNumConnectionsDefaultUser() throws SQLException;
    public int getNumIdleConnectionsDefaultUser() throws SQLException;
    public int getNumBusyConnectionsDefaultUser() throws SQLException;
    public int getNumUnclosedOrphanedConnectionsDefaultUser() throws SQLException;

    /**
     * Discards all Connections managed by the PooledDataSource's default-authentication pool
     * and reacquires new Connections to populate.
     * Current checked out Connections will still
     * be valid, and should still be checked into the
     * PooledDataSource (so the PooledDataSource can destroy 
     * them).
     */
    public void softResetDefaultUser() throws SQLException;

    public int getNumConnections(String username, String password) throws SQLException;
    public int getNumIdleConnections(String username, String password) throws SQLException;
    public int getNumBusyConnections(String username, String password) throws SQLException;
    public int getNumUnclosedOrphanedConnections(String username, String password) throws SQLException;

    /**
     * Discards all Connections managed by the PooledDataSource with the specified authentication credentials
     * and reacquires new Connections to populate.
     * Current checked out Connections will still
     * be valid, and should still be checked into the
     * PooledDataSource (so the PooledDataSource can destroy 
     * them).
     */
    public void softReset(String username, String password) throws SQLException;

    public int getNumBusyConnectionsAllUsers() throws SQLException;
    public int getNumIdleConnectionsAllUsers() throws SQLException;
    public int getNumConnectionsAllUsers() throws SQLException;
    public int getNumUnclosedOrphanedConnectionsAllUsers() throws SQLException;

    /**
     * Discards all Connections managed by the PooledDataSource
     * and reacquires new Connections to populate.
     * Current checked out Connections will still
     * be valid, and should still be checked into the
     * PooledDataSource (so the PooledDataSource can destroy 
     * them).
     */
    public void softResetAllUsers() throws SQLException;

    public int getNumUserPools() throws SQLException;

    public Collection getAllUsers() throws SQLException;

    /**
     * Destroys all pooled and checked-out Connections associated with
     * this DataSource immediately. The PooledDataSource is
     * reset to its initial state prior to first Connection acquisition,
     * with no pools yet active, but ready for requests.  
     */
    public void hardReset() throws SQLException;

    /**
     * <p>C3P0 pooled DataSources use no resources before they are actually used in a VM,
     * and they close themselves in their finalize() method. When they are active and
     * pooling, they may have open database connections and their pool may spawn several threads
     * for its maintenance. You can use this method to clean these resource methods up quickly
     * when you will no longer be using this DataSource. The resources will actually be cleaned up only if 
     * no other DataSources are sharing the same pool.</p>
     *
     * <p>You can equivalently use the static method destroy() in the DataSources class to clean-up
     * these resources.</p>
     *
     * <p>This is equivalent to calling close( false ).</p>
     *
     * @see DataSources#destroy
     */
    public void close() throws SQLException;

    /**
     * <p>Should be used only with great caution. If <tt>force_destroy</tt> is set to true,
     *    this immediately destroys any pool and cleans up all resources
     *    this DataSource may be using, <u><i>even if other DataSources are sharing that
     *    pool!</i></u> In general, it is difficult to know whether a pool is being shared by
     *    multiple DataSources. It may depend upon whether or not a JNDI implementation returns
     *    a single instance or multiple copies upon lookup (which is undefined by the JNDI spec).</p>
     *
     * <p>In general, this method should be used only when you wish to wind down all c3p0 pools
     *    in a ClassLoader. For example, when shutting down and restarting a web application
     *    that uses c3p0, you may wish to kill all threads making use of classes loaded by a 
     *    web-app specific ClassLoader, so that the ClassLoader can be cleanly garbage collected.
     *    In this case, you may wish to use force destroy. Otherwise, it is much safer to use
     *    the simple destroy() method, which will not shut down pools that may still be in use.</p>
     *
     * <p><b>To close a pool normally, use the no argument close method, or set <tt>force_destroy</tt>
     *    to false.</b></p>
     *
     *   @see #close()
     */
    public void close(boolean force_destory) throws SQLException;
}