Package com.mchange.v2.c3p0

Interface PooledDataSource

  • All Superinterfaces:
    java.lang.AutoCloseable, javax.sql.CommonDataSource, javax.sql.DataSource, java.sql.Wrapper
    All Known Implementing Classes:
    AbstractComboPooledDataSource, AbstractPoolBackedDataSource, AfterCloseLoggingComboPooledDataSource, CloseLoggingComboPooledDataSource, ComboPooledDataSource, ConstructionLoggingComboPooledDataSource, PoolBackedDataSource
    public interface PooledDataSource
extends javax.sql.DataSource, java.lang.AutoCloseable

    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 Detail

      • getIdentityToken

        java.lang.String getIdentityToken()

      • getDataSourceName

        java.lang.String getDataSourceName()

      • setDataSourceName

        void setDataSourceName​(java.lang.String dataSourceName)

      • getExtensions

        java.util.Map getExtensions()

      • setExtensions

        void setExtensions​(java.util.Map extensions)

      • getNumConnections

        int getNumConnections()
               throws java.sql.SQLException
        Deprecated.
        use getNumConnectionsDefaultUser()
        Throws:
        java.sql.SQLException

      • getNumIdleConnections

        int getNumIdleConnections()
                   throws java.sql.SQLException
        Deprecated.
        use getNumIdleConnectionsDefaultUser()
        Throws:
        java.sql.SQLException

      • getNumBusyConnections

        int getNumBusyConnections()
                   throws java.sql.SQLException
        Deprecated.
        use getNumBusyConnectionsDefaultUser()
        Throws:
        java.sql.SQLException

      • getNumUnclosedOrphanedConnections

        int getNumUnclosedOrphanedConnections()
                               throws java.sql.SQLException
        Deprecated.
        use getNumUnclosedOrphanedConnectionsDefaultUser()
        Throws:
        java.sql.SQLException

      • getNumConnectionsDefaultUser

        int getNumConnectionsDefaultUser()
                          throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumIdleConnectionsDefaultUser

        int getNumIdleConnectionsDefaultUser()
                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumBusyConnectionsDefaultUser

        int getNumBusyConnectionsDefaultUser()
                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumUnclosedOrphanedConnectionsDefaultUser

        int getNumUnclosedOrphanedConnectionsDefaultUser()
                                          throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumStatementsDefaultUser

        int getStatementCacheNumStatementsDefaultUser()
                                       throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumCheckedOutDefaultUser

        int getStatementCacheNumCheckedOutDefaultUser()
                                       throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumConnectionsWithCachedStatementsDefaultUser

        int getStatementCacheNumConnectionsWithCachedStatementsDefaultUser()
                                                            throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStartTimeMillisDefaultUser

        long getStartTimeMillisDefaultUser()
                            throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getUpTimeMillisDefaultUser

        long getUpTimeMillisDefaultUser()
                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumFailedCheckinsDefaultUser

        long getNumFailedCheckinsDefaultUser()
                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumFailedCheckoutsDefaultUser

        long getNumFailedCheckoutsDefaultUser()
                               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumFailedIdleTestsDefaultUser

        long getNumFailedIdleTestsDefaultUser()
                               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getEffectivePropertyCycleDefaultUser

        float getEffectivePropertyCycleDefaultUser()
                                    throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumThreadsAwaitingCheckoutDefaultUser

        int getNumThreadsAwaitingCheckoutDefaultUser()
                                      throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • softResetDefaultUser

        void softResetDefaultUser()
                   throws java.sql.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).
        Throws:
        java.sql.SQLException

      • getNumConnections

        int getNumConnections​(java.lang.String username,
                      java.lang.String password)
               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumIdleConnections

        int getNumIdleConnections​(java.lang.String username,
                          java.lang.String password)
                   throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumBusyConnections

        int getNumBusyConnections​(java.lang.String username,
                          java.lang.String password)
                   throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumUnclosedOrphanedConnections

        int getNumUnclosedOrphanedConnections​(java.lang.String username,
                                      java.lang.String password)
                               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumStatements

        int getStatementCacheNumStatements​(java.lang.String username,
                                   java.lang.String password)
                            throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumCheckedOut

        int getStatementCacheNumCheckedOut​(java.lang.String username,
                                   java.lang.String password)
                            throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumConnectionsWithCachedStatements

        int getStatementCacheNumConnectionsWithCachedStatements​(java.lang.String username,
                                                        java.lang.String password)
                                                 throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getEffectivePropertyCycle

        float getEffectivePropertyCycle​(java.lang.String username,
                                java.lang.String password)
                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumThreadsAwaitingCheckout

        int getNumThreadsAwaitingCheckout​(java.lang.String username,
                                  java.lang.String password)
                           throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • softReset

        void softReset​(java.lang.String username,
               java.lang.String password)
        throws java.sql.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).
        Throws:
        java.sql.SQLException

      • getNumBusyConnectionsAllUsers

        int getNumBusyConnectionsAllUsers()
                           throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumIdleConnectionsAllUsers

        int getNumIdleConnectionsAllUsers()
                           throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumConnectionsAllUsers

        int getNumConnectionsAllUsers()
                       throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumUnclosedOrphanedConnectionsAllUsers

        int getNumUnclosedOrphanedConnectionsAllUsers()
                                       throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumStatementsAllUsers

        int getStatementCacheNumStatementsAllUsers()
                                    throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumCheckedOutStatementsAllUsers

        int getStatementCacheNumCheckedOutStatementsAllUsers()
                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementCacheNumConnectionsWithCachedStatementsAllUsers

        int getStatementCacheNumConnectionsWithCachedStatementsAllUsers()
                                                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumConnectionsInUseAllUsers

        int getStatementDestroyerNumConnectionsInUseAllUsers()
                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumConnectionsWithDeferredDestroyStatementsAllUsers

        int getStatementDestroyerNumConnectionsWithDeferredDestroyStatementsAllUsers()
                                                                      throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumDeferredDestroyStatementsAllUsers

        int getStatementDestroyerNumDeferredDestroyStatementsAllUsers()
                                                       throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getThreadPoolSize

        int getThreadPoolSize()
               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getThreadPoolNumActiveThreads

        int getThreadPoolNumActiveThreads()
                           throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getThreadPoolNumIdleThreads

        int getThreadPoolNumIdleThreads()
                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getThreadPoolNumTasksPending

        int getThreadPoolNumTasksPending()
                          throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumThreads

        int getStatementDestroyerNumThreads()
                             throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumActiveThreads

        int getStatementDestroyerNumActiveThreads()
                                   throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumIdleThreads

        int getStatementDestroyerNumIdleThreads()
                                 throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumTasksPending

        int getStatementDestroyerNumTasksPending()
                                  throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleThreadPoolStackTraces

        java.lang.String sampleThreadPoolStackTraces()
                                      throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleThreadPoolStatus

        java.lang.String sampleThreadPoolStatus()
                                 throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleStatementDestroyerStackTraces

        java.lang.String sampleStatementDestroyerStackTraces()
                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleStatementDestroyerStatus

        java.lang.String sampleStatementDestroyerStatus()
                                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleStatementCacheStatusDefaultUser

        java.lang.String sampleStatementCacheStatusDefaultUser()
                                                throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleStatementCacheStatus

        java.lang.String sampleStatementCacheStatus​(java.lang.String username,
                                            java.lang.String password)
                                     throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastAcquisitionFailureDefaultUser

        java.lang.Throwable getLastAcquisitionFailureDefaultUser()
                                                  throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastCheckinFailureDefaultUser

        java.lang.Throwable getLastCheckinFailureDefaultUser()
                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastCheckoutFailureDefaultUser

        java.lang.Throwable getLastCheckoutFailureDefaultUser()
                                               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastIdleTestFailureDefaultUser

        java.lang.Throwable getLastIdleTestFailureDefaultUser()
                                               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastConnectionTestFailureDefaultUser

        java.lang.Throwable getLastConnectionTestFailureDefaultUser()
                                                     throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumConnectionsInUseDefaultUser

        int getStatementDestroyerNumConnectionsInUseDefaultUser()
                                                 throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumConnectionsWithDeferredDestroyStatementsDefaultUser

        int getStatementDestroyerNumConnectionsWithDeferredDestroyStatementsDefaultUser()
                                                                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumDeferredDestroyStatementsDefaultUser

        int getStatementDestroyerNumDeferredDestroyStatementsDefaultUser()
                                                          throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastAcquisitionFailure

        java.lang.Throwable getLastAcquisitionFailure​(java.lang.String username,
                                              java.lang.String password)
                                       throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastCheckinFailure

        java.lang.Throwable getLastCheckinFailure​(java.lang.String username,
                                          java.lang.String password)
                                   throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastCheckoutFailure

        java.lang.Throwable getLastCheckoutFailure​(java.lang.String username,
                                           java.lang.String password)
                                    throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastIdleTestFailure

        java.lang.Throwable getLastIdleTestFailure​(java.lang.String username,
                                           java.lang.String password)
                                    throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getLastConnectionTestFailure

        java.lang.Throwable getLastConnectionTestFailure​(java.lang.String username,
                                                 java.lang.String password)
                                          throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumConnectionsInUse

        int getStatementDestroyerNumConnectionsInUse​(java.lang.String username,
                                             java.lang.String password)
                                      throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumConnectionsWithDeferredDestroyStatements

        int getStatementDestroyerNumConnectionsWithDeferredDestroyStatements​(java.lang.String username,
                                                                     java.lang.String password)
                                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getStatementDestroyerNumDeferredDestroyStatements

        int getStatementDestroyerNumDeferredDestroyStatements​(java.lang.String username,
                                                      java.lang.String password)
                                               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastAcquisitionFailureStackTraceDefaultUser

        java.lang.String sampleLastAcquisitionFailureStackTraceDefaultUser()
                                                            throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastCheckinFailureStackTraceDefaultUser

        java.lang.String sampleLastCheckinFailureStackTraceDefaultUser()
                                                        throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastCheckoutFailureStackTraceDefaultUser

        java.lang.String sampleLastCheckoutFailureStackTraceDefaultUser()
                                                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastIdleTestFailureStackTraceDefaultUser

        java.lang.String sampleLastIdleTestFailureStackTraceDefaultUser()
                                                         throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastConnectionTestFailureStackTraceDefaultUser

        java.lang.String sampleLastConnectionTestFailureStackTraceDefaultUser()
                                                               throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastAcquisitionFailureStackTrace

        java.lang.String sampleLastAcquisitionFailureStackTrace​(java.lang.String username,
                                                        java.lang.String password)
                                                 throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastCheckinFailureStackTrace

        java.lang.String sampleLastCheckinFailureStackTrace​(java.lang.String username,
                                                    java.lang.String password)
                                             throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastCheckoutFailureStackTrace

        java.lang.String sampleLastCheckoutFailureStackTrace​(java.lang.String username,
                                                     java.lang.String password)
                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastIdleTestFailureStackTrace

        java.lang.String sampleLastIdleTestFailureStackTrace​(java.lang.String username,
                                                     java.lang.String password)
                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • sampleLastConnectionTestFailureStackTrace

        java.lang.String sampleLastConnectionTestFailureStackTrace​(java.lang.String username,
                                                           java.lang.String password)
                                                    throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • softResetAllUsers

        void softResetAllUsers()
                throws java.sql.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).
        Throws:
        java.sql.SQLException

      • getNumUserPools

        int getNumUserPools()
             throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getNumHelperThreads

        int getNumHelperThreads()
                 throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getAllUsers

        java.util.Collection getAllUsers()
                          throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • hardReset

        void hardReset()
        throws java.sql.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.
        Throws:
        java.sql.SQLException

      • close

        void close()
    throws java.sql.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 ).

        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        java.sql.SQLException
        See Also:
        DataSources.destroy(javax.sql.DataSource)

      • close

        void close​(boolean force_destory)
    throws java.sql.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.

        Throws:
        java.sql.SQLException
        See Also:
        close()