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