001: /* FairGenericObjectPool
002: *
003: * $Id: FairGenericObjectPool.java 4672 2006-09-27 00:03:16Z paul_jack $
004: *
005: * Created on Apr 7, 2006
006: *
007: * Copyright (C) 2006 Internet Archive.
008: */
009:
010: package org.apache.commons.pool.impl;
011:
012: import java.util.Collections;
013: import java.util.LinkedList;
014: import java.util.List;
015: import java.util.NoSuchElementException;
016:
017: import org.apache.commons.pool.PoolableObjectFactory;
018: import org.apache.commons.pool.impl.GenericKeyedObjectPool.ObjectTimestampPair;
019:
020: /**
021: * Version of GenericObjectPool which is 'fair' with respect to the client
022: * threads using {@link #borrowObject <i>borrowObject</i>}. Those which enter
023: * first will receive objects from the pool first.
024: *
025: *
026: * @see GenericObjectPool
027: * @author Gordon Mohr
028: * @version $Revision: 4672 $ $Date: 2006-09-27 00:03:16 +0000 (Wed, 27 Sep 2006) $
029: */
030: @SuppressWarnings("unchecked")
031: public class FairGenericObjectPool extends GenericObjectPool {
032:
033: //--- constructors -----------------------------------------------
034: // (all copied from superclass; only last adds one additional line of
035: // initialization and call to superclass)
036:
037: /**
038: * Create a new <tt>FairGenericObjectPool</tt>.
039: */
040: public FairGenericObjectPool() {
041: this (null, DEFAULT_MAX_ACTIVE, DEFAULT_WHEN_EXHAUSTED_ACTION,
042: DEFAULT_MAX_WAIT, DEFAULT_MAX_IDLE, DEFAULT_MIN_IDLE,
043: DEFAULT_TEST_ON_BORROW, DEFAULT_TEST_ON_RETURN,
044: DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
045: DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
046: DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,
047: DEFAULT_TEST_WHILE_IDLE);
048: }
049:
050: /**
051: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
052: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
053: */
054: public FairGenericObjectPool(PoolableObjectFactory factory) {
055: this (factory, DEFAULT_MAX_ACTIVE,
056: DEFAULT_WHEN_EXHAUSTED_ACTION, DEFAULT_MAX_WAIT,
057: DEFAULT_MAX_IDLE, DEFAULT_MIN_IDLE,
058: DEFAULT_TEST_ON_BORROW, DEFAULT_TEST_ON_RETURN,
059: DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
060: DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
061: DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,
062: DEFAULT_TEST_WHILE_IDLE);
063: }
064:
065: /**
066: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
067: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
068: * @param config a non-<tt>null</tt> {@link GenericObjectPool.Config} describing my configuration
069: */
070: public FairGenericObjectPool(PoolableObjectFactory factory,
071: GenericObjectPool.Config config) {
072: this (factory, config.maxActive, config.whenExhaustedAction,
073: config.maxWait, config.maxIdle, config.minIdle,
074: config.testOnBorrow, config.testOnReturn,
075: config.timeBetweenEvictionRunsMillis,
076: config.numTestsPerEvictionRun,
077: config.minEvictableIdleTimeMillis, config.testWhileIdle);
078: }
079:
080: /**
081: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
082: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
083: * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
084: */
085: public FairGenericObjectPool(PoolableObjectFactory factory,
086: int maxActive) {
087: this (factory, maxActive, DEFAULT_WHEN_EXHAUSTED_ACTION,
088: DEFAULT_MAX_WAIT, DEFAULT_MAX_IDLE, DEFAULT_MIN_IDLE,
089: DEFAULT_TEST_ON_BORROW, DEFAULT_TEST_ON_RETURN,
090: DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
091: DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
092: DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,
093: DEFAULT_TEST_WHILE_IDLE);
094: }
095:
096: /**
097: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
098: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
099: * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
100: * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})
101: * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
102: */
103: public FairGenericObjectPool(PoolableObjectFactory factory,
104: int maxActive, byte whenExhaustedAction, long maxWait) {
105: this (factory, maxActive, whenExhaustedAction, maxWait,
106: DEFAULT_MAX_IDLE, DEFAULT_MIN_IDLE,
107: DEFAULT_TEST_ON_BORROW, DEFAULT_TEST_ON_RETURN,
108: DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
109: DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
110: DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,
111: DEFAULT_TEST_WHILE_IDLE);
112: }
113:
114: /**
115: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
116: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
117: * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
118: * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})
119: * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
120: * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #getTestOnBorrow})
121: * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #getTestOnReturn})
122: */
123: public FairGenericObjectPool(PoolableObjectFactory factory,
124: int maxActive, byte whenExhaustedAction, long maxWait,
125: boolean testOnBorrow, boolean testOnReturn) {
126: this (factory, maxActive, whenExhaustedAction, maxWait,
127: DEFAULT_MAX_IDLE, DEFAULT_MIN_IDLE, testOnBorrow,
128: testOnReturn,
129: DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
130: DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
131: DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,
132: DEFAULT_TEST_WHILE_IDLE);
133: }
134:
135: /**
136: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
137: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
138: * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
139: * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})
140: * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
141: * @param maxIdle the maximum number of idle objects in my pool (see {@link #getMaxIdle})
142: */
143: public FairGenericObjectPool(PoolableObjectFactory factory,
144: int maxActive, byte whenExhaustedAction, long maxWait,
145: int maxIdle) {
146: this (factory, maxActive, whenExhaustedAction, maxWait, maxIdle,
147: DEFAULT_MIN_IDLE, DEFAULT_TEST_ON_BORROW,
148: DEFAULT_TEST_ON_RETURN,
149: DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
150: DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
151: DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,
152: DEFAULT_TEST_WHILE_IDLE);
153: }
154:
155: /**
156: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
157: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
158: * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
159: * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #getWhenExhaustedAction})
160: * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
161: * @param maxIdle the maximum number of idle objects in my pool (see {@link #getMaxIdle})
162: * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #getTestOnBorrow})
163: * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #getTestOnReturn})
164: */
165: public FairGenericObjectPool(PoolableObjectFactory factory,
166: int maxActive, byte whenExhaustedAction, long maxWait,
167: int maxIdle, boolean testOnBorrow, boolean testOnReturn) {
168: this (factory, maxActive, whenExhaustedAction, maxWait, maxIdle,
169: DEFAULT_MIN_IDLE, testOnBorrow, testOnReturn,
170: DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
171: DEFAULT_NUM_TESTS_PER_EVICTION_RUN,
172: DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS,
173: DEFAULT_TEST_WHILE_IDLE);
174: }
175:
176: /**
177: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
178: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
179: * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
180: * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
181: * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
182: * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
183: * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #setTestOnBorrow})
184: * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #setTestOnReturn})
185: * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
186: * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see {@link #setNumTestsPerEvictionRun})
187: * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see {@link #setMinEvictableIdleTimeMillis})
188: * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see {@link #setTestWhileIdle})
189: */
190: public FairGenericObjectPool(PoolableObjectFactory factory,
191: int maxActive, byte whenExhaustedAction, long maxWait,
192: int maxIdle, boolean testOnBorrow, boolean testOnReturn,
193: long timeBetweenEvictionRunsMillis,
194: int numTestsPerEvictionRun,
195: long minEvictableIdleTimeMillis, boolean testWhileIdle) {
196: this (factory, maxActive, whenExhaustedAction, maxWait, maxIdle,
197: DEFAULT_MIN_IDLE, testOnBorrow, testOnReturn,
198: timeBetweenEvictionRunsMillis, numTestsPerEvictionRun,
199: minEvictableIdleTimeMillis, testWhileIdle);
200: }
201:
202: /**
203: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
204: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
205: * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
206: * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
207: * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
208: * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
209: * @param minIdle the minimum number of idle objects in my pool (see {@link #setMinIdle})
210: * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #setTestOnBorrow})
211: * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #setTestOnReturn})
212: * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
213: * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see {@link #setNumTestsPerEvictionRun})
214: * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see {@link #setMinEvictableIdleTimeMillis})
215: * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see {@link #setTestWhileIdle})
216: */
217: public FairGenericObjectPool(PoolableObjectFactory factory,
218: int maxActive, byte whenExhaustedAction, long maxWait,
219: int maxIdle, int minIdle, boolean testOnBorrow,
220: boolean testOnReturn, long timeBetweenEvictionRunsMillis,
221: int numTestsPerEvictionRun,
222: long minEvictableIdleTimeMillis, boolean testWhileIdle) {
223: this (factory, maxActive, whenExhaustedAction, maxWait, maxIdle,
224: minIdle, testOnBorrow, testOnReturn,
225: timeBetweenEvictionRunsMillis, numTestsPerEvictionRun,
226: minEvictableIdleTimeMillis, testWhileIdle,
227: DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS);
228: }
229:
230: /**
231: * Create a new <tt>FairGenericObjectPool</tt> using the specified values.
232: * @param factory the (possibly <tt>null</tt>)PoolableObjectFactory to use to create, validate and destroy objects
233: * @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
234: * @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
235: * @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted an and <i>whenExhaustedAction</i> is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
236: * @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
237: * @param minIdle the minimum number of idle objects in my pool (see {@link #setMinIdle})
238: * @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject} method (see {@link #setTestOnBorrow})
239: * @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject} method (see {@link #setTestOnReturn})
240: * @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
241: * @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction thread (if any) (see {@link #setNumTestsPerEvictionRun})
242: * @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see {@link #setMinEvictableIdleTimeMillis})
243: * @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any (see {@link #setTestWhileIdle})
244: * @param softMinEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition with the extra condition that at least "minIdle" amount of object remain in the pool. (see {@link #setSoftMinEvictableIdleTimeMillis})
245: */
246: public FairGenericObjectPool(PoolableObjectFactory factory,
247: int maxActive, byte whenExhaustedAction, long maxWait,
248: int maxIdle, int minIdle, boolean testOnBorrow,
249: boolean testOnReturn, long timeBetweenEvictionRunsMillis,
250: int numTestsPerEvictionRun,
251: long minEvictableIdleTimeMillis, boolean testWhileIdle,
252: long softMinEvictableIdleTimeMillis) {
253: super (factory, maxActive, whenExhaustedAction, maxWait,
254: maxIdle, minIdle, testOnBorrow, testOnReturn,
255: timeBetweenEvictionRunsMillis, numTestsPerEvictionRun,
256: minEvictableIdleTimeMillis, testWhileIdle,
257: softMinEvictableIdleTimeMillis);
258: _borrowerQueue = Collections.synchronizedList(new LinkedList());
259: }
260:
261: //-- ObjectPool methods ------------------------------------------
262:
263: /**
264: *
265: * @see org.apache.commons.pool.ObjectPool#borrowObject()
266: */
267: public Object borrowObject() throws Exception {
268: assertOpen();
269: long starttime = System.currentTimeMillis();
270:
271: try {
272: synchronized (this ) {
273: // use borrowerQueue
274: _borrowerQueue.add(Thread.currentThread());
275:
276: for (;;) {
277: ObjectTimestampPair pair = null;
278:
279: // Only allow current thread to receive pool object if
280: // thread is top of queue
281: boolean eligible = _borrowerQueue.get(0) == Thread
282: .currentThread();
283: if (eligible) {
284: // if there are any sleeping, just grab one of those
285: try {
286: pair = (ObjectTimestampPair) (_pool
287: .removeFirst());
288: } catch (NoSuchElementException e) {
289: ; /* ignored */
290: }
291: }
292:
293: // otherwise
294: if (null == pair) {
295: // check if we can create one
296: // (note we know that the num sleeping is 0, else we wouldn't be here)
297: if (eligible
298: && (_maxActive < 0 || _numActive < _maxActive)) {
299: // allow new object to be created
300: } else {
301: // the pool is exhausted
302: // or current thread is ineligible due to fairness
303: switch (_whenExhaustedAction) {
304: case WHEN_EXHAUSTED_GROW:
305: // allow new object to be created
306: break;
307: case WHEN_EXHAUSTED_FAIL:
308: throw new NoSuchElementException(
309: "Pool exhausted");
310: case WHEN_EXHAUSTED_BLOCK:
311: try {
312: if (_maxWait <= 0) {
313: wait();
314: } else {
315: // this code may be executed again after a notify then continue cycle
316: // so, need to calculate the amount of time to wait
317: final long elapsed = (System
318: .currentTimeMillis() - starttime);
319: final long waitTime = _maxWait
320: - elapsed;
321: if (waitTime > 0) {
322: wait(waitTime);
323: }
324: }
325: } catch (InterruptedException e) {
326: // ignored
327: }
328: if (_maxWait > 0
329: && ((System.currentTimeMillis() - starttime) >= _maxWait)) {
330: throw new NoSuchElementException(
331: "Timeout waiting for idle object");
332: } else {
333: continue; // keep looping
334: }
335: default:
336: throw new IllegalArgumentException(
337: "WhenExhaustedAction property "
338: + _whenExhaustedAction
339: + " not recognized.");
340: }
341: }
342: }
343: _numActive++;
344:
345: // create new object when needed
346: boolean newlyCreated = false;
347: if (null == pair) {
348: try {
349: Object obj = _factory.makeObject();
350: pair = new ObjectTimestampPair(obj);
351: newlyCreated = true;
352: return pair.value;
353: } finally {
354: if (!newlyCreated) {
355: // object cannot be created
356: _numActive--;
357: notifyAll();
358: }
359: }
360: }
361:
362: // activate & validate the object
363: try {
364: _factory.activateObject(pair.value);
365: if (_testOnBorrow
366: && !_factory.validateObject(pair.value)) {
367: throw new Exception("ValidateObject failed");
368: }
369: return pair.value;
370: } catch (Throwable e) {
371: // object cannot be activated or is invalid
372: _numActive--;
373: notifyAll();
374: try {
375: _factory.destroyObject(pair.value);
376: } catch (Throwable e2) {
377: // cannot destroy broken object
378: }
379: if (newlyCreated) {
380: throw new NoSuchElementException(
381: "Could not create a validated object, cause: "
382: + e.getMessage());
383: } else {
384: continue; // keep looping
385: }
386: }
387: }
388: }
389: } finally {
390: // remove thread from queue on any method exit
391: _borrowerQueue.remove(Thread.currentThread());
392: }
393: }
394:
395: /** Waiting borrowers (threads in #borrowObject ) */
396: protected List _borrowerQueue;
397: }
|