com.mchange.v2.c3p0
public interface PooledDataSource extends DataSource
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:
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.
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.
For each per-user pool, four different statistics are available:
Method Summary | |
---|---|
void | close() C3P0 pooled DataSources use no resources before they are actually used in a VM, and they close themselves in their finalize() method. |
void | close(boolean force_destory) Should be used only with great caution. |
int | getNumBusyConnections() |
int | getNumBusyConnections(String username, String password) |
int | getNumBusyConnectionsAllUsers() |
int | getNumBusyConnectionsDefaultUser() |
int | getNumConnections() |
int | getNumConnections(String username, String password) |
int | getNumConnectionsAllUsers() |
int | getNumConnectionsDefaultUser() |
int | getNumIdleConnections() |
int | getNumIdleConnections(String username, String password) |
int | getNumIdleConnectionsAllUsers() |
int | getNumIdleConnectionsDefaultUser() |
int | getNumUnclosedOrphanedConnections() |
int | getNumUnclosedOrphanedConnections(String username, String password) |
int | getNumUnclosedOrphanedConnectionsAllUsers() |
int | getNumUnclosedOrphanedConnectionsDefaultUser() |
int | getNumUserPools() |
void | hardReset()
Destroys all pooled and checked-out Connections associated with
this DataSource immediately. |
void | softReset(String username, String password)
Discards all Connections managed by the PooledDataSource with the specified authentication credentials
and reacquires new Connections to populate.
|
void | softResetAllUsers()
Discards all Connections managed by the PooledDataSource
and reacquires new Connections to populate.
|
void | softResetDefaultUser()
Discards all Connections managed by the PooledDataSource's default-authentication pool
and reacquires new Connections to populate.
|
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.
You can equivalently use the static method destroy() in the DataSources class to clean-up these resources.
This is equivalent to calling close( false ).
See Also: DataSources
Should be used only with great caution. If force_destroy is set to true, this immediately destroys any pool and cleans up all resources this DataSource may be using, even if other DataSources are sharing that pool! 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).
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.
To close a pool normally, use the no argument close method, or set force_destroy to false.
See Also: close
Deprecated: use getNumBusyConnectionsDefaultUser()
Deprecated: use getNumConnectionsDefaultUser()
Deprecated: use getNumIdleConnectionsDefaultUser()
Deprecated: use getNumUnclosedOrphanedConnectionsDefaultUser()