public Interface PooledDataSource

Most clients need never use or know about this interface -- c3p0 pooled DataSources can be treated like any other DataSource.

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' maxIdleTime, idleConnectionTestPeriod, or testConnectionOnCheckout 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.

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 Connection getConnection(String username, String password) rather than the no-argument getConnection() method. If users make use of non-default username, password combinations, there will be a separate pool for each set of authentification criteria supplied.

Many methods in this interface have three variants:

1. <method-name>DefaultUser()
2. <method-name>(String username, String password)
3. <method-name>AllUsers()

The first variant makes use of the pool maintained for the default user -- Connections created by calls to the no argument getConnection(), the second variant lets you keeps track of pools created by calling getConnection( username, password ), and the third variant provides aggregate information or performs operation on all pools.

Under most circumstances, non-default authentication credentials will not be used, and methods of the first variant are sufficient to manage the DataSource.

Soft and Hard Resets

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.

1. hardReset() 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.
   
   
2. softResetDefaultUser(), softReset( username, password ) and softResetAllUsers() asks the DataSource to flush its current pool of Connections and reacquire without 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 above to understand why there are three variants of this method.)

Understanding Connection Counts

For each per-user pool, four different statistics are available:

1. numConnections represents the total number of Connections in the pool.
   
   
2. numIdleConnections represents the number of Connections in the pool that are currently available for checkout.
   
   
3. numBusyConnections represents the number of Connections in the pool that are currently checked out. The invariant numIdleConnections + numBusyConnections == numConnections should always hold.
   
   
4. numUnclosedOrphanedConnections will only be non-zero following a call to softReset(). 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.