001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    package org.apache.commons.pool.impl;
019    
020    import java.util.ArrayList;
021    import java.util.Collection;
022    import java.util.Iterator;
023    import java.util.LinkedList;
024    import java.util.List;
025    import java.util.NoSuchElementException;
026    import java.util.TimerTask;
027    
028    import org.apache.commons.pool.BaseObjectPool;
029    import org.apache.commons.pool.ObjectPool;
030    import org.apache.commons.pool.PoolUtils;
031    import org.apache.commons.pool.PoolableObjectFactory;
032    import org.apache.commons.pool.impl.GenericKeyedObjectPool.ObjectTimestampPair;
033    
034    /**
035     * A configurable {@link ObjectPool} implementation.
036     * <p>
037     * When coupled with the appropriate {@link PoolableObjectFactory},
038     * <tt>GenericObjectPool</tt> provides robust pooling functionality for
039     * arbitrary objects.
040     * <p>
041     * A <tt>GenericObjectPool</tt> provides a number of configurable parameters:
042     * <ul>
043     *  <li>
044     *    {@link #setMaxActive <i>maxActive</i>} controls the maximum number of
045     *    objects that can be allocated by the pool (checked out to clients, or
046     *    idle awaiting checkout) at a given time.  When non-positive, there is no
047     *    limit to the number of objects that can be managed by the pool at one time.
048     *    When {@link #setMaxActive <i>maxActive</i>} is reached, the pool is said
049     *    to be exhausted. The default setting for this parameter is 8.
050     *  </li>
051     *  <li>
052     *    {@link #setMaxIdle <i>maxIdle</i>} controls the maximum number of objects
053     *    that can sit idle in the pool at any time.  When negative, there is no
054     *    limit to the number of objects that may be idle at one time. The default
055     *    setting for this parameter is 8.
056     *  </li>
057     *  <li>
058     *    {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} specifies the
059     *    behavior of the {@link #borrowObject} method when the pool is exhausted:
060     *    <ul>
061     *    <li>
062     *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} is
063     *      {@link #WHEN_EXHAUSTED_FAIL}, {@link #borrowObject} will throw
064     *      a {@link NoSuchElementException}
065     *    </li>
066     *    <li>
067     *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>} is
068     *      {@link #WHEN_EXHAUSTED_GROW}, {@link #borrowObject} will create a new
069     *      object and return it (essentially making {@link #setMaxActive <i>maxActive</i>}
070     *      meaningless.)
071     *    </li>
072     *    <li>
073     *      When {@link #setWhenExhaustedAction <i>whenExhaustedAction</i>}
074     *      is {@link #WHEN_EXHAUSTED_BLOCK}, {@link #borrowObject} will block
075     *      (invoke {@link Object#wait()}) until a new or idle object is available.
076     *      If a positive {@link #setMaxWait <i>maxWait</i>}
077     *      value is supplied, then {@link #borrowObject} will block for at
078     *      most that many milliseconds, after which a {@link NoSuchElementException}
079     *      will be thrown.  If {@link #setMaxWait <i>maxWait</i>} is non-positive,
080     *      the {@link #borrowObject} method will block indefinitely.
081     *    </li>
082     *    </ul>
083     *    The default <code>whenExhaustedAction</code> setting is
084     *    {@link #WHEN_EXHAUSTED_BLOCK} and the default <code>maxWait</code>
085     *    setting is -1. By default, therefore, <code>borrowObject</code> will
086     *    block indefinitely until an idle instance becomes available.
087     *  </li>
088     *  <li>
089     *    When {@link #setTestOnBorrow <i>testOnBorrow</i>} is set, the pool will
090     *    attempt to validate each object before it is returned from the
091     *    {@link #borrowObject} method. (Using the provided factory's
092     *    {@link PoolableObjectFactory#validateObject} method.)  Objects that fail
093     *    to validate will be dropped from the pool, and a different object will
094     *    be borrowed. The default setting for this parameter is
095     *    <code>false.</code>
096     *  </li>
097     *  <li>
098     *    When {@link #setTestOnReturn <i>testOnReturn</i>} is set, the pool will
099     *    attempt to validate each object before it is returned to the pool in the
100     *    {@link #returnObject} method. (Using the provided factory's
101     *    {@link PoolableObjectFactory#validateObject}
102     *    method.)  Objects that fail to validate will be dropped from the pool.
103     *    The default setting for this parameter is <code>false.</code>
104     *  </li>
105     * </ul>
106     * <p>
107     * Optionally, one may configure the pool to examine and possibly evict objects
108     * as they sit idle in the pool and to ensure that a minimum number of idle
109     * objects are available. This is performed by an "idle object eviction"
110     * thread, which runs asynchronously. Caution should be used when configuring
111     * this optional feature. Eviction runs contend with client threads for access
112     * to objects in the pool, so if they run too frequently performance issues may
113     * result. The idle object eviction thread may be configured using the following
114     * 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: 892236 $ $Date: 2013-12-31 04:43:12 +0000 (Tue, 31 Dec 2013) $
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 void setMaxActive(int maxActive) {
628            synchronized(this) {
629                _maxActive = maxActive;
630            }
631            allocate();
632        }
633    
634        /**
635         * Returns the action to take when the {@link #borrowObject} method
636         * is invoked when the pool is exhausted (the maximum number
637         * of "active" objects has been reached).
638         *
639         * @return one of {@link #WHEN_EXHAUSTED_BLOCK}, {@link #WHEN_EXHAUSTED_FAIL} or {@link #WHEN_EXHAUSTED_GROW}
640         * @see #setWhenExhaustedAction
641         */
642        public synchronized byte getWhenExhaustedAction() {
643            return _whenExhaustedAction;
644        }
645    
646        /**
647         * Sets the action to take when the {@link #borrowObject} method
648         * is invoked when the pool is exhausted (the maximum number
649         * of "active" objects has been reached).
650         *
651         * @param whenExhaustedAction the action code, which must be one of
652         *        {@link #WHEN_EXHAUSTED_BLOCK}, {@link #WHEN_EXHAUSTED_FAIL},
653         *        or {@link #WHEN_EXHAUSTED_GROW}
654         * @see #getWhenExhaustedAction
655         */
656        public void setWhenExhaustedAction(byte whenExhaustedAction) {
657            synchronized(this) {
658                switch(whenExhaustedAction) {
659                    case WHEN_EXHAUSTED_BLOCK:
660                    case WHEN_EXHAUSTED_FAIL:
661                    case WHEN_EXHAUSTED_GROW:
662                        _whenExhaustedAction = whenExhaustedAction;
663                        break;
664                    default:
665                        throw new IllegalArgumentException("whenExhaustedAction " + whenExhaustedAction + " not recognized.");
666                }
667            }
668            allocate();
669        }
670    
671    
672        /**
673         * Returns the maximum amount of time (in milliseconds) the
674         * {@link #borrowObject} method should block before throwing
675         * an exception when the pool is exhausted and the
676         * {@link #setWhenExhaustedAction "when exhausted" action} is
677         * {@link #WHEN_EXHAUSTED_BLOCK}.
678         *
679         * When less than or equal to 0, the {@link #borrowObject} method
680         * may block indefinitely.
681         *
682         * @return maximum number of milliseconds to block when borrowing an object.
683         * @see #setMaxWait
684         * @see #setWhenExhaustedAction
685         * @see #WHEN_EXHAUSTED_BLOCK
686         */
687        public synchronized long getMaxWait() {
688            return _maxWait;
689        }
690    
691        /**
692         * Sets the maximum amount of time (in milliseconds) the
693         * {@link #borrowObject} method should block before throwing
694         * an exception when the pool is exhausted and the
695         * {@link #setWhenExhaustedAction "when exhausted" action} is
696         * {@link #WHEN_EXHAUSTED_BLOCK}.
697         *
698         * When less than or equal to 0, the {@link #borrowObject} method
699         * may block indefinitely.
700         *
701         * @param maxWait maximum number of milliseconds to block when borrowing an object.
702         * @see #getMaxWait
703         * @see #setWhenExhaustedAction
704         * @see #WHEN_EXHAUSTED_BLOCK
705         */
706        public void setMaxWait(long maxWait) {
707            synchronized(this) {
708                _maxWait = maxWait;
709            }
710            allocate();
711        }
712    
713        /**
714         * Returns the cap on the number of "idle" instances in the pool.
715         * @return the cap on the number of "idle" instances in the pool.
716         * @see #setMaxIdle
717         */
718        public synchronized int getMaxIdle() {
719            return _maxIdle;
720        }
721    
722        /**
723         * Sets the cap on the number of "idle" instances in the pool.
724         * If maxIdle is set too low on heavily loaded systems it is possible you
725         * will see objects being destroyed and almost immediately new objects
726         * being created. This is a result of the active threads momentarily
727         * returning objects faster than they are requesting them them, causing the
728         * number of idle objects to rise above maxIdle. The best value for maxIdle
729         * for heavily loaded system will vary but the default is a good starting
730         * point.
731         * @param maxIdle The cap on the number of "idle" instances in the pool.
732         * Use a negative value to indicate an unlimited number of idle instances.
733         * @see #getMaxIdle
734         */
735        public void setMaxIdle(int maxIdle) {
736            synchronized(this) {
737                _maxIdle = maxIdle;
738            }
739            allocate();
740        }
741    
742        /**
743         * Sets the minimum number of objects allowed in the pool
744         * before the evictor thread (if active) spawns new objects.
745         * Note that no objects are created when
746         * <code>numActive + numIdle >= maxActive.</code>
747         * This setting has no effect if the idle object evictor is disabled
748         * (i.e. if <code>timeBetweenEvictionRunsMillis <= 0</code>).
749         *
750         * @param minIdle The minimum number of objects.
751         * @see #getMinIdle
752         * @see #getTimeBetweenEvictionRunsMillis()
753         */
754        public void setMinIdle(int minIdle) {
755            synchronized(this) {
756                _minIdle = minIdle;
757            }
758            allocate();
759        }
760    
761        /**
762         * Returns the minimum number of objects allowed in the pool
763         * before the evictor thread (if active) spawns new objects.
764         * (Note no objects are created when: numActive + numIdle >= maxActive)
765         *
766         * @return The minimum number of objects.
767         * @see #setMinIdle
768         */
769        public synchronized int getMinIdle() {
770            return _minIdle;
771        }
772    
773        /**
774         * When <tt>true</tt>, objects will be
775         * {@link PoolableObjectFactory#validateObject validated}
776         * before being returned by the {@link #borrowObject}
777         * method.  If the object fails to validate,
778         * it will be dropped from the pool, and we will attempt
779         * to borrow another.
780         *
781         * @return <code>true</code> if objects are validated before being borrowed.
782         * @see #setTestOnBorrow
783         */
784        public boolean getTestOnBorrow() {
785            return _testOnBorrow;
786        }
787    
788        /**
789         * When <tt>true</tt>, objects will be
790         * {@link PoolableObjectFactory#validateObject validated}
791         * before being returned by the {@link #borrowObject}
792         * method.  If the object fails to validate,
793         * it will be dropped from the pool, and we will attempt
794         * to borrow another.
795         *
796         * @param testOnBorrow <code>true</code> if objects should be validated before being borrowed.
797         * @see #getTestOnBorrow
798         */
799        public void setTestOnBorrow(boolean testOnBorrow) {
800            _testOnBorrow = testOnBorrow;
801        }
802    
803        /**
804         * When <tt>true</tt>, objects will be
805         * {@link PoolableObjectFactory#validateObject validated}
806         * before being returned to the pool within the
807         * {@link #returnObject}.
808         *
809         * @return <code>true</code> when objects will be validated after returned to {@link #returnObject}.
810         * @see #setTestOnReturn
811         */
812        public boolean getTestOnReturn() {
813            return _testOnReturn;
814        }
815    
816        /**
817         * When <tt>true</tt>, objects will be
818         * {@link PoolableObjectFactory#validateObject validated}
819         * before being returned to the pool within the
820         * {@link #returnObject}.
821         *
822         * @param testOnReturn <code>true</code> so objects will be validated after returned to {@link #returnObject}.
823         * @see #getTestOnReturn
824         */
825        public void setTestOnReturn(boolean testOnReturn) {
826            _testOnReturn = testOnReturn;
827        }
828    
829        /**
830         * Returns the number of milliseconds to sleep between runs of the
831         * idle object evictor thread.
832         * When non-positive, no idle object evictor thread will be
833         * run.
834         *
835         * @return number of milliseconds to sleep between evictor runs.
836         * @see #setTimeBetweenEvictionRunsMillis
837         */
838        public synchronized long getTimeBetweenEvictionRunsMillis() {
839            return _timeBetweenEvictionRunsMillis;
840        }
841    
842        /**
843         * Sets the number of milliseconds to sleep between runs of the
844         * idle object evictor thread.
845         * When non-positive, no idle object evictor thread will be
846         * run.
847         *
848         * @param timeBetweenEvictionRunsMillis number of milliseconds to sleep between evictor runs.
849         * @see #getTimeBetweenEvictionRunsMillis
850         */
851        public synchronized void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) {
852            _timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
853            startEvictor(_timeBetweenEvictionRunsMillis);
854        }
855    
856        /**
857         * Returns the max number of objects to examine during each run of the
858         * idle object evictor thread (if any).
859         *
860         * @return max number of objects to examine during each evictor run.
861         * @see #setNumTestsPerEvictionRun
862         * @see #setTimeBetweenEvictionRunsMillis
863         */
864        public synchronized int getNumTestsPerEvictionRun() {
865            return _numTestsPerEvictionRun;
866        }
867    
868        /**
869         * Sets the max number of objects to examine during each run of the
870         * idle object evictor thread (if any).
871         * <p>
872         * When a negative value is supplied, <tt>ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})</tt>
873         * tests will be run.  That is, when the value is <i>-n</i>, roughly one <i>n</i>th of the
874         * idle objects will be tested per run. When the value is positive, the number of tests
875         * actually performed in each run will be the minimum of this value and the number of instances
876         * idle in the pool.
877         *
878         * @param numTestsPerEvictionRun max number of objects to examine during each evictor run.
879         * @see #getNumTestsPerEvictionRun
880         * @see #setTimeBetweenEvictionRunsMillis
881         */
882        public synchronized void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) {
883            _numTestsPerEvictionRun = numTestsPerEvictionRun;
884        }
885    
886        /**
887         * Returns the minimum amount of time an object may sit idle in the pool
888         * before it is eligible for eviction by the idle object evictor
889         * (if any).
890         *
891         * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
892         * @see #setMinEvictableIdleTimeMillis
893         * @see #setTimeBetweenEvictionRunsMillis
894         */
895        public synchronized long getMinEvictableIdleTimeMillis() {
896            return _minEvictableIdleTimeMillis;
897        }
898    
899        /**
900         * Sets the minimum amount of time an object may sit idle in the pool
901         * before it is eligible for eviction by the idle object evictor
902         * (if any).
903         * When non-positive, no objects will be evicted from the pool
904         * due to idle time alone.
905         * @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
906         * it is eligible for eviction.
907         * @see #getMinEvictableIdleTimeMillis
908         * @see #setTimeBetweenEvictionRunsMillis
909         */
910        public synchronized void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) {
911            _minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
912        }
913    
914        /**
915         * Returns the minimum amount of time an object may sit idle in the pool
916         * before it is eligible for eviction by the idle object evictor
917         * (if any), with the extra condition that at least
918         * "minIdle" amount of object remain in the pool.
919         *
920         * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
921         * @since Pool 1.3
922         * @see #setSoftMinEvictableIdleTimeMillis
923         */
924        public synchronized long getSoftMinEvictableIdleTimeMillis() {
925            return _softMinEvictableIdleTimeMillis;
926        }
927    
928        /**
929         * Sets the minimum amount of time an object may sit idle in the pool
930         * before it is eligible for eviction by the idle object evictor
931         * (if any), with the extra condition that at least
932         * "minIdle" object instances remain in the pool.
933         * When non-positive, no objects will be evicted from the pool
934         * due to idle time alone.
935         *
936         * @param softMinEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
937         * it is eligible for eviction.
938         * @since Pool 1.3
939         * @see #getSoftMinEvictableIdleTimeMillis
940         */
941        public synchronized void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis) {
942            _softMinEvictableIdleTimeMillis = softMinEvictableIdleTimeMillis;
943        }
944    
945        /**
946         * When <tt>true</tt>, objects will be
947         * {@link PoolableObjectFactory#validateObject validated}
948         * by the idle object evictor (if any).  If an object
949         * fails to validate, it will be dropped from the pool.
950         *
951         * @return <code>true</code> when objects will be validated by the evictor.
952         * @see #setTestWhileIdle
953         * @see #setTimeBetweenEvictionRunsMillis
954         */
955        public synchronized boolean getTestWhileIdle() {
956            return _testWhileIdle;
957        }
958    
959        /**
960         * When <tt>true</tt>, objects will be
961         * {@link PoolableObjectFactory#validateObject validated}
962         * by the idle object evictor (if any).  If an object
963         * fails to validate, it will be dropped from the pool.
964         *
965         * @param testWhileIdle <code>true</code> so objects will be validated by the evictor.
966         * @see #getTestWhileIdle
967         * @see #setTimeBetweenEvictionRunsMillis
968         */
969        public synchronized void setTestWhileIdle(boolean testWhileIdle) {
970            _testWhileIdle = testWhileIdle;
971        }
972    
973        /**
974         * Whether or not the idle object pool acts as a LIFO queue. True means
975         * that borrowObject returns the most recently used ("last in") idle object
976         * in the pool (if there are idle instances available).  False means that
977         * the pool behaves as a FIFO queue - objects are taken from the idle object
978         * pool in the order that they are returned to the pool.
979         *
980         * @return <code>true</true> if the pool is configured to act as a LIFO queue
981         * @since 1.4
982         */
983         public synchronized boolean getLifo() {
984             return _lifo;
985         }
986    
987         /**
988          * Sets the LIFO property of the pool. True means that borrowObject returns
989          * the most recently used ("last in") idle object in the pool (if there are
990          * idle instances available).  False means that the pool behaves as a FIFO
991          * queue - objects are taken from the idle object pool in the order that
992          * they are returned to the pool.
993          *
994          * @param lifo the new value for the LIFO property
995          * @since 1.4
996          */
997         public synchronized void setLifo(boolean lifo) {
998             this._lifo = lifo;
999         }
1000    
1001        /**
1002         * Sets my configuration.
1003         *
1004         * @param conf configuration to use.
1005         * @see GenericObjectPool.Config
1006         */
1007        public void setConfig(GenericObjectPool.Config conf) {
1008            synchronized (this) {
1009                setMaxIdle(conf.maxIdle);
1010                setMinIdle(conf.minIdle);
1011                setMaxActive(conf.maxActive);
1012                setMaxWait(conf.maxWait);
1013                setWhenExhaustedAction(conf.whenExhaustedAction);
1014                setTestOnBorrow(conf.testOnBorrow);
1015                setTestOnReturn(conf.testOnReturn);
1016                setTestWhileIdle(conf.testWhileIdle);
1017                setNumTestsPerEvictionRun(conf.numTestsPerEvictionRun);
1018                setMinEvictableIdleTimeMillis(conf.minEvictableIdleTimeMillis);
1019                setTimeBetweenEvictionRunsMillis(conf.timeBetweenEvictionRunsMillis);
1020                setSoftMinEvictableIdleTimeMillis(conf.softMinEvictableIdleTimeMillis);
1021                setLifo(conf.lifo);
1022            }
1023            allocate();
1024        }
1025    
1026        //-- ObjectPool methods ------------------------------------------
1027    
1028        /**
1029         * <p>Borrows an object from the pool.</p>
1030         * 
1031         * <p>If there is an idle instance available in the pool, then either the most-recently returned
1032         * (if {@link #getLifo() lifo} == true) or "oldest" (lifo == false) instance sitting idle in the pool
1033         * will be activated and returned.  If activation fails, or {@link #getTestOnBorrow() testOnBorrow} is set
1034         * to true and validation fails, the instance is destroyed and the next available instance is examined.
1035         * This continues until either a valid instance is returned or there are no more idle instances available.</p>
1036         * 
1037         * <p>If there are no idle instances available in the pool, behavior depends on the {@link #getMaxActive() maxActive}
1038         * and (if applicable) {@link #getWhenExhaustedAction() whenExhaustedAction} and {@link #getMaxWait() maxWait}
1039         * properties. If the number of instances checked out from the pool is less than <code>maxActive,</code> a new
1040         * instance is created, activated and (if applicable) validated and returned to the caller.</p>
1041         * 
1042         * <p>If the pool is exhausted (no available idle instances and no capacity to create new ones),
1043         * this method will either block ({@link #WHEN_EXHAUSTED_BLOCK}), throw a <code>NoSuchElementException</code>
1044         * ({@link #WHEN_EXHAUSTED_FAIL}), or grow ({@link #WHEN_EXHAUSTED_GROW} - ignoring maxActive).
1045         * The length of time that this method will block when <code>whenExhaustedAction == WHEN_EXHAUSTED_BLOCK</code>
1046         * is determined by the {@link #getMaxWait() maxWait} property.</p>
1047         * 
1048         * <p>When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances
1049         * to become available.  As of pool 1.5, a "fairness" algorithm has been implemented to ensure that threads receive
1050         * available instances in request arrival order.</p>
1051         * 
1052         * @return object instance
1053         * @throws NoSuchElementException if an instance cannot be returned
1054         */
1055        public Object borrowObject() throws Exception {
1056            long starttime = System.currentTimeMillis();
1057            Latch latch = new Latch();
1058            byte whenExhaustedAction;
1059            long maxWait;
1060            synchronized (this) {
1061                // Get local copy of current config. Can't sync when used later as
1062                // it can result in a deadlock. Has the added advantage that config
1063                // is consistent for entire method execution
1064                whenExhaustedAction = _whenExhaustedAction;
1065                maxWait = _maxWait;
1066    
1067                // Add this request to the queue
1068                _allocationQueue.add(latch);
1069            }
1070            // Work the allocation queue, allocating idle instances and
1071            // instance creation permits in request arrival order
1072            allocate();
1073    
1074            for(;;) {
1075                synchronized (this) {
1076                    assertOpen();
1077                }
1078    
1079                // If no object was allocated from the pool above
1080                if(latch.getPair() == null) {
1081                    // check if we were allowed to create one
1082                    if(latch.mayCreate()) {
1083                        // allow new object to be created
1084                    } else {
1085                        // the pool is exhausted
1086                        switch(whenExhaustedAction) {
1087                            case WHEN_EXHAUSTED_GROW:
1088                                // allow new object to be created
1089                                synchronized (this) {
1090                                    // Make sure another thread didn't allocate us an object
1091                                    // or permit a new object to be created
1092                                    if (latch.getPair() == null && !latch.mayCreate()) {
1093                                        _allocationQueue.remove(latch);
1094                                        _numInternalProcessing++;
1095                                    }
1096                                }
1097                                break;
1098                            case WHEN_EXHAUSTED_FAIL:
1099                                synchronized (this) {
1100                                    // Make sure allocate hasn't already assigned an object
1101                                    // in a different thread or permitted a new object to be created
1102                                    if (latch.getPair() != null || latch.mayCreate()) {
1103                                        break;
1104                                    }
1105                                    _allocationQueue.remove(latch);
1106                                }
1107                                throw new NoSuchElementException("Pool exhausted");
1108                            case WHEN_EXHAUSTED_BLOCK:
1109                                try {
1110                                    synchronized (latch) {
1111                                        // Before we wait, make sure another thread didn't allocate us an object
1112                                        // or permit a new object to be created
1113                                        if (latch.getPair() == null && !latch.mayCreate()) {
1114                                            if(maxWait <= 0) {
1115                                                latch.wait();
1116                                            } else {
1117                                                // this code may be executed again after a notify then continue cycle
1118                                                // so, need to calculate the amount of time to wait
1119                                                final long elapsed = (System.currentTimeMillis() - starttime);
1120                                                final long waitTime = maxWait - elapsed;
1121                                                if (waitTime > 0)
1122                                                {
1123                                                    latch.wait(waitTime);
1124                                                }
1125                                            }
1126                                        } else {
1127                                            break;
1128                                        }
1129                                    }
1130                                    // see if we were awakened by a closing pool
1131                                    if(isClosed() == true) {
1132                                        throw new IllegalStateException("Pool closed");
1133                                    }
1134                                } catch(InterruptedException e) {
1135                                    boolean doAllocate = false;
1136                                    synchronized(this) {
1137                                        // Need to handle the all three possibilities
1138                                        if (latch.getPair() == null && !latch.mayCreate()) {
1139                                            // Case 1: latch still in allocation queue
1140                                            // Remove latch from the allocation queue
1141                                            _allocationQueue.remove(latch);
1142                                        } else if (latch.getPair() == null && latch.mayCreate()) {
1143                                            // Case 2: latch has been given permission to create
1144                                            //         a new object
1145                                            _numInternalProcessing--;
1146                                            doAllocate = true;
1147                                        } else {
1148                                            // Case 3: An object has been allocated
1149                                            _numInternalProcessing--;
1150                                            _numActive++;
1151                                            returnObject(latch.getPair().getValue());
1152                                        }
1153                                    }
1154                                    if (doAllocate) {
1155                                        allocate();
1156                                    }
1157                                    Thread.currentThread().interrupt();
1158                                    throw e;
1159                                }
1160                                if(maxWait > 0 && ((System.currentTimeMillis() - starttime) >= maxWait)) {
1161                                    synchronized(this) {
1162                                        // Make sure allocate hasn't already assigned an object
1163                                        // in a different thread or permitted a new object to be created
1164                                        if (latch.getPair() == null && !latch.mayCreate()) {
1165                                            // Remove latch from the allocation queue
1166                                            _allocationQueue.remove(latch);
1167                                        } else {
1168                                            break;
1169                                        }
1170                                    }
1171                                    throw new NoSuchElementException("Timeout waiting for idle object");
1172                                } else {
1173                                    continue; // keep looping
1174                                }
1175                            default:
1176                                throw new IllegalArgumentException("WhenExhaustedAction property " + whenExhaustedAction +
1177                                        " not recognized.");
1178                        }
1179                    }
1180                }
1181    
1182                boolean newlyCreated = false;
1183                if(null == latch.getPair()) {
1184                    try {
1185                        Object obj = _factory.makeObject();
1186                        latch.setPair(new ObjectTimestampPair(obj));
1187                        newlyCreated = true;
1188                    } finally {
1189                        if (!newlyCreated) {
1190                            // object cannot be created
1191                            synchronized (this) {
1192                                _numInternalProcessing--;
1193                                // No need to reset latch - about to throw exception
1194                            }
1195                            allocate();
1196                        }
1197                    }
1198                }
1199                // activate & validate the object
1200                try {
1201                    _factory.activateObject(latch.getPair().value);
1202                    if(_testOnBorrow &&
1203                            !_factory.validateObject(latch.getPair().value)) {
1204                        throw new Exception("ValidateObject failed");
1205                    }
1206                    synchronized(this) {
1207                        _numInternalProcessing--;
1208                        _numActive++;
1209                    }
1210                    return latch.getPair().value;
1211                }
1212                catch (Throwable e) {
1213                    PoolUtils.checkRethrow(e);
1214                    // object cannot be activated or is invalid
1215                    try {
1216                        _factory.destroyObject(latch.getPair().value);
1217                    } catch (Throwable e2) {
1218                        PoolUtils.checkRethrow(e2);
1219                        // cannot destroy broken object
1220                    }
1221                    synchronized (this) {
1222                        _numInternalProcessing--;
1223                        if (!newlyCreated) {
1224                            latch.reset();
1225                            _allocationQueue.add(0, latch);
1226                        }
1227                    }
1228                    allocate();
1229                    if(newlyCreated) {
1230                        throw new NoSuchElementException("Could not create a validated object, cause: " + e.getMessage());
1231                    }
1232                    else {
1233                        continue; // keep looping
1234                    }
1235                }
1236            }
1237        }
1238    
1239        /**
1240         * Allocate available instances to latches in the allocation queue.  Then
1241         * set _mayCreate to true for as many additional latches remaining in queue
1242         * as _maxActive allows. While it is safe for GOP, for consistency with GKOP
1243         * this method should not be called from inside a sync block. 
1244         */
1245        private synchronized void allocate() {
1246            if (isClosed()) return;
1247    
1248            // First use any objects in the pool to clear the queue
1249            for (;;) {
1250                if (!_pool.isEmpty() && !_allocationQueue.isEmpty()) {
1251                    Latch latch = (Latch) _allocationQueue.removeFirst();
1252                    latch.setPair((ObjectTimestampPair) _pool.removeFirst());
1253                    _numInternalProcessing++;
1254                    synchronized (latch) {
1255                        latch.notify();
1256                    }
1257                } else {
1258                    break;
1259                }
1260            }
1261    
1262            // Second utilise any spare capacity to create new objects
1263            for(;;) {
1264                if((!_allocationQueue.isEmpty()) && (_maxActive < 0 || (_numActive + _numInternalProcessing) < _maxActive)) {
1265                    Latch latch = (Latch) _allocationQueue.removeFirst();
1266                    latch.setMayCreate(true);
1267                    _numInternalProcessing++;
1268                    synchronized (latch) {
1269                        latch.notify();
1270                    }
1271                } else {
1272                    break;
1273                }
1274            }
1275        }
1276    
1277        /**
1278         * {@inheritDoc}
1279         * <p>Activation of this method decrements the active count and attempts to destroy the instance.</p>
1280         * 
1281         * @throws Exception if the configured {@link PoolableObjectFactory} throws an exception destroying obj
1282         */
1283        public void invalidateObject(Object obj) throws Exception {
1284            try {
1285                if (_factory != null) {
1286                    _factory.destroyObject(obj);
1287                }
1288            } finally {
1289                synchronized (this) {
1290                    _numActive--;
1291                }
1292                allocate();
1293            }
1294        }
1295    
1296        /**
1297         * Clears any objects sitting idle in the pool by removing them from the
1298         * idle instance pool and then invoking the configured 
1299         * {@link PoolableObjectFactory#destroyObject(Object)} method on each idle
1300         * instance. 
1301         * 
1302         * <p> Implementation notes:
1303         * <ul><li>This method does not destroy or effect in any way instances that are
1304         * checked out of the pool when it is invoked.</li>
1305         * <li>Invoking this method does not prevent objects being
1306         * returned to the idle instance pool, even during its execution. It locks
1307         * the pool only during instance removal. Additional instances may be returned
1308         * while removed items are being destroyed.</li>
1309         * <li>Exceptions encountered destroying idle instances are swallowed.</li></ul></p>
1310         */
1311        public void clear() {
1312            List toDestroy = new ArrayList();
1313    
1314            synchronized(this) {
1315                toDestroy.addAll(_pool);
1316                _numInternalProcessing = _numInternalProcessing + _pool._size;
1317                _pool.clear();
1318            }
1319            destroy(toDestroy, _factory);
1320        }
1321    
1322        /**
1323         * Private method to destroy all the objects in a collection using the 
1324         * supplied object factory.  Assumes that objects in the collection are
1325         * instances of ObjectTimestampPair and that the object instances that
1326         * they wrap were created by the factory.
1327         * 
1328         * @param c Collection of objects to destroy
1329         * @param factory PoolableConnectionFactory used to destroy the objects
1330         */
1331        private void destroy(Collection c, PoolableObjectFactory factory) {
1332            for (Iterator it = c.iterator(); it.hasNext();) {
1333                try {
1334                    factory.destroyObject(((ObjectTimestampPair)(it.next())).value);
1335                } catch(Exception e) {
1336                    // ignore error, keep destroying the rest
1337                } finally {
1338                    synchronized(this) {
1339                        _numInternalProcessing--;
1340                    }
1341                    allocate();
1342                }
1343            }
1344        }
1345    
1346        /**
1347         * Return the number of instances currently borrowed from this pool.
1348         *
1349         * @return the number of instances currently borrowed from this pool
1350         */
1351        public synchronized int getNumActive() {
1352            return _numActive;
1353        }
1354    
1355        /**
1356         * Return the number of instances currently idle in this pool.
1357         *
1358         * @return the number of instances currently idle in this pool
1359         */
1360        public synchronized int getNumIdle() {
1361            return _pool.size();
1362        }
1363    
1364        /**
1365         * <p>Returns an object instance to the pool.</p>
1366         * 
1367         * <p>If {@link #getMaxIdle() maxIdle} is set to a positive value and the number of idle instances
1368         * has reached this value, the returning instance is destroyed.</p>
1369         * 
1370         * <p>If {@link #getTestOnReturn() testOnReturn} == true, the returning instance is validated before being returned
1371         * to the idle instance pool.  In this case, if validation fails, the instance is destroyed.</p>
1372         * 
1373         * <p><strong>Note: </strong> There is no guard to prevent an object
1374         * being returned to the pool multiple times. Clients are expected to
1375         * discard references to returned objects and ensure that an object is not
1376         * returned to the pool multiple times in sequence (i.e., without being
1377         * borrowed again between returns). Violating this contract will result in
1378         * the same object appearing multiple times in the pool and pool counters
1379         * (numActive, numIdle) returning incorrect values.</p>
1380         * 
1381         * @param obj instance to return to the pool
1382         */
1383        public void returnObject(Object obj) throws Exception {
1384            try {
1385                addObjectToPool(obj, true);
1386            } catch (Exception e) {
1387                if (_factory != null) {
1388                    try {
1389                        _factory.destroyObject(obj);
1390                    } catch (Exception e2) {
1391                        // swallowed
1392                    }
1393                    // TODO: Correctness here depends on control in addObjectToPool.
1394                    // These two methods should be refactored, removing the
1395                    // "behavior flag", decrementNumActive, from addObjectToPool.
1396                    synchronized(this) {
1397                        _numActive--;
1398                    }
1399                    allocate();
1400                }
1401            }
1402        }
1403    
1404        /**
1405         * <p>Adds an object to the pool.</p>
1406         * 
1407         * <p>Validates the object if testOnReturn == true and passivates it before returning it to the pool.
1408         * if validation or passivation fails, or maxIdle is set and there is no room in the pool, the instance
1409         * is destroyed.</p>
1410         * 
1411         * <p>Calls {@link #allocate()} on successful completion</p>
1412         * 
1413         * @param obj instance to add to the pool
1414         * @param decrementNumActive whether or not to decrement the active count
1415         * @throws Exception
1416         */
1417        private void addObjectToPool(Object obj, boolean decrementNumActive) throws Exception {
1418            boolean success = true;
1419            if(_testOnReturn && !(_factory.validateObject(obj))) {
1420                success = false;
1421            } else {
1422                _factory.passivateObject(obj);
1423            }
1424    
1425            boolean shouldDestroy = !success;
1426    
1427            // Add instance to pool if there is room and it has passed validation
1428            // (if testOnreturn is set)
1429            boolean doAllocate = false;
1430            synchronized (this) {
1431                if (isClosed()) {
1432                    shouldDestroy = true;
1433                } else {
1434                    if((_maxIdle >= 0) && (_pool.size() >= _maxIdle)) {
1435                        shouldDestroy = true;
1436                    } else if(success) {
1437                        // borrowObject always takes the first element from the queue,
1438                        // so for LIFO, push on top, FIFO add to end
1439                        if (_lifo) {
1440                            _pool.addFirst(new ObjectTimestampPair(obj));
1441                        } else {
1442                            _pool.addLast(new ObjectTimestampPair(obj));
1443                        }
1444                        if (decrementNumActive) {
1445                            _numActive--;
1446                        }
1447                        doAllocate = true;
1448                    }
1449                }
1450            }
1451            if (doAllocate) {
1452                allocate();
1453            }
1454    
1455            // Destroy the instance if necessary
1456            if(shouldDestroy) {
1457                try {
1458                    _factory.destroyObject(obj);
1459                } catch(Exception e) {
1460                    // ignored
1461                }
1462                // Decrement active count *after* destroy if applicable
1463                if (decrementNumActive) {
1464                    synchronized(this) {
1465                        _numActive--;
1466                    }
1467                    allocate();
1468                }
1469            }
1470    
1471        }
1472    
1473        /**
1474         * <p>Closes the pool.  Once the pool is closed, {@link #borrowObject()}
1475         * will fail with IllegalStateException, but {@link #returnObject(Object)} and
1476         * {@link #invalidateObject(Object)} will continue to work, with returned objects
1477         * destroyed on return.</p>
1478         * 
1479         * <p>Destroys idle instances in the pool by invoking {@link #clear()}.</p> 
1480         * 
1481         * @throws Exception
1482         */
1483        public void close() throws Exception {
1484            super.close();
1485            synchronized (this) {
1486                clear();
1487                startEvictor(-1L);
1488    
1489                while(_allocationQueue.size() > 0) {
1490                    Latch l = (Latch) _allocationQueue.removeFirst();
1491                    
1492                    synchronized (l) {
1493                        // notify the waiting thread
1494                        l.notify();
1495                    }
1496                }
1497            }
1498        }
1499    
1500        /**
1501         * Sets the {@link PoolableObjectFactory factory} this pool uses
1502         * to create new instances. Trying to change
1503         * the <code>factory</code> while there are borrowed objects will
1504         * throw an {@link IllegalStateException}.  If there are instances idle
1505         * in the pool when this method is invoked, these will be destroyed
1506         * using the original factory.
1507         *
1508         * @param factory the {@link PoolableObjectFactory} used to create new instances.
1509         * @throws IllegalStateException when the factory cannot be set at this time
1510         * @deprecated to be removed in version 2.0
1511         */
1512        public void setFactory(PoolableObjectFactory factory) throws IllegalStateException {
1513            List toDestroy = new ArrayList();
1514            final PoolableObjectFactory oldFactory = _factory;
1515            synchronized (this) {
1516                assertOpen();
1517                if(0 < getNumActive()) {
1518                    throw new IllegalStateException("Objects are already active");
1519                } else {
1520                    toDestroy.addAll(_pool);
1521                    _numInternalProcessing = _numInternalProcessing + _pool._size;
1522                    _pool.clear();
1523                }
1524                _factory = factory;
1525            }
1526            destroy(toDestroy, oldFactory); 
1527        }
1528    
1529        /**
1530         * <p>Perform <code>numTests</code> idle object eviction tests, evicting
1531         * examined objects that meet the criteria for eviction. If
1532         * <code>testWhileIdle</code> is true, examined objects are validated
1533         * when visited (and removed if invalid); otherwise only objects that
1534         * have been idle for more than <code>minEvicableIdletimeMillis</code>
1535         * are removed.</p>
1536         *
1537         * <p>Successive activations of this method examine objects in
1538         * in sequence, cycling through objects in oldest-to-youngest order.</p>
1539         *
1540         * @throws Exception if the pool is closed or eviction fails.
1541         */
1542        public void evict() throws Exception {
1543            assertOpen();
1544            synchronized (this) {
1545                if(_pool.isEmpty()) {
1546                    return;
1547                }
1548                if (null == _evictionCursor) {
1549                    _evictionCursor = (_pool.cursor(_lifo ? _pool.size() : 0));
1550                }
1551            }
1552    
1553            for (int i=0,m=getNumTests();i<m;i++) {
1554                final ObjectTimestampPair pair;
1555                synchronized (this) {
1556                    if ((_lifo && !_evictionCursor.hasPrevious()) ||
1557                            !_lifo && !_evictionCursor.hasNext()) {
1558                        _evictionCursor.close();
1559                        _evictionCursor = _pool.cursor(_lifo ? _pool.size() : 0);
1560                    }
1561    
1562                    pair = _lifo ?
1563                            (ObjectTimestampPair) _evictionCursor.previous() :
1564                            (ObjectTimestampPair) _evictionCursor.next();
1565    
1566                    _evictionCursor.remove();
1567                    _numInternalProcessing++;
1568                }
1569    
1570                boolean removeObject = false;
1571                final long idleTimeMilis = System.currentTimeMillis() - pair.tstamp;
1572                if ((getMinEvictableIdleTimeMillis() > 0) &&
1573                        (idleTimeMilis > getMinEvictableIdleTimeMillis())) {
1574                    removeObject = true;
1575                } else if ((getSoftMinEvictableIdleTimeMillis() > 0) &&
1576                        (idleTimeMilis > getSoftMinEvictableIdleTimeMillis()) &&
1577                        ((getNumIdle() + 1)> getMinIdle())) { // +1 accounts for object we are processing
1578                    removeObject = true;
1579                }
1580                if(getTestWhileIdle() && !removeObject) {
1581                    boolean active = false;
1582                    try {
1583                        _factory.activateObject(pair.value);
1584                        active = true;
1585                    } catch(Exception e) {
1586                        removeObject=true;
1587                    }
1588                    if(active) {
1589                        if(!_factory.validateObject(pair.value)) {
1590                            removeObject=true;
1591                        } else {
1592                            try {
1593                                _factory.passivateObject(pair.value);
1594                            } catch(Exception e) {
1595                                removeObject=true;
1596                            }
1597                        }
1598                    }
1599                }
1600    
1601                if (removeObject) {
1602                    try {
1603                        _factory.destroyObject(pair.value);
1604                    } catch(Exception e) {
1605                        // ignored
1606                    }
1607                }
1608                synchronized (this) {
1609                    if(!removeObject) {
1610                        _evictionCursor.add(pair);
1611                        if (_lifo) {
1612                            // Skip over the element we just added back
1613                            _evictionCursor.previous();
1614                        }
1615                    }
1616                    _numInternalProcessing--;
1617                }
1618            }
1619            allocate();
1620        }
1621    
1622        /**
1623         * Check to see if we are below our minimum number of objects
1624         * if so enough to bring us back to our minimum.
1625         *
1626         * @throws Exception when {@link #addObject()} fails.
1627         */
1628        private void ensureMinIdle() throws Exception {
1629            // this method isn't synchronized so the
1630            // calculateDeficit is done at the beginning
1631            // as a loop limit and a second time inside the loop
1632            // to stop when another thread already returned the
1633            // needed objects
1634            int objectDeficit = calculateDeficit(false);
1635            for ( int j = 0 ; j < objectDeficit && calculateDeficit(true) > 0 ; j++ ) {
1636                try {
1637                    addObject();
1638                } finally {
1639                    synchronized (this) {
1640                        _numInternalProcessing--;
1641                    }
1642                    allocate();
1643                }
1644            }
1645        }
1646    
1647        /**
1648         * This returns the number of objects to create during the pool
1649         * sustain cycle. This will ensure that the minimum number of idle
1650         * instances is maintained without going past the maxActive value.
1651         *
1652         * @param incrementInternal - Should the count of objects currently under
1653         *                            some form of internal processing be
1654         *                            incremented?
1655         * @return The number of objects to be created
1656         */
1657        private synchronized int calculateDeficit(boolean incrementInternal) {
1658            int objectDeficit = getMinIdle() - getNumIdle();
1659            if (_maxActive > 0) {
1660                int growLimit = Math.max(0,
1661                        getMaxActive() - getNumActive() - getNumIdle() - _numInternalProcessing);
1662                objectDeficit = Math.min(objectDeficit, growLimit);
1663            }
1664            if (incrementInternal && objectDeficit >0) {
1665                _numInternalProcessing++;
1666            }
1667            return objectDeficit;
1668        }
1669    
1670        /**
1671         * Create an object, and place it into the pool.
1672         * addObject() is useful for "pre-loading" a pool with idle objects.
1673         */
1674        public void addObject() throws Exception {
1675            assertOpen();
1676            if (_factory == null) {
1677                throw new IllegalStateException("Cannot add objects without a factory.");
1678            }
1679            Object obj = _factory.makeObject();
1680            try {
1681                assertOpen();
1682                addObjectToPool(obj, false);
1683            } catch (IllegalStateException ex) { // Pool closed
1684                try {
1685                    _factory.destroyObject(obj);
1686                } catch (Exception ex2) {
1687                    // swallow
1688                }
1689                throw ex;
1690            }
1691        }
1692    
1693        //--- non-public methods ----------------------------------------
1694    
1695        /**
1696         * Start the eviction thread or service, or when
1697         * <i>delay</i> is non-positive, stop it
1698         * if it is already running.
1699         *
1700         * @param delay milliseconds between evictor runs.
1701         */
1702        protected synchronized void startEvictor(long delay) {
1703            if(null != _evictor) {
1704                EvictionTimer.cancel(_evictor);
1705                _evictor = null;
1706            }
1707            if(delay > 0) {
1708                _evictor = new Evictor();
1709                EvictionTimer.schedule(_evictor, delay, delay);
1710            }
1711        }
1712    
1713        /**
1714         * Returns pool info including {@link #getNumActive()}, {@link #getNumIdle()}
1715         * and a list of objects idle in the pool with their idle times.
1716         * 
1717         * @return string containing debug information
1718         */
1719        synchronized String debugInfo() {
1720            StringBuffer buf = new StringBuffer();
1721            buf.append("Active: ").append(getNumActive()).append("\n");
1722            buf.append("Idle: ").append(getNumIdle()).append("\n");
1723            buf.append("Idle Objects:\n");
1724            Iterator it = _pool.iterator();
1725            long time = System.currentTimeMillis();
1726            while(it.hasNext()) {
1727                ObjectTimestampPair pair = (ObjectTimestampPair)(it.next());
1728                buf.append("\t").append(pair.value).append("\t").append(time - pair.tstamp).append("\n");
1729            }
1730            return buf.toString();
1731        }
1732    
1733        /** 
1734         * Returns the number of tests to be performed in an Evictor run,
1735         * based on the current value of <code>numTestsPerEvictionRun</code>
1736         * and the number of idle instances in the pool.
1737         * 
1738         * @see #setNumTestsPerEvictionRun
1739         * @return the number of tests for the Evictor to run
1740         */
1741        private int getNumTests() {
1742            if(_numTestsPerEvictionRun >= 0) {
1743                return Math.min(_numTestsPerEvictionRun, _pool.size());
1744            } else {
1745                return(int)(Math.ceil(_pool.size()/Math.abs((double)_numTestsPerEvictionRun)));
1746            }
1747        }
1748    
1749        //--- inner classes ----------------------------------------------
1750    
1751        /**
1752         * The idle object evictor {@link TimerTask}.
1753         * @see GenericObjectPool#setTimeBetweenEvictionRunsMillis
1754         */
1755        private class Evictor extends TimerTask {
1756            /**
1757             * Run pool maintenance.  Evict objects qualifying for eviction and then
1758             * invoke {@link GenericObjectPool#ensureMinIdle()}.
1759             */
1760            public void run() {
1761                try {
1762                    evict();
1763                } catch(Exception e) {
1764                    // ignored
1765                } catch(OutOfMemoryError oome) {
1766                    // Log problem but give evictor thread a chance to continue in
1767                    // case error is recoverable
1768                    oome.printStackTrace(System.err);
1769                }
1770                try {
1771                    ensureMinIdle();
1772                } catch(Exception e) {
1773                    // ignored
1774                }
1775            }
1776        }
1777    
1778        /**
1779         * A simple "struct" encapsulating the
1780         * configuration information for a {@link GenericObjectPool}.
1781         * @see GenericObjectPool#GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory,
1782         * org.apache.commons.pool.impl.GenericObjectPool.Config)
1783         * @see GenericObjectPool#setConfig
1784         */
1785        public static class Config {
1786            //CHECKSTYLE: stop VisibilityModifier
1787            /**
1788             * @see GenericObjectPool#setMaxIdle
1789             */
1790            public int maxIdle = GenericObjectPool.DEFAULT_MAX_IDLE;
1791            /**
1792             * @see GenericObjectPool#setMinIdle
1793             */
1794            public int minIdle = GenericObjectPool.DEFAULT_MIN_IDLE;
1795            /**
1796             * @see GenericObjectPool#setMaxActive
1797             */
1798            public int maxActive = GenericObjectPool.DEFAULT_MAX_ACTIVE;
1799            /**
1800             * @see GenericObjectPool#setMaxWait
1801             */
1802            public long maxWait = GenericObjectPool.DEFAULT_MAX_WAIT;
1803            /**
1804             * @see GenericObjectPool#setWhenExhaustedAction
1805             */
1806            public byte whenExhaustedAction = GenericObjectPool.DEFAULT_WHEN_EXHAUSTED_ACTION;
1807            /**
1808             * @see GenericObjectPool#setTestOnBorrow
1809             */
1810            public boolean testOnBorrow = GenericObjectPool.DEFAULT_TEST_ON_BORROW;
1811            /**
1812             * @see GenericObjectPool#setTestOnReturn
1813             */
1814            public boolean testOnReturn = GenericObjectPool.DEFAULT_TEST_ON_RETURN;
1815            /**
1816             * @see GenericObjectPool#setTestWhileIdle
1817             */
1818            public boolean testWhileIdle = GenericObjectPool.DEFAULT_TEST_WHILE_IDLE;
1819            /**
1820             * @see GenericObjectPool#setTimeBetweenEvictionRunsMillis
1821             */
1822            public long timeBetweenEvictionRunsMillis = GenericObjectPool.DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS;
1823            /**
1824             * @see GenericObjectPool#setNumTestsPerEvictionRun
1825             */
1826            public int numTestsPerEvictionRun =  GenericObjectPool.DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
1827            /**
1828             * @see GenericObjectPool#setMinEvictableIdleTimeMillis
1829             */
1830            public long minEvictableIdleTimeMillis = GenericObjectPool.DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
1831            /**
1832             * @see GenericObjectPool#setSoftMinEvictableIdleTimeMillis
1833             */
1834            public long softMinEvictableIdleTimeMillis = GenericObjectPool.DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
1835            /**
1836             * @see GenericObjectPool#setLifo
1837             */
1838            public boolean lifo = GenericObjectPool.DEFAULT_LIFO;
1839            //CHECKSTYLE: resume VisibilityModifier
1840        }
1841    
1842        /**
1843         * Latch used to control allocation order of objects to threads to ensure
1844         * fairness. That is, objects are allocated to threads in the order that
1845         * threads request objects.
1846         */
1847        private static final class Latch {
1848            
1849            /** object timestamp pair allocated to this latch */
1850            private ObjectTimestampPair _pair;
1851            
1852            /** Whether or not this latch may create an object instance */
1853            private boolean _mayCreate = false;
1854    
1855            /**
1856             * Returns ObjectTimestampPair allocated to this latch
1857             * @return ObjectTimestampPair allocated to this latch
1858             */
1859            private synchronized ObjectTimestampPair getPair() {
1860                return _pair;
1861            }
1862            
1863            /**
1864             * Sets ObjectTimestampPair on this latch
1865             * @param pair ObjectTimestampPair allocated to this latch
1866             */
1867            private synchronized void setPair(ObjectTimestampPair pair) {
1868                _pair = pair;
1869            }
1870    
1871            /**
1872             * Whether or not this latch may create an object instance 
1873             * @return true if this latch has an instance creation permit
1874             */
1875            private synchronized boolean mayCreate() {
1876                return _mayCreate;
1877            }
1878            
1879            /**
1880             * Sets the mayCreate property
1881             * @param mayCreate new value for mayCreate
1882             */
1883            private synchronized void setMayCreate(boolean mayCreate) {
1884                _mayCreate = mayCreate;
1885            }
1886    
1887            /**
1888             * Reset the latch data. Used when an allocation fails and the latch
1889             * needs to be re-added to the queue.
1890             */
1891            private synchronized void reset() {
1892                _pair = null;
1893                _mayCreate = false;
1894            }
1895        }
1896    
1897    
1898        //--- private attributes ---------------------------------------
1899    
1900        /**
1901         * The cap on the number of idle instances in the pool.
1902         * @see #setMaxIdle
1903         * @see #getMaxIdle
1904         */
1905        private int _maxIdle = DEFAULT_MAX_IDLE;
1906    
1907        /**
1908        * The cap on the minimum number of idle instances in the pool.
1909        * @see #setMinIdle
1910        * @see #getMinIdle
1911        */
1912        private int _minIdle = DEFAULT_MIN_IDLE;
1913    
1914        /**
1915         * The cap on the total number of active instances from the pool.
1916         * @see #setMaxActive
1917         * @see #getMaxActive
1918         */
1919        private int _maxActive = DEFAULT_MAX_ACTIVE;
1920    
1921        /**
1922         * The maximum amount of time (in millis) the
1923         * {@link #borrowObject} method should block before throwing
1924         * an exception when the pool is exhausted and the
1925         * {@link #getWhenExhaustedAction "when exhausted" action} is
1926         * {@link #WHEN_EXHAUSTED_BLOCK}.
1927         *
1928         * When less than or equal to 0, the {@link #borrowObject} method
1929         * may block indefinitely.
1930         *
1931         * @see #setMaxWait
1932         * @see #getMaxWait
1933         * @see #WHEN_EXHAUSTED_BLOCK
1934         * @see #setWhenExhaustedAction
1935         * @see #getWhenExhaustedAction
1936         */
1937        private long _maxWait = DEFAULT_MAX_WAIT;
1938    
1939        /**
1940         * The action to take when the {@link #borrowObject} method
1941         * is invoked when the pool is exhausted (the maximum number
1942         * of "active" objects has been reached).
1943         *
1944         * @see #WHEN_EXHAUSTED_BLOCK
1945         * @see #WHEN_EXHAUSTED_FAIL
1946         * @see #WHEN_EXHAUSTED_GROW
1947         * @see #DEFAULT_WHEN_EXHAUSTED_ACTION
1948         * @see #setWhenExhaustedAction
1949         * @see #getWhenExhaustedAction
1950         */
1951        private byte _whenExhaustedAction = DEFAULT_WHEN_EXHAUSTED_ACTION;
1952    
1953        /**
1954         * When <tt>true</tt>, objects will be
1955         * {@link PoolableObjectFactory#validateObject validated}
1956         * before being returned by the {@link #borrowObject}
1957         * method.  If the object fails to validate,
1958         * it will be dropped from the pool, and we will attempt
1959         * to borrow another.
1960         *
1961         * @see #setTestOnBorrow
1962         * @see #getTestOnBorrow
1963         */
1964        private volatile boolean _testOnBorrow = DEFAULT_TEST_ON_BORROW;
1965    
1966        /**
1967         * When <tt>true</tt>, objects will be
1968         * {@link PoolableObjectFactory#validateObject validated}
1969         * before being returned to the pool within the
1970         * {@link #returnObject}.
1971         *
1972         * @see #getTestOnReturn
1973         * @see #setTestOnReturn
1974         */
1975        private volatile boolean _testOnReturn = DEFAULT_TEST_ON_RETURN;
1976    
1977        /**
1978         * When <tt>true</tt>, objects will be
1979         * {@link PoolableObjectFactory#validateObject validated}
1980         * by the idle object evictor (if any).  If an object
1981         * fails to validate, it will be dropped from the pool.
1982         *
1983         * @see #setTestWhileIdle
1984         * @see #getTestWhileIdle
1985         * @see #getTimeBetweenEvictionRunsMillis
1986         * @see #setTimeBetweenEvictionRunsMillis
1987         */
1988        private boolean _testWhileIdle = DEFAULT_TEST_WHILE_IDLE;
1989    
1990        /**
1991         * The number of milliseconds to sleep between runs of the
1992         * idle object evictor thread.
1993         * When non-positive, no idle object evictor thread will be
1994         * run.
1995         *
1996         * @see #setTimeBetweenEvictionRunsMillis
1997         * @see #getTimeBetweenEvictionRunsMillis
1998         */
1999        private long _timeBetweenEvictionRunsMillis = DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS;
2000    
2001        /**
2002         * The max number of objects to examine during each run of the
2003         * idle object evictor thread (if any).
2004         * <p>
2005         * When a negative value is supplied, <tt>ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})</tt>
2006         * tests will be run.  I.e., when the value is <i>-n</i>, roughly one <i>n</i>th of the
2007         * idle objects will be tested per run.
2008         *
2009         * @see #setNumTestsPerEvictionRun
2010         * @see #getNumTestsPerEvictionRun
2011         * @see #getTimeBetweenEvictionRunsMillis
2012         * @see #setTimeBetweenEvictionRunsMillis
2013         */
2014        private int _numTestsPerEvictionRun =  DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
2015    
2016        /**
2017         * The minimum amount of time an object may sit idle in the pool
2018         * before it is eligible for eviction by the idle object evictor
2019         * (if any).
2020         * When non-positive, no objects will be evicted from the pool
2021         * due to idle time alone.
2022         *
2023         * @see #setMinEvictableIdleTimeMillis
2024         * @see #getMinEvictableIdleTimeMillis
2025         * @see #getTimeBetweenEvictionRunsMillis
2026         * @see #setTimeBetweenEvictionRunsMillis
2027         */
2028        private long _minEvictableIdleTimeMillis = DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
2029    
2030        /**
2031         * The minimum amount of time an object may sit idle in the pool
2032         * before it is eligible for eviction by the idle object evictor
2033         * (if any), with the extra condition that at least
2034         * "minIdle" amount of object remain in the pool.
2035         * When non-positive, no objects will be evicted from the pool
2036         * due to idle time alone.
2037         *
2038         * @see #setSoftMinEvictableIdleTimeMillis
2039         * @see #getSoftMinEvictableIdleTimeMillis
2040         */
2041        private long _softMinEvictableIdleTimeMillis = DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
2042    
2043        /** Whether or not the pool behaves as a LIFO queue (last in first out) */
2044        private boolean _lifo = DEFAULT_LIFO;
2045    
2046        /** My pool. */
2047        private CursorableLinkedList _pool = null;
2048    
2049        /** Eviction cursor - keeps track of idle object evictor position */
2050        private CursorableLinkedList.Cursor _evictionCursor = null;
2051    
2052        /** My {@link PoolableObjectFactory}. */
2053        private PoolableObjectFactory _factory = null;
2054    
2055        /**
2056         * The number of objects {@link #borrowObject} borrowed
2057         * from the pool, but not yet returned.
2058         */
2059        private int _numActive = 0;
2060    
2061        /**
2062         * My idle object eviction {@link TimerTask}, if any.
2063         */
2064        private Evictor _evictor = null;
2065    
2066        /**
2067         * The number of objects subject to some form of internal processing
2068         * (usually creation or destruction) that should be included in the total
2069         * number of objects but are neither active nor idle.
2070         */
2071        private int _numInternalProcessing = 0;
2072    
2073        /**
2074         * Used to track the order in which threads call {@link #borrowObject()} so
2075         * that objects can be allocated in the order in which the threads requested
2076         * them.
2077         */
2078        private final LinkedList _allocationQueue = new LinkedList();
2079    
2080    }