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 }