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