View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.pool.impl;
19  
20  import java.util.ArrayList;
21  import java.util.Collection;
22  import java.util.Iterator;
23  import java.util.LinkedList;
24  import java.util.List;
25  import java.util.NoSuchElementException;
26  import java.util.TimerTask;
27  
28  import org.apache.commons.pool.BaseObjectPool;
29  import org.apache.commons.pool.ObjectPool;
30  import org.apache.commons.pool.PoolableObjectFactory;
31  import org.apache.commons.pool.impl.GenericKeyedObjectPool.ObjectTimestampPair;
32  
33  /**
34   * A configurable {@link ObjectPool} implementation.
35   * <p>
36   * When coupled with the appropriate {@link PoolableObjectFactory},
37   * <tt>GenericObjectPool</tt> provides robust pooling functionality for
38   * arbitrary objects.
39   * <p>
40   * A <tt>GenericObjectPool</tt> provides a number of configurable parameters:
41   * <ul>
42   *  <li>
43   *    {@link #setMaxActive <i>maxActive</i>} controls the maximum number of
44   *    objects that can be allocated by the pool (checked out to clients, or
45   *    idle awaiting checkout) at a given time.  When non-positive, there is no
46   *    limit to the number of objects that can be managed by the pool at one time.
47   *    When {@link #setMaxActive <i>maxActive</i>} is reached, the pool is said
48   *    to be exhausted. The default setting for this parameter is 8.
49   *  </li>
50   *  <li>
51   *    {@link #setMaxIdle <i>maxIdle</i>} controls the maximum number of objects
52   *    that can sit idle in the pool at any time.  When negative, there is no
53   *    limit to the number of objects that may be idle at one time. The default
54   *    setting for this parameter is 8.
55   *  </li>
56   *  <li>
57   *    {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} specifies the
58   *    behavior of the {@link #borrowObject} method when the pool is exhausted:
59   *    <ul>
60   *    <li>
61   *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} is
62   *      {@link #WHEN_EXHAUSTED_FAIL}, {@link #borrowObject} will throw
63   *      a {@link NoSuchElementException}
64   *    </li>
65   *    <li>
66   *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} is
67   *      {@link #WHEN_EXHAUSTED_GROW}, {@link #borrowObject} will create a new
68   *      object and return it (essentially making {@link #setMaxActive <i>maxActive</i>}
69   *      meaningless.)
70   *    </li>
71   *    <li>
72   *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>}
73   *      is {@link #WHEN_EXHAUSTED_BLOCK}, {@link #borrowObject} will block
74   *      (invoke {@link Object#wait()}) until a new or idle object is available.
75   *      If a positive {@link #setMaxWait <i>maxWait</i>}
76   *      value is supplied, then {@link #borrowObject} will block for at
77   *      most that many milliseconds, after which a {@link NoSuchElementException}
78   *      will be thrown.  If {@link #setMaxWait <i>maxWait</i>} is non-positive,
79   *      the {@link #borrowObject} method will block indefinitely.
80   *    </li>
81   *    </ul>
82   *    The default <code>whenExhaustedAction</code> setting is
83   *    {@link #WHEN_EXHAUSTED_BLOCK} and the default <code>maxWait</code>
84   *    setting is -1. By default, therefore, <code>borrowObject</code> will
85   *    block indefinitely until an idle instance becomes available.
86   *  </li>
87   *  <li>
88   *    When {@link #setTestOnBorrow <i>testOnBorrow</i>} is set, the pool will
89   *    attempt to validate each object before it is returned from the
90   *    {@link #borrowObject} method. (Using the provided factory's
91   *    {@link PoolableObjectFactory#validateObject} method.)  Objects that fail
92   *    to validate will be dropped from the pool, and a different object will
93   *    be borrowed. The default setting for this parameter is
94   *    <code>false.</code>
95   *  </li>
96   *  <li>
97   *    When {@link #setTestOnReturn <i>testOnReturn</i>} is set, the pool will
98   *    attempt to validate each object before it is returned to the pool in the
99   *    {@link #returnObject} method. (Using the provided factory's
100  *    {@link PoolableObjectFactory#validateObject}
101  *    method.)  Objects that fail to validate will be dropped from the pool.
102  *    The default setting for this parameter is <code>false.</code>
103  *  </li>
104  * </ul>
105  * <p>
106  * Optionally, one may configure the pool to examine and possibly evict objects
107  * as they sit idle in the pool and to ensure that a minimum number of idle
108  * objects are available. This is performed by an "idle object eviction"
109  * thread, which runs asynchronously. Caution should be used when configuring
110  * this optional feature. Eviction runs require an exclusive synchronization
111  * lock on the pool, so if they run too frequently and / or incur excessive
112  * latency when creating, destroying or validating object instances,
113  * performance issues may result.  The idle object eviction thread may be
114  * configured using the following attributes:
115  * <ul>
116  *  <li>
117  *   {@link #setTimeBetweenEvictionRunsMillis <i>timeBetweenEvictionRunsMillis</i>}
118  *   indicates how long the eviction thread should sleep before "runs" of examining
119  *   idle objects.  When non-positive, no eviction thread will be launched. The
120  *   default setting for this parameter is -1 (i.e., idle object eviction is
121  *   disabled by default).
122  *  </li>
123  *  <li>
124  *   {@link #setMinEvictableIdleTimeMillis <i>minEvictableIdleTimeMillis</i>}
125  *   specifies the minimum amount of time that an object may sit idle in the pool
126  *   before it is eligible for eviction due to idle time.  When non-positive, no object
127  *   will be dropped from the pool due to idle time alone. This setting has no
128  *   effect unless <code>timeBetweenEvictionRunsMillis > 0.</code> The default
129  *   setting for this parameter is 30 minutes.
130  *  </li>
131  *  <li>
132  *   {@link #setTestWhileIdle <i>testWhileIdle</i>} indicates whether or not idle
133  *   objects should be validated using the factory's
134  *   {@link PoolableObjectFactory#validateObject} method. Objects that fail to
135  *   validate will be dropped from the pool. This setting has no effect unless
136  *   <code>timeBetweenEvictionRunsMillis > 0.</code>  The default setting for
137  *   this parameter is <code>false.</code>
138  *  </li>
139  *  <li>
140  *   {@link #setSoftMinEvictableIdleTimeMillis <i>softMinEvictableIdleTimeMillis</i>}
141  *   specifies the minimum amount of time an object may sit idle in the pool
142  *   before it is eligible for eviction by the idle object evictor
143  *   (if any), with the extra condition that at least "minIdle" object instances
144  *   remain in the pool.  When non-positive, no objects will be evicted from the pool
145  *   due to idle time alone. This setting has no effect unless
146  *   <code>timeBetweenEvictionRunsMillis > 0.</code> and it is superceded by
147  *   {@link #setMinEvictableIdleTimeMillis <i>minEvictableIdleTimeMillis</i>}
148  *   (that is, if <code>minEvictableIdleTimeMillis</code> is positive, then
149  *   <code>softMinEvictableIdleTimeMillis</code> is ignored). The default setting for
150  *   this parameter is -1 (disabled).
151  *  </li>
152  *  <li>
153  *   {@link #setNumTestsPerEvictionRun <i>numTestsPerEvictionRun</i>}
154  *   determines the number of objects examined in each run of the idle object
155  *   evictor. This setting has no effect unless
156  *   <code>timeBetweenEvictionRunsMillis > 0.</code>  The default setting for
157  *   this parameter is 3.
158  *  </li>
159  * </ul>
160  * <p>
161  * <p>
162  * The pool can be configured to behave as a LIFO queue with respect to idle
163  * objects - always returning the most recently used object from the pool,
164  * or as a FIFO queue, where borrowObject always returns the oldest object
165  * in the idle object pool.
166  * <ul>
167  *  <li>
168  *   {@link #setLifo <i>lifo</i>}
169  *   determines whether or not the pool returns idle objects in
170  *   last-in-first-out order. The default setting for this parameter is
171  *   <code>true.</code>
172  *  </li>
173  * </ul>
174  * <p>
175  * GenericObjectPool is not usable without a {@link PoolableObjectFactory}.  A
176  * non-<code>null</code> factory must be provided either as a constructor argument
177  * or via a call to {@link #setFactory} before the pool is used.
178  * <p>
179  * Implementation note: To prevent possible deadlocks, care has been taken to
180  * ensure that no call to a factory method will occur within a synchronization
181  * block. See POOL-125 and DBCP-44 for more information.
182  *
183  * @see GenericKeyedObjectPool
184  * @author Rodney Waldhoff
185  * @author Dirk Verbeeck
186  * @author Sandy McArthur
187  * @version $Revision: 812938 $ $Date: 2009-09-09 09:09:26 -0400 (Wed, 09 Sep 2009) $
188  * @since Pool 1.0
189  */
190 public class GenericObjectPool extends BaseObjectPool implements ObjectPool {
191 
192     //--- public constants -------------------------------------------
193 
194     /**
195      * A "when exhausted action" type indicating that when the pool is
196      * exhausted (i.e., the maximum number of active objects has
197      * been reached), the {@link #borrowObject}
198      * method should fail, throwing a {@link NoSuchElementException}.
199      * @see #WHEN_EXHAUSTED_BLOCK
200      * @see #WHEN_EXHAUSTED_GROW
201      * @see #setWhenExhaustedAction
202      */
203     public static final byte WHEN_EXHAUSTED_FAIL   = 0;
204 
205     /**
206      * A "when exhausted action" type indicating that when the pool
207      * is exhausted (i.e., the maximum number
208      * of active objects has been reached), the {@link #borrowObject}
209      * method should block until a new object is available, or the
210      * {@link #getMaxWait maximum wait time} has been reached.
211      * @see #WHEN_EXHAUSTED_FAIL
212      * @see #WHEN_EXHAUSTED_GROW
213      * @see #setMaxWait
214      * @see #getMaxWait
215      * @see #setWhenExhaustedAction
216      */
217     public static final byte WHEN_EXHAUSTED_BLOCK  = 1;
218 
219     /**
220      * A "when exhausted action" type indicating that when the pool is
221      * exhausted (i.e., the maximum number
222      * of active objects has been reached), the {@link #borrowObject}
223      * method should simply create a new object anyway.
224      * @see #WHEN_EXHAUSTED_FAIL
225      * @see #WHEN_EXHAUSTED_GROW
226      * @see #setWhenExhaustedAction
227      */
228     public static final byte WHEN_EXHAUSTED_GROW   = 2;
229 
230     /**
231      * The default cap on the number of "sleeping" instances in the pool.
232      * @see #getMaxIdle
233      * @see #setMaxIdle
234      */
235     public static final int DEFAULT_MAX_IDLE  = 8;
236 
237     /**
238      * The default minimum number of "sleeping" instances in the pool
239      * before before the evictor thread (if active) spawns new objects.
240      * @see #getMinIdle
241      * @see #setMinIdle
242      */
243     public static final int DEFAULT_MIN_IDLE = 0;
244 
245     /**
246      * The default cap on the total number of active instances from the pool.
247      * @see #getMaxActive
248      */
249     public static final int DEFAULT_MAX_ACTIVE  = 8;
250 
251     /**
252      * The default "when exhausted action" for the pool.
253      * @see #WHEN_EXHAUSTED_BLOCK
254      * @see #WHEN_EXHAUSTED_FAIL
255      * @see #WHEN_EXHAUSTED_GROW
256      * @see #setWhenExhaustedAction
257      */
258     public static final byte DEFAULT_WHEN_EXHAUSTED_ACTION = WHEN_EXHAUSTED_BLOCK;
259 
260     /**
261      * The default LIFO status. True means that borrowObject returns the
262      * most recently used ("last in") idle object in the pool (if there are
263      * idle instances available).  False means that the pool behaves as a FIFO
264      * queue - objects are taken from the idle object pool in the order that
265      * they are returned to the pool.
266      * @see #setLifo
267      * @since 1.4
268      */
269     public static final boolean DEFAULT_LIFO = true;
270 
271     /**
272      * The default maximum amount of time (in milliseconds) the
273      * {@link #borrowObject} method should block before throwing
274      * an exception when the pool is exhausted and the
275      * {@link #getWhenExhaustedAction "when exhausted" action} is
276      * {@link #WHEN_EXHAUSTED_BLOCK}.
277      * @see #getMaxWait
278      * @see #setMaxWait
279      */
280     public static final long DEFAULT_MAX_WAIT = -1L;
281 
282     /**
283      * The default "test on borrow" value.
284      * @see #getTestOnBorrow
285      * @see #setTestOnBorrow
286      */
287     public static final boolean DEFAULT_TEST_ON_BORROW = false;
288 
289     /**
290      * The default "test on return" value.
291      * @see #getTestOnReturn
292      * @see #setTestOnReturn
293      */
294     public static final boolean DEFAULT_TEST_ON_RETURN = false;
295 
296     /**
297      * The default "test while idle" value.
298      * @see #getTestWhileIdle
299      * @see #setTestWhileIdle
300      * @see #getTimeBetweenEvictionRunsMillis
301      * @see #setTimeBetweenEvictionRunsMillis
302      */
303     public static final boolean DEFAULT_TEST_WHILE_IDLE = false;
304 
305     /**
306      * The default "time between eviction runs" value.
307      * @see #getTimeBetweenEvictionRunsMillis
308      * @see #setTimeBetweenEvictionRunsMillis
309      */
310     public static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS = -1L;
311 
312     /**
313      * The default number of objects to examine per run in the
314      * idle object evictor.
315      * @see #getNumTestsPerEvictionRun
316      * @see #setNumTestsPerEvictionRun
317      * @see #getTimeBetweenEvictionRunsMillis
318      * @see #setTimeBetweenEvictionRunsMillis
319      */
320     public static final int DEFAULT_NUM_TESTS_PER_EVICTION_RUN = 3;
321 
322     /**
323      * The default value for {@link #getMinEvictableIdleTimeMillis}.
324      * @see #getMinEvictableIdleTimeMillis
325      * @see #setMinEvictableIdleTimeMillis
326      */
327     public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS = 1000L * 60L * 30L;
328 
329     /**
330      * The default value for {@link #getSoftMinEvictableIdleTimeMillis}.
331      * @see #getSoftMinEvictableIdleTimeMillis
332      * @see #setSoftMinEvictableIdleTimeMillis
333      */
334     public static final long DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS = -1;
335 
336     //--- constructors -----------------------------------------------
337 
338     /**
339      * Create a new <tt>GenericObjectPool</tt> with default properties.
340      */
341     public GenericObjectPool() {
342         this(null, DEFAULT_MAX_ACTIVE, DEFAULT_WHEN_EXHAUSTED_ACTION, DEFAULT_MAX_WAIT, DEFAULT_MAX_IDLE,
343                 DEFAULT_MIN_IDLE, DEFAULT_TEST_ON_BORROW, DEFAULT_TEST_ON_RETURN, DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
344                 DEFAULT_NUM_TESTS_PER_EVICTION_RUN, DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS, DEFAULT_TEST_WHILE_IDLE);
345     }
346 
347     /**
348      * Create a new <tt>GenericObjectPool</tt> using the specified factory.
349      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
350      */
351     public GenericObjectPool(PoolableObjectFactory factory) {
352         this(factory, DEFAULT_MAX_ACTIVE, DEFAULT_WHEN_EXHAUSTED_ACTION, DEFAULT_MAX_WAIT, DEFAULT_MAX_IDLE,
353                 DEFAULT_MIN_IDLE, DEFAULT_TEST_ON_BORROW, DEFAULT_TEST_ON_RETURN, DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
354                 DEFAULT_NUM_TESTS_PER_EVICTION_RUN, DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS, DEFAULT_TEST_WHILE_IDLE);
355     }
356 
357     /**
358      * Create a new <tt>GenericObjectPool</tt> using the specified values.
359      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
360      * @param config a non-<tt>null</tt> {@link GenericObjectPool.Config} describing my configuration
361      */
362     public GenericObjectPool(PoolableObjectFactory factory, GenericObjectPool.Config config) {
363         this(factory, config.maxActive, config.whenExhaustedAction, config.maxWait, config.maxIdle, config.minIdle,
364                 config.testOnBorrow, config.testOnReturn, config.timeBetweenEvictionRunsMillis, 
365                 config.numTestsPerEvictionRun, config.minEvictableIdleTimeMillis, config.testWhileIdle, 
366                 config.softMinEvictableIdleTimeMillis, config.lifo);
367     }
368 
369     /**
370      * Create a new <tt>GenericObjectPool</tt> using the specified values.
371      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
372      * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
373      */
374     public GenericObjectPool(PoolableObjectFactory factory, int maxActive) {
375         this(factory, maxActive, DEFAULT_WHEN_EXHAUSTED_ACTION, DEFAULT_MAX_WAIT, DEFAULT_MAX_IDLE, DEFAULT_MIN_IDLE,
376                 DEFAULT_TEST_ON_BORROW, DEFAULT_TEST_ON_RETURN, DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
377                 DEFAULT_NUM_TESTS_PER_EVICTION_RUN, DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS, DEFAULT_TEST_WHILE_IDLE);
378     }
379 
380     /**
381      * Create a new <tt>GenericObjectPool</tt> using the specified values.
382      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
383      * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
384      * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})
385      * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and
386      * <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
387      */
388     public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait) {
389         this(factory, maxActive, whenExhaustedAction, maxWait, DEFAULT_MAX_IDLE, DEFAULT_MIN_IDLE, DEFAULT_TEST_ON_BORROW,
390                 DEFAULT_TEST_ON_RETURN, DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS, DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
391                 DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS, DEFAULT_TEST_WHILE_IDLE);
392     }
393 
394     /**
395      * Create a new <tt>GenericObjectPool</tt> using the specified values.
396      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
397      * @param maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive})
398      * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})
399      * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and
400      * <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
401      * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method
402      * (see {@link #getTestOnBorrow})
403      * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method
404      * (see {@link #getTestOnReturn})
405      */
406     public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait,
407             boolean testOnBorrow, boolean testOnReturn) {
408         this(factory, maxActive, whenExhaustedAction, maxWait, DEFAULT_MAX_IDLE, DEFAULT_MIN_IDLE, testOnBorrow,
409                 testOnReturn, DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS, DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
410                 DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS, DEFAULT_TEST_WHILE_IDLE);
411     }
412 
413     /**
414      * Create a new <tt>GenericObjectPool</tt> using the specified values.
415      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
416      * @param maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive})
417      * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})
418      * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and 
419      * <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
420      * @param maxIdle the maximum number of idle objects in my pool (see {@link #getMaxIdle})
421      */
422     public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle) {
423         this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, DEFAULT_MIN_IDLE, DEFAULT_TEST_ON_BORROW,
424                 DEFAULT_TEST_ON_RETURN, DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS, DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
425                 DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS, DEFAULT_TEST_WHILE_IDLE);
426     }
427 
428     /**
429      * Create a new <tt>GenericObjectPool</tt> using the specified values.
430      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
431      * @param maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive})
432      * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})
433      * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
434      * <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
435      * @param maxIdle the maximum number of idle objects in my pool (see {@link #getMaxIdle})
436      * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method
437      * (see {@link #getTestOnBorrow})
438      * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method
439      * (see {@link #getTestOnReturn})
440      */
441     public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait,
442             int maxIdle, boolean testOnBorrow, boolean testOnReturn) {
443         this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, DEFAULT_MIN_IDLE, testOnBorrow, testOnReturn,
444                 DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS, DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
445                 DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS, DEFAULT_TEST_WHILE_IDLE);
446     }
447 
448     /**
449      * Create a new <tt>GenericObjectPool</tt> using the specified values.
450      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
451      * @param maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive})
452      * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
453      * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and 
454      * <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
455      * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
456      * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
457      * method (see {@link #setTestOnBorrow})
458      * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method
459      * (see {@link #setTestOnReturn})
460      * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects
461      * for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
462      * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread
463      * (if any) (see {@link #setNumTestsPerEvictionRun})
464      * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it
465      * is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis})
466      * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any
467      * (see {@link #setTestWhileIdle})
468      */
469     public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait,
470             int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis,
471             int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle) {
472         this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, DEFAULT_MIN_IDLE, testOnBorrow, testOnReturn,
473                 timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle);
474     }
475 
476     /**
477      * Create a new <tt>GenericObjectPool</tt> using the specified values.
478      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
479      * @param maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive})
480      * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
481      * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
482      *  <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
483      * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
484      * @param minIdle the minimum number of idle objects in my pool (see {@link #setMinIdle})
485      * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method
486      * (see {@link #setTestOnBorrow})
487      * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method
488      * (see {@link #setTestOnReturn})
489      * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects
490      * for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
491      * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread
492      * (if any) (see {@link #setNumTestsPerEvictionRun})
493      * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before
494      * it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis})
495      * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any
496      *  (see {@link #setTestWhileIdle})
497      */
498     public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait,
499             int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis,
500             int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle) {
501         this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, minIdle, testOnBorrow, testOnReturn,
502                 timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle,
503                 DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS);
504     }
505 
506     /**
507      * Create a new <tt>GenericObjectPool</tt> using the specified values.
508      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
509      * @param maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive})
510      * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
511      * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
512      * <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
513      * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
514      * @param minIdle the minimum number of idle objects in my pool (see {@link #setMinIdle})
515      * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
516      * method (see {@link #setTestOnBorrow})
517      * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
518      * method (see {@link #setTestOnReturn})
519      * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects
520      * for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
521      * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread
522      * (if any) (see {@link #setNumTestsPerEvictionRun})
523      * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before
524      * it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis})
525      * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any
526      * (see {@link #setTestWhileIdle})
527      * @param softMinEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is
528      * eligible for eviction with the extra condition that at least "minIdle" amount of object remain in the pool.
529      * (see {@link #setSoftMinEvictableIdleTimeMillis})
530      * @since Pool 1.3
531      */
532     public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait,
533             int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis,
534             int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle,
535             long softMinEvictableIdleTimeMillis) {
536         this(factory, maxActive, whenExhaustedAction, maxWait, maxIdle, minIdle, testOnBorrow, testOnReturn,
537                 timeBetweenEvictionRunsMillis, numTestsPerEvictionRun, minEvictableIdleTimeMillis, testWhileIdle,
538                 softMinEvictableIdleTimeMillis, DEFAULT_LIFO);
539     }
540 
541     /**
542      * Create a new <tt>GenericObjectPool</tt> using the specified values.
543      * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
544      * @param maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive})
545      * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
546      * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
547      * <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
548      * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
549      * @param minIdle the minimum number of idle objects in my pool (see {@link #setMinIdle})
550      * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
551      * method (see {@link #setTestOnBorrow})
552      * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
553      * method (see {@link #setTestOnReturn})
554      * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle
555      * objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
556      * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction
557      * thread (if any) (see {@link #setNumTestsPerEvictionRun})
558      * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before
559      * it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis})
560      * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any
561      * (see {@link #setTestWhileIdle})
562      * @param softMinEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the
563      * pool before it is eligible for eviction with the extra condition that at least "minIdle" amount of object
564      * remain in the pool. (see {@link #setSoftMinEvictableIdleTimeMillis})
565      * @param lifo whether or not objects are returned in last-in-first-out order from the idle object pool
566      * (see {@link #setLifo})
567      * @since Pool 1.4
568      */
569     public GenericObjectPool(PoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait,
570             int maxIdle, int minIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis,
571             int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle,
572             long softMinEvictableIdleTimeMillis, boolean lifo) {
573         _factory = factory;
574         _maxActive = maxActive;
575         _lifo = lifo;
576         switch(whenExhaustedAction) {
577             case WHEN_EXHAUSTED_BLOCK:
578             case WHEN_EXHAUSTED_FAIL:
579             case WHEN_EXHAUSTED_GROW:
580                 _whenExhaustedAction = whenExhaustedAction;
581                 break;
582             default:
583                 throw new IllegalArgumentException("whenExhaustedAction " + whenExhaustedAction + " not recognized.");
584         }
585         _maxWait = maxWait;
586         _maxIdle = maxIdle;
587         _minIdle = minIdle;
588         _testOnBorrow = testOnBorrow;
589         _testOnReturn = testOnReturn;
590         _timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
591         _numTestsPerEvictionRun = numTestsPerEvictionRun;
592         _minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
593         _softMinEvictableIdleTimeMillis = softMinEvictableIdleTimeMillis;
594         _testWhileIdle = testWhileIdle;
595 
596         _pool = new CursorableLinkedList();
597         startEvictor(_timeBetweenEvictionRunsMillis);
598     }
599 
600     //--- public methods ---------------------------------------------
601 
602     //--- configuration methods --------------------------------------
603 
604     /**
605      * Returns the maximum number of objects that can be allocated by the pool
606      * (checked out to clients, or idle awaiting checkout) at a given time.
607      * When non-positive, there is no limit to the number of objects that can
608      * be managed by the pool at one time.
609      *
610      * @return the cap on the total number of object instances managed by the pool.
611      * @see #setMaxActive
612      */
613     public synchronized int getMaxActive() {
614         return _maxActive;
615     }
616 
617     /**
618      * Sets the cap on the number of objects that can be allocated by the pool
619      * (checked out to clients, or idle awaiting checkout) at a given time. Use
620      * a negative value for no limit.
621      *
622      * @param maxActive The cap on the total number of object instances managed by the pool.
623      * Negative values mean that there is no limit to the number of objects allocated
624      * by the pool.
625      * @see #getMaxActive
626      */
627     public synchronized void setMaxActive(int maxActive) {
628         _maxActive = maxActive;
629         allocate();
630     }
631 
632     /**
633      * Returns the action to take when the {@link #borrowObject} method
634      * is invoked when the pool is exhausted (the maximum number
635      * of "active" objects has been reached).
636      *
637      * @return one of {@link #WHEN_EXHAUSTED_BLOCK}, {@link #WHEN_EXHAUSTED_FAIL} or {@link #WHEN_EXHAUSTED_GROW}
638      * @see #setWhenExhaustedAction
639      */
640     public synchronized byte getWhenExhaustedAction() {
641         return _whenExhaustedAction;
642     }
643 
644     /**
645      * Sets the action to take when the {@link #borrowObject} method
646      * is invoked when the pool is exhausted (the maximum number
647      * of "active" objects has been reached).
648      *
649      * @param whenExhaustedAction the action code, which must be one of
650      *        {@link #WHEN_EXHAUSTED_BLOCK}, {@link #WHEN_EXHAUSTED_FAIL},
651      *        or {@link #WHEN_EXHAUSTED_GROW}
652      * @see #getWhenExhaustedAction
653      */
654     public synchronized void setWhenExhaustedAction(byte whenExhaustedAction) {
655         switch(whenExhaustedAction) {
656             case WHEN_EXHAUSTED_BLOCK:
657             case WHEN_EXHAUSTED_FAIL:
658             case WHEN_EXHAUSTED_GROW:
659                 _whenExhaustedAction = whenExhaustedAction;
660                 allocate();
661                 break;
662             default:
663                 throw new IllegalArgumentException("whenExhaustedAction " + whenExhaustedAction + " not recognized.");
664         }
665     }
666 
667 
668     /**
669      * Returns the maximum amount of time (in milliseconds) the
670      * {@link #borrowObject} method should block before throwing
671      * an exception when the pool is exhausted and the
672      * {@link #setWhenExhaustedAction "when exhausted" action} is
673      * {@link #WHEN_EXHAUSTED_BLOCK}.
674      *
675      * When less than or equal to 0, the {@link #borrowObject} method
676      * may block indefinitely.
677      *
678      * @return maximum number of milliseconds to block when borrowing an object.
679      * @see #setMaxWait
680      * @see #setWhenExhaustedAction
681      * @see #WHEN_EXHAUSTED_BLOCK
682      */
683     public synchronized long getMaxWait() {
684         return _maxWait;
685     }
686 
687     /**
688      * Sets the maximum amount of time (in milliseconds) the
689      * {@link #borrowObject} method should block before throwing
690      * an exception when the pool is exhausted and the
691      * {@link #setWhenExhaustedAction "when exhausted" action} is
692      * {@link #WHEN_EXHAUSTED_BLOCK}.
693      *
694      * When less than or equal to 0, the {@link #borrowObject} method
695      * may block indefinitely.
696      *
697      * @param maxWait maximum number of milliseconds to block when borrowing an object.
698      * @see #getMaxWait
699      * @see #setWhenExhaustedAction
700      * @see #WHEN_EXHAUSTED_BLOCK
701      */
702     public synchronized void setMaxWait(long maxWait) {
703         _maxWait = maxWait;
704         allocate();
705     }
706 
707     /**
708      * Returns the cap on the number of "idle" instances in the pool.
709      * @return the cap on the number of "idle" instances in the pool.
710      * @see #setMaxIdle
711      */
712     public synchronized int getMaxIdle() {
713         return _maxIdle;
714     }
715 
716     /**
717      * Sets the cap on the number of "idle" instances in the pool.
718      * If maxIdle is set too low on heavily loaded systems it is possible you
719      * will see objects being destroyed and almost immediately new objects
720      * being created. This is a result of the active threads momentarily
721      * returning objects faster than they are requesting them them, causing the
722      * number of idle objects to rise above maxIdle. The best value for maxIdle
723      * for heavily loaded system will vary but the default is a good starting
724      * point.
725      * @param maxIdle The cap on the number of "idle" instances in the pool.
726      * Use a negative value to indicate an unlimited number of idle instances.
727      * @see #getMaxIdle
728      */
729     public synchronized void setMaxIdle(int maxIdle) {
730         _maxIdle = maxIdle;
731         allocate();
732     }
733 
734     /**
735      * Sets the minimum number of objects allowed in the pool
736      * before the evictor thread (if active) spawns new objects.
737      * Note that no objects are created when
738      * <code>numActive + numIdle >= maxActive.</code>
739      * This setting has no effect if the idle object evictor is disabled
740      * (i.e. if <code>timeBetweenEvictionRunsMillis <= 0</code>).
741      *
742      * @param minIdle The minimum number of objects.
743      * @see #getMinIdle
744      * @see #getTimeBetweenEvictionRunsMillis()
745      */
746     public synchronized void setMinIdle(int minIdle) {
747         _minIdle = minIdle;
748         allocate();
749     }
750 
751     /**
752      * Returns the minimum number of objects allowed in the pool
753      * before the evictor thread (if active) spawns new objects.
754      * (Note no objects are created when: numActive + numIdle >= maxActive)
755      *
756      * @return The minimum number of objects.
757      * @see #setMinIdle
758      */
759     public synchronized int getMinIdle() {
760         return _minIdle;
761     }
762 
763     /**
764      * When <tt>true</tt>, objects will be
765      * {@link PoolableObjectFactory#validateObject validated}
766      * before being returned by the {@link #borrowObject}
767      * method.  If the object fails to validate,
768      * it will be dropped from the pool, and we will attempt
769      * to borrow another.
770      *
771      * @return <code>true</code> if objects are validated before being borrowed.
772      * @see #setTestOnBorrow
773      */
774     public boolean getTestOnBorrow() {
775         return _testOnBorrow;
776     }
777 
778     /**
779      * When <tt>true</tt>, objects will be
780      * {@link PoolableObjectFactory#validateObject validated}
781      * before being returned by the {@link #borrowObject}
782      * method.  If the object fails to validate,
783      * it will be dropped from the pool, and we will attempt
784      * to borrow another.
785      *
786      * @param testOnBorrow <code>true</code> if objects should be validated before being borrowed.
787      * @see #getTestOnBorrow
788      */
789     public void setTestOnBorrow(boolean testOnBorrow) {
790         _testOnBorrow = testOnBorrow;
791     }
792 
793     /**
794      * When <tt>true</tt>, objects will be
795      * {@link PoolableObjectFactory#validateObject validated}
796      * before being returned to the pool within the
797      * {@link #returnObject}.
798      *
799      * @return <code>true</code> when objects will be validated after returned to {@link #returnObject}.
800      * @see #setTestOnReturn
801      */
802     public boolean getTestOnReturn() {
803         return _testOnReturn;
804     }
805 
806     /**
807      * When <tt>true</tt>, objects will be
808      * {@link PoolableObjectFactory#validateObject validated}
809      * before being returned to the pool within the
810      * {@link #returnObject}.
811      *
812      * @param testOnReturn <code>true</code> so objects will be validated after returned to {@link #returnObject}.
813      * @see #getTestOnReturn
814      */
815     public void setTestOnReturn(boolean testOnReturn) {
816         _testOnReturn = testOnReturn;
817     }
818 
819     /**
820      * Returns the number of milliseconds to sleep between runs of the
821      * idle object evictor thread.
822      * When non-positive, no idle object evictor thread will be
823      * run.
824      *
825      * @return number of milliseconds to sleep between evictor runs.
826      * @see #setTimeBetweenEvictionRunsMillis
827      */
828     public synchronized long getTimeBetweenEvictionRunsMillis() {
829         return _timeBetweenEvictionRunsMillis;
830     }
831 
832     /**
833      * Sets the number of milliseconds to sleep between runs of the
834      * idle object evictor thread.
835      * When non-positive, no idle object evictor thread will be
836      * run.
837      *
838      * @param timeBetweenEvictionRunsMillis number of milliseconds to sleep between evictor runs.
839      * @see #getTimeBetweenEvictionRunsMillis
840      */
841     public synchronized void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) {
842         _timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
843         startEvictor(_timeBetweenEvictionRunsMillis);
844     }
845 
846     /**
847      * Returns the max number of objects to examine during each run of the
848      * idle object evictor thread (if any).
849      *
850      * @return max number of objects to examine during each evictor run.
851      * @see #setNumTestsPerEvictionRun
852      * @see #setTimeBetweenEvictionRunsMillis
853      */
854     public synchronized int getNumTestsPerEvictionRun() {
855         return _numTestsPerEvictionRun;
856     }
857 
858     /**
859      * Sets the max number of objects to examine during each run of the
860      * idle object evictor thread (if any).
861      * <p>
862      * When a negative value is supplied, <tt>ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})</tt>
863      * tests will be run.  That is, when the value is <i>-n</i>, roughly one <i>n</i>th of the
864      * idle objects will be tested per run. When the value is positive, the number of tests
865      * actually performed in each run will be the minimum of this value and the number of instances
866      * idle in the pool.
867      *
868      * @param numTestsPerEvictionRun max number of objects to examine during each evictor run.
869      * @see #getNumTestsPerEvictionRun
870      * @see #setTimeBetweenEvictionRunsMillis
871      */
872     public synchronized void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) {
873         _numTestsPerEvictionRun = numTestsPerEvictionRun;
874     }
875 
876     /**
877      * Returns the minimum amount of time an object may sit idle in the pool
878      * before it is eligible for eviction by the idle object evictor
879      * (if any).
880      *
881      * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
882      * @see #setMinEvictableIdleTimeMillis
883      * @see #setTimeBetweenEvictionRunsMillis
884      */
885     public synchronized long getMinEvictableIdleTimeMillis() {
886         return _minEvictableIdleTimeMillis;
887     }
888 
889     /**
890      * Sets the minimum amount of time an object may sit idle in the pool
891      * before it is eligible for eviction by the idle object evictor
892      * (if any).
893      * When non-positive, no objects will be evicted from the pool
894      * due to idle time alone.
895      * @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
896      * it is eligible for eviction.
897      * @see #getMinEvictableIdleTimeMillis
898      * @see #setTimeBetweenEvictionRunsMillis
899      */
900     public synchronized void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) {
901         _minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
902     }
903 
904     /**
905      * Returns the minimum amount of time an object may sit idle in the pool
906      * before it is eligible for eviction by the idle object evictor
907      * (if any), with the extra condition that at least
908      * "minIdle" amount of object remain in the pool.
909      *
910      * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
911      * @since Pool 1.3
912      * @see #setSoftMinEvictableIdleTimeMillis
913      */
914     public synchronized long getSoftMinEvictableIdleTimeMillis() {
915         return _softMinEvictableIdleTimeMillis;
916     }
917 
918     /**
919      * Sets the minimum amount of time an object may sit idle in the pool
920      * before it is eligible for eviction by the idle object evictor
921      * (if any), with the extra condition that at least
922      * "minIdle" object instances remain in the pool.
923      * When non-positive, no objects will be evicted from the pool
924      * due to idle time alone.
925      *
926      * @param softMinEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
927      * it is eligible for eviction.
928      * @since Pool 1.3
929      * @see #getSoftMinEvictableIdleTimeMillis
930      */
931     public synchronized void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis) {
932         _softMinEvictableIdleTimeMillis = softMinEvictableIdleTimeMillis;
933     }
934 
935     /**
936      * When <tt>true</tt>, objects will be
937      * {@link PoolableObjectFactory#validateObject validated}
938      * by the idle object evictor (if any).  If an object
939      * fails to validate, it will be dropped from the pool.
940      *
941      * @return <code>true</code> when objects will be validated by the evictor.
942      * @see #setTestWhileIdle
943      * @see #setTimeBetweenEvictionRunsMillis
944      */
945     public synchronized boolean getTestWhileIdle() {
946         return _testWhileIdle;
947     }
948 
949     /**
950      * When <tt>true</tt>, objects will be
951      * {@link PoolableObjectFactory#validateObject validated}
952      * by the idle object evictor (if any).  If an object
953      * fails to validate, it will be dropped from the pool.
954      *
955      * @param testWhileIdle <code>true</code> so objects will be validated by the evictor.
956      * @see #getTestWhileIdle
957      * @see #setTimeBetweenEvictionRunsMillis
958      */
959     public synchronized void setTestWhileIdle(boolean testWhileIdle) {
960         _testWhileIdle = testWhileIdle;
961     }
962 
963     /**
964      * Whether or not the idle object pool acts as a LIFO queue. True means
965      * that borrowObject returns the most recently used ("last in") idle object
966      * in the pool (if there are idle instances available).  False means that
967      * the pool behaves as a FIFO queue - objects are taken from the idle object
968      * pool in the order that they are returned to the pool.
969      *
970      * @return <code>true</true> if the pool is configured to act as a LIFO queue
971      * @since 1.4
972      */
973      public synchronized boolean getLifo() {
974          return _lifo;
975      }
976 
977      /**
978       * Sets the LIFO property of the pool. True means that borrowObject returns
979       * the most recently used ("last in") idle object in the pool (if there are
980       * idle instances available).  False means that the pool behaves as a FIFO
981       * queue - objects are taken from the idle object pool in the order that
982       * they are returned to the pool.
983       *
984       * @param lifo the new value for the LIFO property
985       * @since 1.4
986       */
987      public synchronized void setLifo(boolean lifo) {
988          this._lifo = lifo;
989      }
990 
991     /**
992      * Sets my configuration.
993      *
994      * @param conf configuration to use.
995      * @see GenericObjectPool.Config
996      */
997     public synchronized void setConfig(GenericObjectPool.Config conf) {
998         setMaxIdle(conf.maxIdle);
999         setMinIdle(conf.minIdle);
1000         setMaxActive(conf.maxActive);
1001         setMaxWait(conf.maxWait);
1002         setWhenExhaustedAction(conf.whenExhaustedAction);
1003         setTestOnBorrow(conf.testOnBorrow);
1004         setTestOnReturn(conf.testOnReturn);
1005         setTestWhileIdle(conf.testWhileIdle);
1006         setNumTestsPerEvictionRun(conf.numTestsPerEvictionRun);
1007         setMinEvictableIdleTimeMillis(conf.minEvictableIdleTimeMillis);
1008         setTimeBetweenEvictionRunsMillis(conf.timeBetweenEvictionRunsMillis);
1009         setSoftMinEvictableIdleTimeMillis(conf.softMinEvictableIdleTimeMillis);
1010         setLifo(conf.lifo);
1011         allocate();
1012     }
1013 
1014     //-- ObjectPool methods ------------------------------------------
1015 
1016     /**
1017      * <p>Borrows an object from the pool.</p>
1018      * 
1019      * <p>If there is an idle instance available in the pool, then either the most-recently returned
1020      * (if {@link #getLifo() lifo} == true) or "oldest" (lifo == false) instance sitting idle in the pool
1021      * will be activated and returned.  If activation fails, or {@link #getTestOnBorrow() testOnBorrow} is set
1022      * to true and validation fails, the instance is destroyed and the next available instance is examined.
1023      * This continues until either a valid instance is returned or there are no more idle instances available.</p>
1024      * 
1025      * <p>If there are no idle instances available in the pool, behavior depends on the {@link #getMaxActive() maxActive}
1026      * and (if applicable) {@link #getWhenExhaustedAction() whenExhaustedAction} and {@link #getMaxWait() maxWait}
1027      * properties. If the number of instances checked out from the pool is less than <code>maxActive,</code> a new
1028      * instance is created, activated and (if applicable) validated and returned to the caller.</p>
1029      * 
1030      * <p>If the pool is exhausted (no available idle instances and no capacity to create new ones),
1031      * this method will either block ({@link #WHEN_EXHAUSTED_BLOCK}), throw a <code>NoSuchElementException</code>
1032      * ({@link #WHEN_EXHAUSTED_FAIL}), or grow ({@link #WHEN_EXHAUSTED_GROW} - ignoring maxActive).
1033      * The length of time that this method will block when <code>whenExhaustedAction == WHEN_EXHAUSTED_BLOCK</code>
1034      * is determined by the {@link #getMaxWait() maxWait} property.</p>
1035      * 
1036      * <p>When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances
1037      * to become available.  As of pool 1.5, a "fairness" algorithm has been implemented to ensure that threads receive
1038      * available instances in request arrival order.</p>
1039      * 
1040      * @return object instance
1041      * @throws NoSuchElementException if an instance cannot be returned
1042      */
1043     public Object borrowObject() throws Exception {
1044         long starttime = System.currentTimeMillis();
1045         Latch latch = new Latch();
1046         byte whenExhaustedAction;
1047         long maxWait;
1048         synchronized (this) {
1049             // Get local copy of current config. Can't sync when used later as
1050             // it can result in a deadlock. Has the added advantage that config
1051             // is consistent for entire method execution
1052             whenExhaustedAction = _whenExhaustedAction;
1053             maxWait = _maxWait;
1054 
1055             // Add this request to the queue
1056             _allocationQueue.add(latch);
1057 
1058             // Work the allocation queue, allocating idle instances and
1059             // instance creation permits in request arrival order
1060             allocate();
1061         }
1062 
1063         for(;;) {
1064             synchronized (this) {
1065                 assertOpen();
1066             }
1067 
1068             // If no object was allocated from the pool above
1069             if(latch.getPair() == null) {
1070                 // check if we were allowed to create one
1071                 if(latch.mayCreate()) {
1072                     // allow new object to be created
1073                 } else {
1074                     // the pool is exhausted
1075                     switch(whenExhaustedAction) {
1076                         case WHEN_EXHAUSTED_GROW:
1077                             // allow new object to be created
1078                             synchronized (this) {
1079                                 // Make sure another thread didn't allocate us an object
1080                                 // or permit a new object to be created
1081                                 if (latch.getPair() == null && !latch.mayCreate()) {
1082                                     _allocationQueue.remove(latch);
1083                                     _numInternalProcessing++;
1084                                 }
1085                             }
1086                             break;
1087                         case WHEN_EXHAUSTED_FAIL:
1088                             synchronized (this) {
1089                                 // Make sure allocate hasn't already assigned an object
1090                                 // in a different thread or permitted a new object to be created
1091                                 if (latch.getPair() != null || latch.mayCreate()) {
1092                                     break;
1093                                 }
1094                                 _allocationQueue.remove(latch);
1095                             }
1096                             throw new NoSuchElementException("Pool exhausted");
1097                         case WHEN_EXHAUSTED_BLOCK:
1098                             try {
1099                                 synchronized (latch) {
1100                                     // Before we wait, make sure another thread didn't allocate us an object
1101                                     // or permit a new object to be created
1102                                     if (latch.getPair() == null && !latch.mayCreate()) {
1103                                         if(maxWait <= 0) {
1104                                             latch.wait();
1105                                         } else {
1106                                             // this code may be executed again after a notify then continue cycle
1107                                             // so, need to calculate the amount of time to wait
1108                                             final long elapsed = (System.currentTimeMillis() - starttime);
1109                                             final long waitTime = maxWait - elapsed;
1110                                             if (waitTime > 0)
1111                                             {
1112                                                 latch.wait(waitTime);
1113                                             }
1114                                         }
1115                                     } else {
1116                                         break;
1117                                     }
1118                                 }
1119                             } catch(InterruptedException e) {
1120                                 Thread.currentThread().interrupt();
1121                                 throw e;
1122                             }
1123                             if(maxWait > 0 && ((System.currentTimeMillis() - starttime) >= maxWait)) {
1124                                 synchronized(this) {
1125                                     // Make sure allocate hasn't already assigned an object
1126                                     // in a different thread or permitted a new object to be created
1127                                     if (latch.getPair() == null && !latch.mayCreate()) {
1128                                         // Remove latch from the allocation queue
1129                                         _allocationQueue.remove(latch);
1130                                     } else {
1131                                         break;
1132                                     }
1133                                 }
1134                                 throw new NoSuchElementException("Timeout waiting for idle object");
1135                             } else {
1136                                 continue; // keep looping
1137                             }
1138                         default:
1139                             throw new IllegalArgumentException("WhenExhaustedAction property " + whenExhaustedAction +
1140                                     " not recognized.");
1141                     }
1142                 }
1143             }
1144 
1145             boolean newlyCreated = false;
1146             if(null == latch.getPair()) {
1147                 try {
1148                     Object obj = _factory.makeObject();
1149                     latch.setPair(new ObjectTimestampPair(obj));
1150                     newlyCreated = true;
1151                 } finally {
1152                     if (!newlyCreated) {
1153                         // object cannot be created
1154                         synchronized (this) {
1155                             _numInternalProcessing--;
1156                             // No need to reset latch - about to throw exception
1157                             allocate();
1158                         }
1159                     }
1160                 }
1161             }
1162             // activate & validate the object
1163             try {
1164                 _factory.activateObject(latch.getPair().value);
1165                 if(_testOnBorrow &&
1166                         !_factory.validateObject(latch.getPair().value)) {
1167                     throw new Exception("ValidateObject failed");
1168                 }
1169                 synchronized(this) {
1170                     _numInternalProcessing--;
1171                     _numActive++;
1172                 }
1173                 return latch.getPair().value;
1174             }
1175             catch (Throwable e) {
1176                 // object cannot be activated or is invalid
1177                 try {
1178                     _factory.destroyObject(latch.getPair().value);
1179                 } catch (Throwable e2) {
1180                     // cannot destroy broken object
1181                 }
1182                 synchronized (this) {
1183                     _numInternalProcessing--;
1184                     latch.reset();
1185                     _allocationQueue.add(0, latch);
1186                     allocate();
1187                 }
1188                 if(newlyCreated) {
1189                     throw new NoSuchElementException("Could not create a validated object, cause: " + e.getMessage());
1190                 }
1191                 else {
1192                     continue; // keep looping
1193                 }
1194             }
1195         }
1196     }
1197 
1198     /**
1199      * Allocate available instances to latches in the allocation queue.  Then
1200      * set _mayCreate to true for as many additional latches remaining in queue
1201      * as _maxActive allows.
1202      */
1203     private synchronized void allocate() {
1204         if (isClosed()) return;
1205 
1206         // First use any objects in the pool to clear the queue
1207         for (;;) {
1208             if (!_pool.isEmpty() && !_allocationQueue.isEmpty()) {
1209                 Latch latch = (Latch) _allocationQueue.removeFirst();
1210                 latch.setPair((ObjectTimestampPair) _pool.removeFirst());
1211                 _numInternalProcessing++;
1212                 synchronized (latch) {
1213                     latch.notify();
1214                 }
1215             } else {
1216                 break;
1217             }
1218         }
1219 
1220         // Second utilise any spare capacity to create new objects
1221         for(;;) {
1222             if((!_allocationQueue.isEmpty()) && (_maxActive < 0 || (_numActive + _numInternalProcessing) < _maxActive)) {
1223                 Latch latch = (Latch) _allocationQueue.removeFirst();
1224                 latch.setMayCreate(true);
1225                 _numInternalProcessing++;
1226                 synchronized (latch) {
1227                     latch.notify();
1228                 }
1229             } else {
1230                 break;
1231             }
1232         }
1233     }
1234 
1235     /**
1236      * <p>Invalidates the given object instance.  Decrements the active count
1237      * and destroys the instance.</p>
1238      * 
1239      * @param obj instance to invalidate
1240      * @throws Exception if an exception occurs destroying the object
1241      */
1242     public void invalidateObject(Object obj) throws Exception {
1243         try {
1244             if (_factory != null) {
1245                 _factory.destroyObject(obj);
1246             }
1247         } finally {
1248             synchronized (this) {
1249                 _numActive--;
1250                 allocate();
1251             }
1252         }
1253     }
1254 
1255     /**
1256      * Clears any objects sitting idle in the pool by removing them from the
1257      * idle instance pool and then invoking the configured 
1258      * {@link PoolableObjectFactory#destroyObject(Object)} method on each idle
1259      * instance. 
1260      * 
1261      * <p> Implementation notes:
1262      * <ul><li>This method does not destroy or effect in any way instances that are
1263      * checked out of the pool when it is invoked.</li>
1264      * <li>Invoking this method does not prevent objects being
1265      * returned to the idle instance pool, even during its execution. It locks
1266      * the pool only during instance removal. Additional instances may be returned
1267      * while removed items are being destroyed.</li></ul></p>
1268      */
1269     public void clear() {
1270         List toDestroy = new ArrayList();
1271 
1272         synchronized(this) {
1273             toDestroy.addAll(_pool);
1274             _numInternalProcessing = _numInternalProcessing + _pool._size;
1275             _pool.clear();
1276         }
1277         destroy(toDestroy);
1278     }
1279 
1280     /**
1281      * Private method to destroy all the objects in a collection. Assumes
1282      * objects in the collection are instances of ObjectTimestampPair
1283      * 
1284      * @param c Collection of objects to destroy
1285      */
1286     private void destroy(Collection c) {
1287         for (Iterator it = c.iterator(); it.hasNext();) {
1288             try {
1289                 _factory.destroyObject(((ObjectTimestampPair)(it.next())).value);
1290             } catch(Exception e) {
1291                 // ignore error, keep destroying the rest
1292             } finally {
1293                 synchronized(this) {
1294                     _numInternalProcessing--;
1295                     allocate();
1296                 }
1297             }
1298         }
1299     }
1300 
1301     /**
1302      * Return the number of instances currently borrowed from this pool.
1303      *
1304      * @return the number of instances currently borrowed from this pool
1305      */
1306     public synchronized int getNumActive() {
1307         return _numActive;
1308     }
1309 
1310     /**
1311      * Return the number of instances currently idle in this pool.
1312      *
1313      * @return the number of instances currently idle in this pool
1314      */
1315     public synchronized int getNumIdle() {
1316         return _pool.size();
1317     }
1318 
1319     /**
1320      * <p>Returns an object instance to the pool.</p>
1321      * 
1322      * <p>If {@link #getMaxIdle() maxIdle} is set to a positive value and the number of idle instances
1323      * has reached this value, the returning instance is destroyed.</p>
1324      * 
1325      * <p>If {@link #getTestOnReturn() testOnReturn} == true, the returning instance is validated before being returned
1326      * to the idle instance pool.  In this case, if validation fails, the instance is destroyed.</p>
1327      * 
1328      * <p><strong>Note: </strong> There is no guard to prevent an object
1329      * being returned to the pool multiple times. Clients are expected to
1330      * discard references to returned objects and ensure that an object is not
1331      * returned to the pool multiple times in sequence (i.e., without being
1332      * borrowed again between returns). Violating this contract will result in
1333      * the same object appearing multiple times in the pool and pool counters
1334      * (numActive, numIdle) returning incorrect values.</p>
1335      * 
1336      * @param obj instance to return to the pool
1337      */
1338     public void returnObject(Object obj) throws Exception {
1339         try {
1340             addObjectToPool(obj, true);
1341         } catch (Exception e) {
1342             if (_factory != null) {
1343                 try {
1344                     _factory.destroyObject(obj);
1345                 } catch (Exception e2) {
1346                     // swallowed
1347                 }
1348                 // TODO: Correctness here depends on control in addObjectToPool.
1349                 // These two methods should be refactored, removing the
1350                 // "behavior flag", decrementNumActive, from addObjectToPool.
1351                 synchronized(this) {
1352                     _numActive--;
1353                     allocate();
1354                 }
1355             }
1356         }
1357     }
1358 
1359     /**
1360      * <p>Adds an object to the pool.</p>
1361      * 
1362      * <p>Validates the object if testOnReturn == true and passivates it before returning it to the pool.
1363      * if validation or passivation fails, or maxIdle is set and there is no room in the pool, the instance
1364      * is destroyed.</p>
1365      * 
1366      * <p>Calls {@link #allocate()} on successful completion</p>
1367      * 
1368      * @param obj instance to add to the pool
1369      * @param decrementNumActive whether or not to decrement the active count
1370      * @throws Exception
1371      */
1372     private void addObjectToPool(Object obj, boolean decrementNumActive) throws Exception {
1373         boolean success = true;
1374         if(_testOnReturn && !(_factory.validateObject(obj))) {
1375             success = false;
1376         } else {
1377             _factory.passivateObject(obj);
1378         }
1379 
1380         boolean shouldDestroy = !success;
1381 
1382         // Add instance to pool if there is room and it has passed validation
1383         // (if testOnreturn is set)
1384         synchronized (this) {
1385             if (isClosed()) {
1386                 shouldDestroy = true;
1387             } else {
1388                 if((_maxIdle >= 0) && (_pool.size() >= _maxIdle)) {
1389                     shouldDestroy = true;
1390                 } else if(success) {
1391                     // borrowObject always takes the first element from the queue,
1392                     // so for LIFO, push on top, FIFO add to end
1393                     if (_lifo) {
1394                         _pool.addFirst(new ObjectTimestampPair(obj));
1395                     } else {
1396                         _pool.addLast(new ObjectTimestampPair(obj));
1397                     }
1398                     if (decrementNumActive) {
1399                         _numActive--;
1400                     }
1401                     allocate();
1402                 }
1403             }
1404         }
1405 
1406         // Destroy the instance if necessary
1407         if(shouldDestroy) {
1408             try {
1409                 _factory.destroyObject(obj);
1410             } catch(Exception e) {
1411                 // ignored
1412             }
1413             // Decrement active count *after* destroy if applicable
1414             if (decrementNumActive) {
1415                 synchronized(this) {
1416                     _numActive--;
1417                     allocate();
1418                 }
1419             }
1420         }
1421 
1422     }
1423 
1424     /**
1425      * Closes the pool.  Once the pool is closed, {@link #borrowObject()}
1426      * will fail with IllegalStateException, but {@link #returnObject(Object)} and
1427      * {@link #invalidateObject(Object)} will continue to work. This method does not
1428      * {@link #clear()} the pool. The method is idempotent - that is, it is OK to call it on a closed
1429      * pool. 
1430      * 
1431      * @throws Exception
1432      */
1433     public void close() throws Exception {
1434         super.close();
1435         synchronized (this) {
1436             clear();
1437             startEvictor(-1L);
1438         }
1439     }
1440 
1441     /**
1442      * Sets the {@link PoolableObjectFactory factory} this pool uses
1443      * to create new instances. Trying to change
1444      * the <code>factory</code> while there are borrowed objects will
1445      * throw an {@link IllegalStateException}.
1446      *
1447      * @param factory the {@link PoolableObjectFactory} used to create new instances.
1448      * @throws IllegalStateException when the factory cannot be set at this time
1449      */
1450     public void setFactory(PoolableObjectFactory factory) throws IllegalStateException {
1451         List toDestroy = new ArrayList();
1452         synchronized (this) {
1453             assertOpen();
1454             if(0 < getNumActive()) {
1455                 throw new IllegalStateException("Objects are already active");
1456             } else {
1457                 toDestroy.addAll(_pool);
1458                 _numInternalProcessing = _numInternalProcessing + _pool._size;
1459                 _pool.clear();
1460             }
1461             _factory = factory;
1462         }
1463         destroy(toDestroy);
1464     }
1465 
1466     /**
1467      * <p>Perform <code>numTests</code> idle object eviction tests, evicting
1468      * examined objects that meet the criteria for eviction. If
1469      * <code>testWhileIdle</code> is true, examined objects are validated
1470      * when visited (and removed if invalid); otherwise only objects that
1471      * have been idle for more than <code>minEvicableIdletimeMillis</code>
1472      * are removed.</p>
1473      *
1474      * <p>Successive activations of this method examine objects in
1475      * in sequence, cycling through objects in oldest-to-youngest order.</p>
1476      *
1477      * @throws Exception if the pool is closed or eviction fails.
1478      */
1479     public void evict() throws Exception {
1480         assertOpen();
1481         synchronized (this) {
1482             if(_pool.isEmpty()) {
1483                 return;
1484             }
1485             if (null == _evictionCursor) {
1486                 _evictionCursor = (_pool.cursor(_lifo ? _pool.size() : 0));
1487             }
1488         }
1489 
1490         for (int i=0,m=getNumTests();i<m;i++) {
1491             final ObjectTimestampPair pair;
1492             synchronized (this) {
1493                 if ((_lifo && !_evictionCursor.hasPrevious()) ||
1494                         !_lifo && !_evictionCursor.hasNext()) {
1495                     _evictionCursor.close();
1496                     _evictionCursor = _pool.cursor(_lifo ? _pool.size() : 0);
1497                 }
1498 
1499                 pair = _lifo ?
1500                         (ObjectTimestampPair) _evictionCursor.previous() :
1501                         (ObjectTimestampPair) _evictionCursor.next();
1502 
1503                 _evictionCursor.remove();
1504                 _numInternalProcessing++;
1505             }
1506 
1507             boolean removeObject = false;
1508             final long idleTimeMilis = System.currentTimeMillis() - pair.tstamp;
1509             if ((getMinEvictableIdleTimeMillis() > 0) &&
1510                     (idleTimeMilis > getMinEvictableIdleTimeMillis())) {
1511                 removeObject = true;
1512             } else if ((getSoftMinEvictableIdleTimeMillis() > 0) &&
1513                     (idleTimeMilis > getSoftMinEvictableIdleTimeMillis()) &&
1514                     ((getNumIdle() + 1)> getMinIdle())) { // +1 accounts for object we are processing
1515                 removeObject = true;
1516             }
1517             if(getTestWhileIdle() && !removeObject) {
1518                 boolean active = false;
1519                 try {
1520                     _factory.activateObject(pair.value);
1521                     active = true;
1522                 } catch(Exception e) {
1523                     removeObject=true;
1524                 }
1525                 if(active) {
1526                     if(!_factory.validateObject(pair.value)) {
1527                         removeObject=true;
1528                     } else {
1529                         try {
1530                             _factory.passivateObject(pair.value);
1531                         } catch(Exception e) {
1532                             removeObject=true;
1533                         }
1534                     }
1535                 }
1536             }
1537 
1538             if (removeObject) {
1539                 try {
1540                     _factory.destroyObject(pair.value);
1541                 } catch(Exception e) {
1542                     // ignored
1543                 }
1544             }
1545             synchronized (this) {
1546                 if(!removeObject) {
1547                     _evictionCursor.add(pair);
1548                     if (_lifo) {
1549                         // Skip over the element we just added back
1550                         _evictionCursor.previous();
1551                     }
1552                 }
1553                 _numInternalProcessing--;
1554             }
1555         }
1556     }
1557 
1558     /**
1559      * Check to see if we are below our minimum number of objects
1560      * if so enough to bring us back to our minimum.
1561      *
1562      * @throws Exception when {@link #addObject()} fails.
1563      */
1564     private void ensureMinIdle() throws Exception {
1565         // this method isn't synchronized so the
1566         // calculateDeficit is done at the beginning
1567         // as a loop limit and a second time inside the loop
1568         // to stop when another thread already returned the
1569         // needed objects
1570         int objectDeficit = calculateDeficit(false);
1571         for ( int j = 0 ; j < objectDeficit && calculateDeficit(true) > 0 ; j++ ) {
1572             try {
1573                 addObject();
1574             } finally {
1575                 synchronized (this) {
1576                     _numInternalProcessing--;
1577                     allocate();
1578                 }
1579             }
1580         }
1581     }
1582 
1583     /**
1584      * This returns the number of objects to create during the pool
1585      * sustain cycle. This will ensure that the minimum number of idle
1586      * instances is maintained without going past the maxActive value.
1587      *
1588      * @param incrementInternal - Should the count of objects currently under
1589      *                            some form of internal processing be
1590      *                            incremented?
1591      * @return The number of objects to be created
1592      */
1593     private synchronized int calculateDeficit(boolean incrementInternal) {
1594         int objectDeficit = getMinIdle() - getNumIdle();
1595         if (_maxActive > 0) {
1596             int growLimit = Math.max(0,
1597                     getMaxActive() - getNumActive() - getNumIdle() - _numInternalProcessing);
1598             objectDeficit = Math.min(objectDeficit, growLimit);
1599         }
1600         if (incrementInternal && objectDeficit >0) {
1601             _numInternalProcessing++;
1602         }
1603         return objectDeficit;
1604     }
1605 
1606     /**
1607      * Create an object, and place it into the pool.
1608      * addObject() is useful for "pre-loading" a pool with idle objects.
1609      */
1610     public void addObject() throws Exception {
1611         assertOpen();
1612         if (_factory == null) {
1613             throw new IllegalStateException("Cannot add objects without a factory.");
1614         }
1615         Object obj = _factory.makeObject();
1616         try {
1617             assertOpen();
1618             addObjectToPool(obj, false);
1619         } catch (IllegalStateException ex) { // Pool closed
1620             try {
1621                 _factory.destroyObject(obj);
1622             } catch (Exception ex2) {
1623                 // swallow
1624             }
1625             throw ex;
1626         }
1627     }
1628 
1629     //--- non-public methods ----------------------------------------
1630 
1631     /**
1632      * Start the eviction thread or service, or when
1633      * <i>delay</i> is non-positive, stop it
1634      * if it is already running.
1635      *
1636      * @param delay milliseconds between evictor runs.
1637      */
1638     protected synchronized void startEvictor(long delay) {
1639         if(null != _evictor) {
1640             EvictionTimer.cancel(_evictor);
1641             _evictor = null;
1642         }
1643         if(delay > 0) {
1644             _evictor = new Evictor();
1645             EvictionTimer.schedule(_evictor, delay, delay);
1646         }
1647     }
1648 
1649     /**
1650      * Returns pool info including {@link #getNumActive()}, {@link #getNumIdle()}
1651      * and a list of objects idle in the pool with their idle times.
1652      * 
1653      * @return string containing debug information
1654      */
1655     synchronized String debugInfo() {
1656         StringBuffer buf = new StringBuffer();
1657         buf.append("Active: ").append(getNumActive()).append("\n");
1658         buf.append("Idle: ").append(getNumIdle()).append("\n");
1659         buf.append("Idle Objects:\n");
1660         Iterator it = _pool.iterator();
1661         long time = System.currentTimeMillis();
1662         while(it.hasNext()) {
1663             ObjectTimestampPair pair = (ObjectTimestampPair)(it.next());
1664             buf.append("\t").append(pair.value).append("\t").append(time - pair.tstamp).append("\n");
1665         }
1666         return buf.toString();
1667     }
1668 
1669     /** 
1670      * Returns the number of tests to be performed in an Evictor run,
1671      * based on the current value of <code>numTestsPerEvictionRun</code>
1672      * and the number of idle instances in the pool.
1673      * 
1674      * @see #setNumTestsPerEvictionRun
1675      * @return the number of tests for the Evictor to run
1676      */
1677     private int getNumTests() {
1678         if(_numTestsPerEvictionRun >= 0) {
1679             return Math.min(_numTestsPerEvictionRun, _pool.size());
1680         } else {
1681             return(int)(Math.ceil(_pool.size()/Math.abs((double)_numTestsPerEvictionRun)));
1682         }
1683     }
1684 
1685     //--- inner classes ----------------------------------------------
1686 
1687     /**
1688      * The idle object evictor {@link TimerTask}.
1689      * @see GenericObjectPool#setTimeBetweenEvictionRunsMillis
1690      */
1691     private class Evictor extends TimerTask {
1692         /**
1693          * Run pool maintenance.  Evict objects qualifying for eviction and then
1694          * invoke {@link GenericObjectPool#ensureMinIdle()}.
1695          */
1696         public void run() {
1697             try {
1698                 evict();
1699             } catch(Exception e) {
1700                 // ignored
1701             } catch(OutOfMemoryError oome) {
1702                 // Log problem but give evictor thread a chance to continue in
1703                 // case error is recoverable
1704                 oome.printStackTrace(System.err);
1705             }
1706             try {
1707                 ensureMinIdle();
1708             } catch(Exception e) {
1709                 // ignored
1710             }
1711         }
1712     }
1713 
1714     /**
1715      * A simple "struct" encapsulating the
1716      * configuration information for a {@link GenericObjectPool}.
1717      * @see GenericObjectPool#GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory,
1718      * org.apache.commons.pool.impl.GenericObjectPool.Config)
1719      * @see GenericObjectPool#setConfig
1720      */
1721     public static class Config {
1722         /**
1723          * @see GenericObjectPool#setMaxIdle
1724          */
1725         public int maxIdle = GenericObjectPool.DEFAULT_MAX_IDLE;
1726         /**
1727          * @see GenericObjectPool#setMinIdle
1728          */
1729         public int minIdle = GenericObjectPool.DEFAULT_MIN_IDLE;
1730         /**
1731          * @see GenericObjectPool#setMaxActive
1732          */
1733         public int maxActive = GenericObjectPool.DEFAULT_MAX_ACTIVE;
1734         /**
1735          * @see GenericObjectPool#setMaxWait
1736          */
1737         public long maxWait = GenericObjectPool.DEFAULT_MAX_WAIT;
1738         /**
1739          * @see GenericObjectPool#setWhenExhaustedAction
1740          */
1741         public byte whenExhaustedAction = GenericObjectPool.DEFAULT_WHEN_EXHAUSTED_ACTION;
1742         /**
1743          * @see GenericObjectPool#setTestOnBorrow
1744          */
1745         public boolean testOnBorrow = GenericObjectPool.DEFAULT_TEST_ON_BORROW;
1746         /**
1747          * @see GenericObjectPool#setTestOnReturn
1748          */
1749         public boolean testOnReturn = GenericObjectPool.DEFAULT_TEST_ON_RETURN;
1750         /**
1751          * @see GenericObjectPool#setTestWhileIdle
1752          */
1753         public boolean testWhileIdle = GenericObjectPool.DEFAULT_TEST_WHILE_IDLE;
1754         /**
1755          * @see GenericObjectPool#setTimeBetweenEvictionRunsMillis
1756          */
1757         public long timeBetweenEvictionRunsMillis = GenericObjectPool.DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS;
1758         /**
1759          * @see GenericObjectPool#setNumTestsPerEvictionRun
1760          */
1761         public int numTestsPerEvictionRun =  GenericObjectPool.DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
1762         /**
1763          * @see GenericObjectPool#setMinEvictableIdleTimeMillis
1764          */
1765         public long minEvictableIdleTimeMillis = GenericObjectPool.DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
1766         /**
1767          * @see GenericObjectPool#setSoftMinEvictableIdleTimeMillis
1768          */
1769         public long softMinEvictableIdleTimeMillis = GenericObjectPool.DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
1770         /**
1771          * @see GenericObjectPool#setLifo
1772          */
1773         public boolean lifo = GenericObjectPool.DEFAULT_LIFO;
1774 
1775     }
1776 
1777     /**
1778      * Latch used to control allocation order of objects to threads to ensure
1779      * fairness. That is, objects are allocated to threads in the order that
1780      * threads request objects.
1781      */
1782     private static final class Latch {
1783         
1784         /** object timestamp pair allocated to this latch */
1785         private ObjectTimestampPair _pair;
1786         
1787         /** Wheter or not this latch may create an object instance */
1788         private boolean _mayCreate = false;
1789 
1790         /**
1791          * Returns ObjectTimestampPair allocated to this latch
1792          * @return ObjectTimestampPair allocated to this latch
1793          */
1794         private synchronized ObjectTimestampPair getPair() {
1795             return _pair;
1796         }
1797         
1798         /**
1799          * Sets ObjectTimestampPair on this latch
1800          * @param pair ObjectTimestampPair allocated to this latch
1801          */
1802         private synchronized void setPair(ObjectTimestampPair pair) {
1803             _pair = pair;
1804         }
1805 
1806         /**
1807          * Whether or not this latch may create an object instance 
1808          * @return true if this latch has an instance creation permit
1809          */
1810         private synchronized boolean mayCreate() {
1811             return _mayCreate;
1812         }
1813         
1814         /**
1815          * Sets the mayCreate property
1816          * @param mayCreate new value for mayCreate
1817          */
1818         private synchronized void setMayCreate(boolean mayCreate) {
1819             _mayCreate = mayCreate;
1820         }
1821 
1822         /**
1823          * Reset the latch data. Used when an allocation fails and the latch
1824          * needs to be re-added to the queue.
1825          */
1826         private synchronized void reset() {
1827             _pair = null;
1828             _mayCreate = false;
1829         }
1830     }
1831 
1832 
1833     //--- private attributes ---------------------------------------
1834 
1835     /**
1836      * The cap on the number of idle instances in the pool.
1837      * @see #setMaxIdle
1838      * @see #getMaxIdle
1839      */
1840     private int _maxIdle = DEFAULT_MAX_IDLE;
1841 
1842     /**
1843     * The cap on the minimum number of idle instances in the pool.
1844     * @see #setMinIdle
1845     * @see #getMinIdle
1846     */
1847     private int _minIdle = DEFAULT_MIN_IDLE;
1848 
1849     /**
1850      * The cap on the total number of active instances from the pool.
1851      * @see #setMaxActive
1852      * @see #getMaxActive
1853      */
1854     private int _maxActive = DEFAULT_MAX_ACTIVE;
1855 
1856     /**
1857      * The maximum amount of time (in millis) the
1858      * {@link #borrowObject} method should block before throwing
1859      * an exception when the pool is exhausted and the
1860      * {@link #getWhenExhaustedAction "when exhausted" action} is
1861      * {@link #WHEN_EXHAUSTED_BLOCK}.
1862      *
1863      * When less than or equal to 0, the {@link #borrowObject} method
1864      * may block indefinitely.
1865      *
1866      * @see #setMaxWait
1867      * @see #getMaxWait
1868      * @see #WHEN_EXHAUSTED_BLOCK
1869      * @see #setWhenExhaustedAction
1870      * @see #getWhenExhaustedAction
1871      */
1872     private long _maxWait = DEFAULT_MAX_WAIT;
1873 
1874     /**
1875      * The action to take when the {@link #borrowObject} method
1876      * is invoked when the pool is exhausted (the maximum number
1877      * of "active" objects has been reached).
1878      *
1879      * @see #WHEN_EXHAUSTED_BLOCK
1880      * @see #WHEN_EXHAUSTED_FAIL
1881      * @see #WHEN_EXHAUSTED_GROW
1882      * @see #DEFAULT_WHEN_EXHAUSTED_ACTION
1883      * @see #setWhenExhaustedAction
1884      * @see #getWhenExhaustedAction
1885      */
1886     private byte _whenExhaustedAction = DEFAULT_WHEN_EXHAUSTED_ACTION;
1887 
1888     /**
1889      * When <tt>true</tt>, objects will be
1890      * {@link PoolableObjectFactory#validateObject validated}
1891      * before being returned by the {@link #borrowObject}
1892      * method.  If the object fails to validate,
1893      * it will be dropped from the pool, and we will attempt
1894      * to borrow another.
1895      *
1896      * @see #setTestOnBorrow
1897      * @see #getTestOnBorrow
1898      */
1899     private volatile boolean _testOnBorrow = DEFAULT_TEST_ON_BORROW;
1900 
1901     /**
1902      * When <tt>true</tt>, objects will be
1903      * {@link PoolableObjectFactory#validateObject validated}
1904      * before being returned to the pool within the
1905      * {@link #returnObject}.
1906      *
1907      * @see #getTestOnReturn
1908      * @see #setTestOnReturn
1909      */
1910     private volatile boolean _testOnReturn = DEFAULT_TEST_ON_RETURN;
1911 
1912     /**
1913      * When <tt>true</tt>, objects will be
1914      * {@link PoolableObjectFactory#validateObject validated}
1915      * by the idle object evictor (if any).  If an object
1916      * fails to validate, it will be dropped from the pool.
1917      *
1918      * @see #setTestWhileIdle
1919      * @see #getTestWhileIdle
1920      * @see #getTimeBetweenEvictionRunsMillis
1921      * @see #setTimeBetweenEvictionRunsMillis
1922      */
1923     private boolean _testWhileIdle = DEFAULT_TEST_WHILE_IDLE;
1924 
1925     /**
1926      * The number of milliseconds to sleep between runs of the
1927      * idle object evictor thread.
1928      * When non-positive, no idle object evictor thread will be
1929      * run.
1930      *
1931      * @see #setTimeBetweenEvictionRunsMillis
1932      * @see #getTimeBetweenEvictionRunsMillis
1933      */
1934     private long _timeBetweenEvictionRunsMillis = DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS;
1935 
1936     /**
1937      * The max number of objects to examine during each run of the
1938      * idle object evictor thread (if any).
1939      * <p>
1940      * When a negative value is supplied, <tt>ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})</tt>
1941      * tests will be run.  I.e., when the value is <i>-n</i>, roughly one <i>n</i>th of the
1942      * idle objects will be tested per run.
1943      *
1944      * @see #setNumTestsPerEvictionRun
1945      * @see #getNumTestsPerEvictionRun
1946      * @see #getTimeBetweenEvictionRunsMillis
1947      * @see #setTimeBetweenEvictionRunsMillis
1948      */
1949     private int _numTestsPerEvictionRun =  DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
1950 
1951     /**
1952      * The minimum amount of time an object may sit idle in the pool
1953      * before it is eligible for eviction by the idle object evictor
1954      * (if any).
1955      * When non-positive, no objects will be evicted from the pool
1956      * due to idle time alone.
1957      *
1958      * @see #setMinEvictableIdleTimeMillis
1959      * @see #getMinEvictableIdleTimeMillis
1960      * @see #getTimeBetweenEvictionRunsMillis
1961      * @see #setTimeBetweenEvictionRunsMillis
1962      */
1963     private long _minEvictableIdleTimeMillis = DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
1964 
1965     /**
1966      * The minimum amount of time an object may sit idle in the pool
1967      * before it is eligible for eviction by the idle object evictor
1968      * (if any), with the extra condition that at least
1969      * "minIdle" amount of object remain in the pool.
1970      * When non-positive, no objects will be evicted from the pool
1971      * due to idle time alone.
1972      *
1973      * @see #setSoftMinEvictableIdleTimeMillis
1974      * @see #getSoftMinEvictableIdleTimeMillis
1975      */
1976     private long _softMinEvictableIdleTimeMillis = DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
1977 
1978     /** Whether or not the pool behaves as a LIFO queue (last in first out) */
1979     private boolean _lifo = DEFAULT_LIFO;
1980 
1981     /** My pool. */
1982     private CursorableLinkedList _pool = null;
1983 
1984     /** Eviction cursor - keeps track of idle object evictor position */
1985     private CursorableLinkedList.Cursor _evictionCursor = null;
1986 
1987     /** My {@link PoolableObjectFactory}. */
1988     private PoolableObjectFactory _factory = null;
1989 
1990     /**
1991      * The number of objects {@link #borrowObject} borrowed
1992      * from the pool, but not yet returned.
1993      */
1994     private int _numActive = 0;
1995 
1996     /**
1997      * My idle object eviction {@link TimerTask}, if any.
1998      */
1999     private Evictor _evictor = null;
2000 
2001     /**
2002      * The number of objects subject to some form of internal processing
2003      * (usually creation or destruction) that should be included in the total
2004      * number of objects but are neither active nor idle.
2005      */
2006     private int _numInternalProcessing = 0;
2007 
2008     /**
2009      * Used to track the order in which threads call {@link #borrowObject()} so
2010      * that objects can be allocated in the order in which the threads requested
2011      * them.
2012      */
2013     private LinkedList _allocationQueue = new LinkedList();
2014 
2015 }