PooledDataSource


1   /*
2    * Distributed as part of c3p0 v.0.9.1
3    *
4    * Copyright (C) 2005 Machinery For Change, Inc.
5    *
6    * Author: Steve Waldman <swaldman@mchange.com>
7    *
8    * This library is free software; you can redistribute it and/or modify
9    * it under the terms of the GNU Lesser General Public License version 2.1, as 
10   * published by the Free Software Foundation.
11   *
12   * This software is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   * GNU Lesser General Public License for more details.
16   *
17   * You should have received a copy of the GNU Lesser General Public License
18   * along with this software; see the file LICENSE.  If not, write to the
19   * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
20   * Boston, MA 02111-1307, USA.
21   */
22  
23  
24  package com.mchange.v2.c3p0;
25  
26  import java.sql.SQLException  ;
27  import javax.sql.DataSource  ;
28  import java.util.Collection  ;
29  
30  /**
31   *  <p><b>Most clients need never use or know about this interface -- c3p0 pooled DataSources
32   *  can be treated like any other DataSource.</b></p>
33   *
34   *  <p>The functionality in this interface will be only be of interest if 1) for administrative
35   *  reasons you like to keep close track of the number and status of all Connections your application
36   *  is using; 2) to work around problems encountered while managing a DataSource whose clients are
37   *  poorly coded applications that leak Connections, but which you are not permitted to fix; 
38   *  or 3) to work around problems that may occur if an underlying jdbc driver / DBMS system is
39   *  unreliable. In the third case, most users will be better off not using the present interface
40   *  at all, and using the DataSources' <tt>maxIdleTime</tt>, <tt>idleConnectionTestPeriod</tt>,
41   *  or <tt>testConnectionOnCheckout</tt> parameters to help your DataSources "automatically" heal. 
42   *  But for those who prefer a more direct, manual approach, this interface is for you. It is anticipated
43   *  that the methods of this interface will primarily be of use to administrators managing c3p0
44   *  PooledDataSources via JMX MBeans.</p>
45   *
46   *  <a name="peruserpools"><h3>Method Names & Per-User Pools</h3></a>
47   *
48   *  <p>To understand this interface, you need to realize that a c3p0 PooledDataSource may represent
49   *  not just one pool of Connections, but many, if users call the method
50   *  <tt>Connection getConnection(String username, String password)</tt> rather than the
51   *  no-argument <tt>getConnection()</tt> method. If users make use of non-default username, password
52   *  combinations, there will be a separate pool for each set of authentification criteria supplied.</p>
53   *
54   *  <p>Many methods in this interface have three variants:</p>
55   *  <ol>
56   *    <li><tt><i>&lt;method-name&gt;</i>DefaultUser()</tt></li>
57   *    <li><tt><i>&lt;method-name&gt;</i>(String username, String password)</tt></li>
58   *    <li><tt><i>&lt;method-name&gt;</i>AllUsers()</tt></li>
59   *  </ol>
60   *  <p>The first variant makes use of the pool maintained for the default user --
61   *  Connections created by calls to the no argument <tt>getConnection()</tt>,
62   *  the second variant lets you keeps track of pools created by calling 
63   *  <tt>getConnection( <i>username</i>, <i>password</i> )</tt>, and the third variant
64   *  provides aggregate information or performs operation on all pools.</p> 
65   *
66   *  <p>Under most circumstances, non-default authentication credentials will not
67   *  be used, and methods of the first variant are sufficient to manage the DataSource.</p> 
68   *
69   *  <h3>Soft and Hard Resets</h3>
70   *
71   *  <p>A properly configured PooledDataSource whose applications are careful to close all checked-out Connections
72   *  would never need to use these methods. But, sometimes applications are untrustworthy
73   *  and leak Connections, or database administrators suspect that Connections may be corrupt or invalid,
74   *  and would like to force a pool to flush and acquire fresh Connections. This interface provides two 
75   *  ways to do so.</p>
76   *
77   *  <ol>
78   *    <li><b><tt>hardReset()</tt></b> immediately closes all Connections managed by the DataSource, including
79   *    those that are currently checked out, bringing the DataSource back to the state it was in before
80   *    the first client called getConnection(). This method is obviously disruptive, and should be with
81   *    great care. Administrators who need to work around client applications that leak Connections, can
82   *    periodically poll for pool exhaustion (using the methods of this class, or by attempting to retrieve
83   *    a Connection and timing out) and use this method clean-up all Connections and start over. But calling
84   *    this method risks breaking Connections in current use by valid applications.<br/><br/></li>
85   *
86   *    <li><b><tt>softResetDefaultUser()</tt></b>, <b><tt>softReset( <i>username</i>, <i>password</i> )</tt></b> and
87   *    <b><tt>softResetAllUsers()</tt></b> asks the DataSource to flush its current pool of Connections and
88   *    reacquire <i>without</i> invalidating currently checked-out Connections. Currently checked out Connections
89   *    are logically removed from the pool, but their destruction is deferred until a client attempts to close() / check-in
90   *    the Connection. Administrators who suspect that some Connections in the pool may be invalid, but who do not
91   *    wish to rely upon c3p0's automatic testing and detection mechanisms to resolve the problem, may call these
92   *    methods to force a refresh without disrupting current clients. Administrators who suspect that clients may be
93   *    leaking Connections may minimize disruptive hardReset() calls by using softReset() until the number of unclosed
94   *    orphaned connections reaches an unacceptable level. (See <a HREF="#peruserpools">above</a> to understand
95   *    why there are three variants of this method.)</li> 
96   *  </ol>
97   *
98   *  <h3>Understanding Connection Counts</h3>
99   *
100  *  <p>For each <a HREF="#peruserpools">per-user pool</a>, four different statistics are available:</p>
101  *
102  *  <ol>
103  *    <li><tt>numConnections</tt> represents the total number of Connections in the pool.<br/><br/></li>
104  *    <li><tt>numIdleConnections</tt> represents the number of Connections in the pool that are currently available for checkout.<br/><br/></li> 
105  *    <li><tt>numBusyConnections</tt> represents the number of Connections in the pool that are currently checked out. The
106  *    invariant <tt>numIdleConnections + numBusyConnections == numConnections</tt> should always hold.<br/><br/></li>
107  *    <li><tt>numUnclosedOrphanedConnections</tt> will only be non-zero following a call to <tt>softReset()</tt>. It represents
108  *    the number of Connections that were checked out when a soft reset occurred and were therefore
109  *    silently excluded from the pool, and which remain unclosed by the client application.</li>
110  *  </ol>
111  */
112 public interface PooledDataSource extends DataSource  
113 {
114     public String   getIdentityToken();
115     public String   getDataSourceName();
116     public void setDataSourceName(String   dataSourceName);
117 
118     /** @deprecated use getNumConnectionsDefaultUser() */
119     public int getNumConnections() throws SQLException  ;
120 
121     /** @deprecated use getNumIdleConnectionsDefaultUser() */
122     public int getNumIdleConnections() throws SQLException  ;
123 
124     /** @deprecated use getNumBusyConnectionsDefaultUser() */
125     public int getNumBusyConnections() throws SQLException  ;
126 
127     /** @deprecated use getNumUnclosedOrphanedConnectionsDefaultUser() */
128     public int getNumUnclosedOrphanedConnections() throws SQLException  ;
129 
130     public int getNumConnectionsDefaultUser() throws SQLException  ;
131     public int getNumIdleConnectionsDefaultUser() throws SQLException  ;
132     public int getNumBusyConnectionsDefaultUser() throws SQLException  ;
133     public int getNumUnclosedOrphanedConnectionsDefaultUser() throws SQLException  ;
134     public int getStatementCacheNumStatementsDefaultUser() throws SQLException  ;
135     public int getStatementCacheNumCheckedOutDefaultUser() throws SQLException  ;
136     public int getStatementCacheNumConnectionsWithCachedStatementsDefaultUser() throws SQLException  ;
137     public long getStartTimeMillisDefaultUser() throws SQLException  ;
138     public long getUpTimeMillisDefaultUser() throws SQLException  ;
139     public long getNumFailedCheckinsDefaultUser() throws SQLException  ;
140     public long getNumFailedCheckoutsDefaultUser() throws SQLException  ;
141     public long getNumFailedIdleTestsDefaultUser() throws SQLException  ;
142     public float getEffectivePropertyCycleDefaultUser() throws SQLException  ;
143     public int getNumThreadsAwaitingCheckoutDefaultUser() throws SQLException  ;
144 
145     /**
146      * Discards all Connections managed by the PooledDataSource's default-authentication pool
147      * and reacquires new Connections to populate.
148      * Current checked out Connections will still
149      * be valid, and should still be checked into the
150      * PooledDataSource (so the PooledDataSource can destroy 
151      * them).
152      */
153     public void softResetDefaultUser() throws SQLException  ;
154 
155     public int getNumConnections(String   username, String   password) throws SQLException  ;
156     public int getNumIdleConnections(String   username, String   password) throws SQLException  ;
157     public int getNumBusyConnections(String   username, String   password) throws SQLException  ;
158     public int getNumUnclosedOrphanedConnections(String   username, String   password) throws SQLException  ;
159     public int getStatementCacheNumStatements(String   username, String   password) throws SQLException  ;
160     public int getStatementCacheNumCheckedOut(String   username, String   password) throws SQLException  ;
161     public int getStatementCacheNumConnectionsWithCachedStatements(String   username, String   password) throws SQLException  ;
162     public float getEffectivePropertyCycle(String   username, String   password) throws SQLException  ;
163     public int getNumThreadsAwaitingCheckout(String   username, String   password) throws SQLException  ;
164 
165     /**
166      * Discards all Connections managed by the PooledDataSource with the specified authentication credentials
167      * and reacquires new Connections to populate.
168      * Current checked out Connections will still
169      * be valid, and should still be checked into the
170      * PooledDataSource (so the PooledDataSource can destroy 
171      * them).
172      */
173     public void softReset(String   username, String   password) throws SQLException  ;
174 
175     public int getNumBusyConnectionsAllUsers() throws SQLException  ;
176     public int getNumIdleConnectionsAllUsers() throws SQLException  ;
177     public int getNumConnectionsAllUsers() throws SQLException  ;
178     public int getNumUnclosedOrphanedConnectionsAllUsers() throws SQLException  ;
179 
180     public int getStatementCacheNumStatementsAllUsers() throws SQLException  ;
181     public int getStatementCacheNumCheckedOutStatementsAllUsers() throws SQLException  ;
182     public int getStatementCacheNumConnectionsWithCachedStatementsAllUsers() throws SQLException  ;
183 
184     public int getThreadPoolSize() throws SQLException  ;
185     public int getThreadPoolNumActiveThreads() throws SQLException  ;
186     public int getThreadPoolNumIdleThreads() throws SQLException  ;
187     public int getThreadPoolNumTasksPending() throws SQLException  ;
188 
189     public String   sampleThreadPoolStackTraces() throws SQLException  ;
190     public String   sampleThreadPoolStatus() throws SQLException  ;
191 
192     public String   sampleStatementCacheStatusDefaultUser() throws SQLException  ;
193     public String   sampleStatementCacheStatus(String   username, String   password) throws SQLException  ;
194     
195     public Throwable   getLastAcquisitionFailureDefaultUser() throws SQLException  ;
196     public Throwable   getLastCheckinFailureDefaultUser() throws SQLException  ;
197     public Throwable   getLastCheckoutFailureDefaultUser() throws SQLException  ;
198     public Throwable   getLastIdleTestFailureDefaultUser() throws SQLException  ;
199     public Throwable   getLastConnectionTestFailureDefaultUser() throws SQLException  ;
200     
201     public Throwable   getLastAcquisitionFailure(String   username, String   password) throws SQLException  ;
202     public Throwable   getLastCheckinFailure(String   username, String   password) throws SQLException  ;
203     public Throwable   getLastCheckoutFailure(String   username, String   password) throws SQLException  ;
204     public Throwable   getLastIdleTestFailure(String   username, String   password) throws SQLException  ;
205     public Throwable   getLastConnectionTestFailure(String   username, String   password) throws SQLException  ;
206     
207     public String   sampleLastAcquisitionFailureStackTraceDefaultUser() throws SQLException  ;
208     public String   sampleLastCheckinFailureStackTraceDefaultUser() throws SQLException  ;
209     public String   sampleLastCheckoutFailureStackTraceDefaultUser() throws SQLException  ;
210     public String   sampleLastIdleTestFailureStackTraceDefaultUser() throws SQLException  ;
211     public String   sampleLastConnectionTestFailureStackTraceDefaultUser() throws SQLException  ;
212     
213     public String   sampleLastAcquisitionFailureStackTrace(String   username, String   password) throws SQLException  ;
214     public String   sampleLastCheckinFailureStackTrace(String   username, String   password) throws SQLException  ;
215     public String   sampleLastCheckoutFailureStackTrace(String   username, String   password) throws SQLException  ;
216     public String   sampleLastIdleTestFailureStackTrace(String   username, String   password) throws SQLException  ;
217     public String   sampleLastConnectionTestFailureStackTrace(String   username, String   password) throws SQLException  ;
218 
219     /**
220      * Discards all Connections managed by the PooledDataSource
221      * and reacquires new Connections to populate.
222      * Current checked out Connections will still
223      * be valid, and should still be checked into the
224      * PooledDataSource (so the PooledDataSource can destroy 
225      * them).
226      */
227     public void softResetAllUsers() throws SQLException  ;
228 
229     public int getNumUserPools() throws SQLException  ;
230     public int getNumHelperThreads() throws SQLException  ;
231 
232     public Collection   getAllUsers() throws SQLException  ;
233 
234     /**
235      * Destroys all pooled and checked-out Connections associated with
236      * this DataSource immediately. The PooledDataSource is
237      * reset to its initial state prior to first Connection acquisition,
238      * with no pools yet active, but ready for requests.  
239      */
240     public void hardReset() throws SQLException  ;
241 
242     /**
243      * <p>C3P0 pooled DataSources use no resources before they are actually used in a VM,
244      * and they close themselves in their finalize() method. When they are active and
245      * pooling, they may have open database connections and their pool may spawn several threads
246      * for its maintenance. You can use this method to clean these resource methods up quickly
247      * when you will no longer be using this DataSource. The resources will actually be cleaned up only if 
248      * no other DataSources are sharing the same pool.</p>
249      *
250      * <p>You can equivalently use the static method destroy() in the DataSources class to clean-up
251      * these resources.</p>
252      *
253      * <p>This is equivalent to calling close( false ).</p>
254      *
255      * @see DataSources#destroy
256      */
257     public void close() throws SQLException  ;
258 
259     /**
260      * <p>Should be used only with great caution. If <tt>force_destroy</tt> is set to true,
261      *    this immediately destroys any pool and cleans up all resources
262      *    this DataSource may be using, <u><i>even if other DataSources are sharing that
263      *    pool!</i></u> In general, it is difficult to know whether a pool is being shared by
264      *    multiple DataSources. It may depend upon whether or not a JNDI implementation returns
265      *    a single instance or multiple copies upon lookup (which is undefined by the JNDI spec).</p>
266      *
267      * <p>In general, this method should be used only when you wish to wind down all c3p0 pools
268      *    in a ClassLoader. For example, when shutting down and restarting a web application
269      *    that uses c3p0, you may wish to kill all threads making use of classes loaded by a 
270      *    web-app specific ClassLoader, so that the ClassLoader can be cleanly garbage collected.
271      *    In this case, you may wish to use force destroy. Otherwise, it is much safer to use
272      *    the simple destroy() method, which will not shut down pools that may still be in use.</p>
273      *
274      * <p><b>To close a pool normally, use the no argument close method, or set <tt>force_destroy</tt>
275      *    to false.</b></p>
276      *    
277      *  @deprecated the force_destroy argument is now meaningless, as pools are no longer
278      *              potentially shared between multiple DataSources.
279      *
280      *  @see #close()
281      */
282     public void close(boolean force_destory) throws SQLException  ;
283 }
284
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags