Package Tree Index Deprecated About
Prev Class | Next ClassFrames | No Frames
Summary: Nested | Field | Method | ConstrDetail: Nested | Field | Method | Constr

com.mchange.v2.c3p0

Interface PooledDataSource

All Superinterfaces:
DataSource
Known Implementing Classes:
ComboPooledDataSource, PoolBackedDataSource
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.

Method Names & Per-User Pools

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.

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)
Deprecated. the force_destroy argument is now meaningless, as pools are no longer potentially shared between multiple DataSources.
Collection
getAllUsers()
String
getDataSourceName()
float
getEffectivePropertyCycle(String username, String password)
float
getEffectivePropertyCycleDefaultUser()
String
getIdentityToken()
Throwable
getLastAcquisitionFailure(String username, String password)
Throwable
getLastAcquisitionFailureDefaultUser()
Throwable
getLastCheckinFailure(String username, String password)
Throwable
getLastCheckinFailureDefaultUser()
Throwable
getLastCheckoutFailure(String username, String password)
Throwable
getLastCheckoutFailureDefaultUser()
Throwable
getLastConnectionTestFailure(String username, String password)
Throwable
getLastConnectionTestFailureDefaultUser()
Throwable
getLastIdleTestFailure(String username, String password)
Throwable
getLastIdleTestFailureDefaultUser()
int
getNumBusyConnections()
Deprecated. use getNumBusyConnectionsDefaultUser()
int
getNumBusyConnections(String username, String password)
int
getNumBusyConnectionsAllUsers()
int
getNumBusyConnectionsDefaultUser()
int
getNumConnections()
Deprecated. use getNumConnectionsDefaultUser()
int
getNumConnections(String username, String password)
int
getNumConnectionsAllUsers()
int
getNumConnectionsDefaultUser()
long
getNumFailedCheckinsDefaultUser()
long
getNumFailedCheckoutsDefaultUser()
long
getNumFailedIdleTestsDefaultUser()
int
getNumHelperThreads()
int
getNumIdleConnections()
Deprecated. use getNumIdleConnectionsDefaultUser()
int
getNumIdleConnections(String username, String password)
int
getNumIdleConnectionsAllUsers()
int
getNumIdleConnectionsDefaultUser()
int
getNumThreadsAwaitingCheckout(String username, String password)
int
getNumThreadsAwaitingCheckoutDefaultUser()
int
getNumUnclosedOrphanedConnections()
Deprecated. use getNumUnclosedOrphanedConnectionsDefaultUser()
int
getNumUnclosedOrphanedConnections(String username, String password)
int
getNumUnclosedOrphanedConnectionsAllUsers()
int
getNumUnclosedOrphanedConnectionsDefaultUser()
int
getNumUserPools()
long
getStartTimeMillisDefaultUser()
int
getStatementCacheNumCheckedOut(String username, String password)
int
getStatementCacheNumCheckedOutDefaultUser()
int
getStatementCacheNumCheckedOutStatementsAllUsers()
int
getStatementCacheNumConnectionsWithCachedStatements(String username, String password)
int
getStatementCacheNumConnectionsWithCachedStatementsAllUsers()
int
getStatementCacheNumConnectionsWithCachedStatementsDefaultUser()
int
getStatementCacheNumStatements(String username, String password)
int
getStatementCacheNumStatementsAllUsers()
int
getStatementCacheNumStatementsDefaultUser()
int
getThreadPoolNumActiveThreads()
int
getThreadPoolNumIdleThreads()
int
getThreadPoolNumTasksPending()
int
getThreadPoolSize()
long
getUpTimeMillisDefaultUser()
void
hardReset()
Destroys all pooled and checked-out Connections associated with this DataSource immediately.
String
sampleLastAcquisitionFailureStackTrace(String username, String password)
String
sampleLastAcquisitionFailureStackTraceDefaultUser()
String
sampleLastCheckinFailureStackTrace(String username, String password)
String
sampleLastCheckinFailureStackTraceDefaultUser()
String
sampleLastCheckoutFailureStackTrace(String username, String password)
String
sampleLastCheckoutFailureStackTraceDefaultUser()
String
sampleLastConnectionTestFailureStackTrace(String username, String password)
String
sampleLastConnectionTestFailureStackTraceDefaultUser()
String
sampleLastIdleTestFailureStackTrace(String username, String password)
String
sampleLastIdleTestFailureStackTraceDefaultUser()
String
sampleStatementCacheStatus(String username, String password)
String
sampleStatementCacheStatusDefaultUser()
String
sampleThreadPoolStackTraces()
String
sampleThreadPoolStatus()
void
setDataSourceName(String dataSourceName)
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.

Method Details

close

public void close()
            throws SQLException
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.destroy(DataSource)

close

public void close(boolean force_destory)
            throws SQLException

Deprecated. the force_destroy argument is now meaningless, as pools are no longer potentially shared between multiple 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()

getAllUsers

public Collection getAllUsers()
            throws SQLException

getDataSourceName

public String getDataSourceName()

getEffectivePropertyCycle

public float getEffectivePropertyCycle(String username,
                                       String password)
            throws SQLException

getEffectivePropertyCycleDefaultUser

public float getEffectivePropertyCycleDefaultUser()
            throws SQLException

getIdentityToken

public String getIdentityToken()

getLastAcquisitionFailure

public Throwable getLastAcquisitionFailure(String username,
                                           String password)
            throws SQLException

getLastAcquisitionFailureDefaultUser

public Throwable getLastAcquisitionFailureDefaultUser()
            throws SQLException

getLastCheckinFailure

public Throwable getLastCheckinFailure(String username,
                                       String password)
            throws SQLException

getLastCheckinFailureDefaultUser

public Throwable getLastCheckinFailureDefaultUser()
            throws SQLException

getLastCheckoutFailure

public Throwable getLastCheckoutFailure(String username,
                                        String password)
            throws SQLException

getLastCheckoutFailureDefaultUser

public Throwable getLastCheckoutFailureDefaultUser()
            throws SQLException

getLastConnectionTestFailure

public Throwable getLastConnectionTestFailure(String username,
                                              String password)
            throws SQLException

getLastConnectionTestFailureDefaultUser

public Throwable getLastConnectionTestFailureDefaultUser()
            throws SQLException

getLastIdleTestFailure

public Throwable getLastIdleTestFailure(String username,
                                        String password)
            throws SQLException

getLastIdleTestFailureDefaultUser

public Throwable getLastIdleTestFailureDefaultUser()
            throws SQLException

getNumBusyConnections

public int getNumBusyConnections()
            throws SQLException

Deprecated. use getNumBusyConnectionsDefaultUser()

getNumBusyConnections

public int getNumBusyConnections(String username,
                                 String password)
            throws SQLException

getNumBusyConnectionsAllUsers

public int getNumBusyConnectionsAllUsers()
            throws SQLException

getNumBusyConnectionsDefaultUser

public int getNumBusyConnectionsDefaultUser()
            throws SQLException

getNumConnections

public int getNumConnections()
            throws SQLException

Deprecated. use getNumConnectionsDefaultUser()

getNumConnections

public int getNumConnections(String username,
                             String password)
            throws SQLException

getNumConnectionsAllUsers

public int getNumConnectionsAllUsers()
            throws SQLException

getNumConnectionsDefaultUser

public int getNumConnectionsDefaultUser()
            throws SQLException

getNumFailedCheckinsDefaultUser

public long getNumFailedCheckinsDefaultUser()
            throws SQLException

getNumFailedCheckoutsDefaultUser

public long getNumFailedCheckoutsDefaultUser()
            throws SQLException

getNumFailedIdleTestsDefaultUser

public long getNumFailedIdleTestsDefaultUser()
            throws SQLException

getNumHelperThreads

public int getNumHelperThreads()
            throws SQLException

getNumIdleConnections

public int getNumIdleConnections()
            throws SQLException

Deprecated. use getNumIdleConnectionsDefaultUser()

getNumIdleConnections

public int getNumIdleConnections(String username,
                                 String password)
            throws SQLException

getNumIdleConnectionsAllUsers

public int getNumIdleConnectionsAllUsers()
            throws SQLException

getNumIdleConnectionsDefaultUser

public int getNumIdleConnectionsDefaultUser()
            throws SQLException

getNumThreadsAwaitingCheckout

public int getNumThreadsAwaitingCheckout(String username,
                                         String password)
            throws SQLException

getNumThreadsAwaitingCheckoutDefaultUser

public int getNumThreadsAwaitingCheckoutDefaultUser()
            throws SQLException

getNumUnclosedOrphanedConnections

public int getNumUnclosedOrphanedConnections()
            throws SQLException

Deprecated. use getNumUnclosedOrphanedConnectionsDefaultUser()

getNumUnclosedOrphanedConnections

public int getNumUnclosedOrphanedConnections(String username,
                                             String password)
            throws SQLException

getNumUnclosedOrphanedConnectionsAllUsers

public int getNumUnclosedOrphanedConnectionsAllUsers()
            throws SQLException

getNumUnclosedOrphanedConnectionsDefaultUser

public int getNumUnclosedOrphanedConnectionsDefaultUser()
            throws SQLException

getNumUserPools

public int getNumUserPools()
            throws SQLException

getStartTimeMillisDefaultUser

public long getStartTimeMillisDefaultUser()
            throws SQLException

getStatementCacheNumCheckedOut

public int getStatementCacheNumCheckedOut(String username,
                                          String password)
            throws SQLException

getStatementCacheNumCheckedOutDefaultUser

public int getStatementCacheNumCheckedOutDefaultUser()
            throws SQLException

getStatementCacheNumCheckedOutStatementsAllUsers

public int getStatementCacheNumCheckedOutStatementsAllUsers()
            throws SQLException

getStatementCacheNumConnectionsWithCachedStatements

public int getStatementCacheNumConnectionsWithCachedStatements(String username,
                                                               String password)
            throws SQLException

getStatementCacheNumConnectionsWithCachedStatementsAllUsers

public int getStatementCacheNumConnectionsWithCachedStatementsAllUsers()
            throws SQLException

getStatementCacheNumConnectionsWithCachedStatementsDefaultUser

public int getStatementCacheNumConnectionsWithCachedStatementsDefaultUser()
            throws SQLException

getStatementCacheNumStatements

public int getStatementCacheNumStatements(String username,
                                          String password)
            throws SQLException

getStatementCacheNumStatementsAllUsers

public int getStatementCacheNumStatementsAllUsers()
            throws SQLException

getStatementCacheNumStatementsDefaultUser

public int getStatementCacheNumStatementsDefaultUser()
            throws SQLException

getThreadPoolNumActiveThreads

public int getThreadPoolNumActiveThreads()
            throws SQLException

getThreadPoolNumIdleThreads

public int getThreadPoolNumIdleThreads()
            throws SQLException

getThreadPoolNumTasksPending

public int getThreadPoolNumTasksPending()
            throws SQLException

getThreadPoolSize

public int getThreadPoolSize()
            throws SQLException

getUpTimeMillisDefaultUser

public long getUpTimeMillisDefaultUser()
            throws SQLException

hardReset

public void hardReset()
            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.

sampleLastAcquisitionFailureStackTrace

public String sampleLastAcquisitionFailureStackTrace(String username,
                                                     String password)
            throws SQLException

sampleLastAcquisitionFailureStackTraceDefaultUser

public String sampleLastAcquisitionFailureStackTraceDefaultUser()
            throws SQLException

sampleLastCheckinFailureStackTrace

public String sampleLastCheckinFailureStackTrace(String username,
                                                 String password)
            throws SQLException

sampleLastCheckinFailureStackTraceDefaultUser

public String sampleLastCheckinFailureStackTraceDefaultUser()
            throws SQLException

sampleLastCheckoutFailureStackTrace

public String sampleLastCheckoutFailureStackTrace(String username,
                                                  String password)
            throws SQLException

sampleLastCheckoutFailureStackTraceDefaultUser

public String sampleLastCheckoutFailureStackTraceDefaultUser()
            throws SQLException

sampleLastConnectionTestFailureStackTrace

public String sampleLastConnectionTestFailureStackTrace(String username,
                                                        String password)
            throws SQLException

sampleLastConnectionTestFailureStackTraceDefaultUser

public String sampleLastConnectionTestFailureStackTraceDefaultUser()
            throws SQLException

sampleLastIdleTestFailureStackTrace

public String sampleLastIdleTestFailureStackTrace(String username,
                                                  String password)
            throws SQLException

sampleLastIdleTestFailureStackTraceDefaultUser

public String sampleLastIdleTestFailureStackTraceDefaultUser()
            throws SQLException

sampleStatementCacheStatus

public String sampleStatementCacheStatus(String username,
                                         String password)
            throws SQLException

sampleStatementCacheStatusDefaultUser

public String sampleStatementCacheStatusDefaultUser()
            throws SQLException

sampleThreadPoolStackTraces

public String sampleThreadPoolStackTraces()
            throws SQLException

sampleThreadPoolStatus

public String sampleThreadPoolStatus()
            throws SQLException

setDataSourceName

public void setDataSourceName(String dataSourceName)

softReset

public void softReset(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).

softResetAllUsers

public void softResetAllUsers()
            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).

softResetDefaultUser

public void softResetDefaultUser()
            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).

Package Tree Index Deprecated About