KeyedObjectPool.
* Optional operations are implemented to either do nothing, return a value
* indicating it is unsupported or throw {@link UnsupportedOperationException}.
*
* @param Invalidates an object from the pool.
* *By contract, obj must have been obtained
* using {@link #borrowObject borrowObject} using a key that is
* equivalent to the one used to borrow the Object in the first place.
This method should be used when an object that has been borrowed * is determined (due to an exception or other problem) to be invalid.
* * @param key the key used to obtain the object * @param obj a {@link #borrowObject borrowed} instance to be returned. * @throws Exception */ public abstract void invalidateObject(K key, V obj) throws Exception; /** * Not supported in this base implementation. * Always throws an {@link UnsupportedOperationException}, * subclasses should override this behavior. * @param key ignored * @throws UnsupportedOperationException */ public void addObject(K key) throws Exception, UnsupportedOperationException { throw new UnsupportedOperationException(); } /** * Not supported in this base implementation. * @return a negative value. * @param key ignored */ public int getNumIdle(K key) throws UnsupportedOperationException { return -1; } /** * Not supported in this base implementation. * @return a negative value. * @param key ignored */ public int getNumActive(K key) throws UnsupportedOperationException { return -1; } /** * Not supported in this base implementation. * @return a negative value. */ public int getNumIdle() throws UnsupportedOperationException { return -1; } /** * Not supported in this base implementation. * @return a negative value. */ public int getNumActive() throws UnsupportedOperationException { return -1; } /** * Not supported in this base implementation. * @throws UnsupportedOperationException */ public void clear() throws Exception, UnsupportedOperationException { throw new UnsupportedOperationException(); } /** * Not supported in this base implementation. * @param key ignored * @throws UnsupportedOperationException */ public void clear(K key) throws Exception, UnsupportedOperationException { throw new UnsupportedOperationException(); } /** * Close this pool. * This affects the behavior ofisClosed and assertOpen.
*/
public void close() throws Exception {
closed = true;
}
/**
* Not supported in this base implementation.
* Always throws an {@link UnsupportedOperationException},
* subclasses should override this behavior.
* @param factory the new KeyedPoolableObjectFactory
* @deprecated to be removed in pool 2.0
*/
@Deprecated
public void setFactory(KeyedPoolableObjectFactorytrue when this pool has been closed.
* @since Pool 1.4
*/
protected final boolean isClosed() {
return closed;
}
/**
* Throws an IllegalStateException when this pool has been closed.
* @throws IllegalStateException when this pool has been closed.
* @see #isClosed()
* @since Pool 1.4
*/
protected final void assertOpen() throws IllegalStateException {
if(isClosed()) {
throw new IllegalStateException("Pool not open");
}
}
/** Whether or not the pool is close */
private volatile boolean closed = false;
}
commons-pool-1.6-src/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java 100644 0 0 6152 11701070263 26717 0 ustar 0 0 /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.pool;
/**
* A base implementation of KeyedPoolableObjectFactory.
* * All operations defined here are essentially no-op's. *
* * @param* The default implementation is a no-op. *
* * @param key the key used when selecting the instance * @param obj the instance to be destroyed */ public void destroyObject(K key, V obj) throws Exception { } /** * Ensures that the instance is safe to be returned by the pool. ** The default implementation always returns true. *
* * @param key the key used when selecting the object * @param obj the instance to be validated * @return alwaystrue in the default implementation
*/
public boolean validateObject(K key, V obj) {
return true;
}
/**
* Reinitialize an instance to be returned by the pool.
* * The default implementation is a no-op. *
* * @param key the key used when selecting the object * @param obj the instance to be activated */ public void activateObject(K key, V obj) throws Exception { } /** * Uninitialize an instance to be returned to the idle object pool. ** The default implementation is a no-op. *
* * @param key the key used when selecting the object * @param obj the instance to be passivated */ public void passivateObject(K key, V obj) throws Exception { } } commons-pool-1.6-src/src/java/org/apache/commons/pool/BaseObjectPool.java 100644 0 0 11556 11701070263 23605 0 ustar 0 0 /* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.pool; /** * A simple base implementation of {@link ObjectPool}. * Optional operations are implemented to either do nothing, return a value * indicating it is unsupported or throw {@link UnsupportedOperationException}. * * @paramInvalidates an object from the pool.
* *By contract, obj must have been obtained
* using {@link #borrowObject borrowObject}.
* *
This method should be used when an object that has been borrowed * is determined (due to an exception or other problem) to be invalid.
* * @param obj a {@link #borrowObject borrowed} instance to be disposed. * @throws Exception */ public abstract void invalidateObject(T obj) throws Exception; /** * Not supported in this base implementation. * @return a negative value. * * @throws UnsupportedOperationException */ public int getNumIdle() throws UnsupportedOperationException { return -1; } /** * Not supported in this base implementation. * @return a negative value. * * @throws UnsupportedOperationException */ public int getNumActive() throws UnsupportedOperationException { return -1; } /** * Not supported in this base implementation. * * @throws UnsupportedOperationException */ public void clear() throws Exception, UnsupportedOperationException { throw new UnsupportedOperationException(); } /** * Not supported in this base implementation. * Always throws an {@link UnsupportedOperationException}, * subclasses should override this behavior. * * @throws UnsupportedOperationException */ public void addObject() throws Exception, UnsupportedOperationException { throw new UnsupportedOperationException(); } /** * Close this pool. * This affects the behavior ofisClosed and assertOpen.
*/
public void close() throws Exception {
closed = true;
}
/**
* Not supported in this base implementation.
* Always throws an {@link UnsupportedOperationException},
* subclasses should override this behavior.
*
* @param factory the PoolableObjectFactory
* @throws UnsupportedOperationException
* @throws IllegalStateException
* @deprecated to be removed in pool 2.0
*/
@Deprecated
public void setFactory(PoolableObjectFactorytrue when this pool has been closed.
*/
public final boolean isClosed() {
return closed;
}
/**
* Throws an IllegalStateException when this pool has been closed.
* @throws IllegalStateException when this pool has been closed.
* @see #isClosed()
*/
protected final void assertOpen() throws IllegalStateException {
if (isClosed()) {
throw new IllegalStateException("Pool not open");
}
}
/** Whether or not the pool is closed */
private volatile boolean closed = false;
}
commons-pool-1.6-src/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java 100644 0 0 4103 11701070263 25727 0 ustar 0 0 /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.pool;
/**
* A base implementation of PoolableObjectFactory.
*
* All operations defined here are essentially no-op's.
*
* @param
* This class has been copied from Commons Collections, version 3.1 in order
* to eliminate the dependency of pool on collections. It has package scope
* to prevent its inclusion in the pool public API. The class declaration below
* should *not* be changed to public.
*
*
* Implements all of the optional {@link List} operations, the
* stack/queue/dequeue operations available in {@link java.util.LinkedList}
* and supports a {@link ListIterator} that allows concurrent modifications
* to the underlying list (see {@link #cursor}).
*
* Note that this implementation is not synchronized.
*
* @param
* Specifically, when elements are added to the list before or
* after the cursor, the cursor simply picks them up automatically.
* When the "current" (i.e., last returned by {@link ListIterator#next}
* or {@link ListIterator#previous}) element of the list is removed,
* the cursor automatically adjusts to the change (invalidating the
* last returned value--i.e., it cannot be removed).
*
* Note that the returned {@link ListIterator} does not support the
* {@link ListIterator#nextIndex} and {@link ListIterator#previousIndex}
* methods (they throw {@link UnsupportedOperationException} when invoked.
*
* Historical Note: In previous versions of this class, the object
* returned from this method was required to be explicitly closed. This
* is no longer necessary.
*
* @see #cursor(int)
* @see #listIterator()
* @see CursorableLinkedList.Cursor
*/
public CursorableLinkedList
* Provides a shared idle object eviction timer for all pools. This class wraps
* the standard {@link Timer} and keeps track of how many pools are using it.
* If no pools are using the timer, it is canceled. This prevents a thread
* being left running which, in application server environments, can lead to
* memory leads and/or prevent applications from shutting down or reloading
* cleanly.
*
* This class has package scope to prevent its inclusion in the pool public API.
* The class declaration below should *not* be changed to public.
*
* When coupled with the appropriate {@link KeyedPoolableObjectFactory},
* A
* Optionally, one may configure the pool to examine and possibly evict objects
* as they sit idle in the pool and to ensure that a minimum number of idle
* objects is maintained for each key. This is performed by an
* "idle object eviction" thread, which runs asynchronously. Caution should be
* used when configuring this optional feature. Eviction runs contend with client
* threads for access to objects in the pool, so if they run too frequently
* performance issues may result. The idle object eviction thread may be
* configured using the following attributes:
*
* The pools can be configured to behave as LIFO queues with respect to idle
* objects - always returning the most recently used object from the pool,
* or as FIFO queues, where borrowObject always returns the oldest object
* in the idle object pool.
*
* GenericKeyedObjectPool is not usable without a {@link KeyedPoolableObjectFactory}. A
* non-
* Implementation note: To prevent possible deadlocks, care has been taken to
* ensure that no call to a factory method will occur within a synchronization
* block. See POOL-125 and DBCP-44 for more information.
*
* When a negative value is supplied,
* Borrows an object from the keyed pool associated with the given key. If there is an idle instance available in the pool associated with the given key, then
* either the most-recently returned (if {@link #getLifo() lifo} == true) or "oldest" (lifo == false)
* instance sitting idle in the pool will be activated and returned. If activation fails, or
* {@link #getTestOnBorrow() testOnBorrow} is set to true and validation fails, the instance is destroyed and the
* next available instance is examined. This continues until either a valid instance is returned or there
* are no more idle instances available. If there are no idle instances available in the pool associated with the given key, behavior
* depends on the {@link #getMaxActive() maxActive}, {@link #getMaxTotal() maxTotal}, and (if applicable)
* {@link #getWhenExhaustedAction() whenExhaustedAction} and {@link #getMaxWait() maxWait} properties. If the
* number of instances checked out from the pool under the given key is less than If the associated keyed pool is exhausted (no available idle instances and no capacity to create new ones),
* this method will either block ({@link #WHEN_EXHAUSTED_BLOCK}), throw a When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances
* to become available. As of pool 1.5, a "fairness" algorithm has been implemented to ensure that threads receive
* available instances in request arrival order. Implementation notes:
* Returns an object to a keyed pool. For the pool to function correctly, the object instance must have been borrowed
* from the pool (under the same key) and not yet returned. Repeated If {@link #getMaxIdle() maxIdle} is set to a positive value and the number of idle instances under the given
* key has reached this value, the returning instance is destroyed. If {@link #getTestOnReturn() testOnReturn} == true, the returning instance is validated before being returned
* to the idle instance pool under the given key. In this case, if validation fails, the instance is destroyed. Adds an object to the keyed pool. Validates the object if testOnReturn == true and passivates it before returning it to the pool.
* if validation or passivation fails, or maxIdle is set and there is no room in the pool, the instance
* is destroyed. Calls {@link #allocate()} on successful completion Activation of this method decrements the active count associated with the given keyed pool
* and attempts to destroy Closes the keyed object pool. Once the pool is closed, {@link #borrowObject(Object)}
* will fail with IllegalStateException, but {@link #returnObject(Object, Object)} and
* {@link #invalidateObject(Object, Object)} will continue to work, with returned objects
* destroyed on return. Destroys idle instances in the pool by invoking {@link #clear()}. Sets the keyed poolable object factory associated with this pool. If this method is called when objects are checked out of any of the keyed pools,
* an IllegalStateException is thrown. Calling this method also has the side effect of
* destroying any idle instances in existing keyed pools, using the original factory. Perform Successive activations of this method examine objects in keyed pools
* in sequence, cycling through the keys and examining objects in
* oldest-to-youngest order within the keyed pools.
* When a negative value is supplied,
* When coupled with the appropriate {@link PoolableObjectFactory},
* GenericObjectPool provides robust pooling functionality for
* arbitrary objects.
*
* A GenericObjectPool provides a number of configurable parameters:
*
* Optionally, one may configure the pool to examine and possibly evict objects
* as they sit idle in the pool and to ensure that a minimum number of idle
* objects are available. This is performed by an "idle object eviction"
* thread, which runs asynchronously. Caution should be used when configuring
* this optional feature. Eviction runs contend with client threads for access
* to objects in the pool, so if they run too frequently performance issues may
* result. The idle object eviction thread may be configured using the following
* attributes:
*
*
* The pool can be configured to behave as a LIFO queue with respect to idle
* objects - always returning the most recently used object from the pool,
* or as a FIFO queue, where borrowObject always returns the oldest object
* in the idle object pool.
*
* GenericObjectPool is not usable without a {@link PoolableObjectFactory}. A
* non-
* Implementation note: To prevent possible deadlocks, care has been taken to
* ensure that no call to a factory method will occur within a synchronization
* block. See POOL-125 and DBCP-44 for more information.
*
* @param
* When a negative value is supplied, ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})
* tests will be run. That is, when the value is -n, roughly one nth of the
* idle objects will be tested per run. When the value is positive, the number of tests
* actually performed in each run will be the minimum of this value and the number of instances
* idle in the pool.
*
* @param numTestsPerEvictionRun max number of objects to examine during each evictor run.
* @see #getNumTestsPerEvictionRun
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) {
_numTestsPerEvictionRun = numTestsPerEvictionRun;
}
/**
* Returns the minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any).
*
* @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
* @see #setMinEvictableIdleTimeMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized long getMinEvictableIdleTimeMillis() {
return _minEvictableIdleTimeMillis;
}
/**
* Sets the minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any).
* When non-positive, no objects will be evicted from the pool
* due to idle time alone.
* @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
* it is eligible for eviction.
* @see #getMinEvictableIdleTimeMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) {
_minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
}
/**
* Returns the minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any), with the extra condition that at least
* "minIdle" amount of object remain in the pool.
*
* @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
* @since Pool 1.3
* @see #setSoftMinEvictableIdleTimeMillis
*/
public synchronized long getSoftMinEvictableIdleTimeMillis() {
return _softMinEvictableIdleTimeMillis;
}
/**
* Sets the minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any), with the extra condition that at least
* "minIdle" object instances remain in the pool.
* When non-positive, no objects will be evicted from the pool
* due to idle time alone.
*
* @param softMinEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
* it is eligible for eviction.
* @since Pool 1.3
* @see #getSoftMinEvictableIdleTimeMillis
*/
public synchronized void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis) {
_softMinEvictableIdleTimeMillis = softMinEvictableIdleTimeMillis;
}
/**
* When true, objects will be
* {@link PoolableObjectFactory#validateObject validated}
* by the idle object evictor (if any). If an object
* fails to validate, it will be dropped from the pool.
*
* @return Borrows an object from the pool. If there is an idle instance available in the pool, then either the most-recently returned
* (if {@link #getLifo() lifo} == true) or "oldest" (lifo == false) instance sitting idle in the pool
* will be activated and returned. If activation fails, or {@link #getTestOnBorrow() testOnBorrow} is set
* to true and validation fails, the instance is destroyed and the next available instance is examined.
* This continues until either a valid instance is returned or there are no more idle instances available. If there are no idle instances available in the pool, behavior depends on the {@link #getMaxActive() maxActive}
* and (if applicable) {@link #getWhenExhaustedAction() whenExhaustedAction} and {@link #getMaxWait() maxWait}
* properties. If the number of instances checked out from the pool is less than If the pool is exhausted (no available idle instances and no capacity to create new ones),
* this method will either block ({@link #WHEN_EXHAUSTED_BLOCK}), throw a When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances
* to become available. As of pool 1.5, a "fairness" algorithm has been implemented to ensure that threads receive
* available instances in request arrival order. Activation of this method decrements the active count and attempts to destroy the instance. Implementation notes:
* Returns an object instance to the pool. If {@link #getMaxIdle() maxIdle} is set to a positive value and the number of idle instances
* has reached this value, the returning instance is destroyed. If {@link #getTestOnReturn() testOnReturn} == true, the returning instance is validated before being returned
* to the idle instance pool. In this case, if validation fails, the instance is destroyed. Note: There is no guard to prevent an object
* being returned to the pool multiple times. Clients are expected to
* discard references to returned objects and ensure that an object is not
* returned to the pool multiple times in sequence (i.e., without being
* borrowed again between returns). Violating this contract will result in
* the same object appearing multiple times in the pool and pool counters
* (numActive, numIdle) returning incorrect values. Adds an object to the pool. Validates the object if testOnReturn == true and passivates it before returning it to the pool.
* if validation or passivation fails, or maxIdle is set and there is no room in the pool, the instance
* is destroyed. Calls {@link #allocate()} on successful completion Closes the pool. Once the pool is closed, {@link #borrowObject()}
* will fail with IllegalStateException, but {@link #returnObject(Object)} and
* {@link #invalidateObject(Object)} will continue to work, with returned objects
* destroyed on return. Destroys idle instances in the pool by invoking {@link #clear()}. Perform Successive activations of this method examine objects in
* in sequence, cycling through objects in oldest-to-youngest order.
* When a negative value is supplied, ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})
* tests will be run. I.e., when the value is -n, roughly one nth of the
* idle objects will be tested per run.
*
* @see #setNumTestsPerEvictionRun
* @see #getNumTestsPerEvictionRun
* @see #getTimeBetweenEvictionRunsMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
private int _numTestsPerEvictionRun = DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
/**
* The minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any).
* When non-positive, no objects will be evicted from the pool
* due to idle time alone.
*
* @see #setMinEvictableIdleTimeMillis
* @see #getMinEvictableIdleTimeMillis
* @see #getTimeBetweenEvictionRunsMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
private long _minEvictableIdleTimeMillis = DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
/**
* The minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any), with the extra condition that at least
* "minIdle" amount of object remain in the pool.
* When non-positive, no objects will be evicted from the pool
* due to idle time alone.
*
* @see #setSoftMinEvictableIdleTimeMillis
* @see #getSoftMinEvictableIdleTimeMillis
*/
private long _softMinEvictableIdleTimeMillis = DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
/** Whether or not the pool behaves as a LIFO queue (last in first out) */
private boolean _lifo = DEFAULT_LIFO;
/** My pool. */
private CursorableLinkedList
Object pooling API implementations.
{@link org.apache.commons.pool.impl.StackObjectPool StackObjectPool}
({@link org.apache.commons.pool.impl.StackKeyedObjectPool StackKeyedObjectPool})
provides a simple, {@link java.util.Stack Stack}-based
implementation of {@link org.apache.commons.pool.ObjectPool ObjectPool}
({@link org.apache.commons.pool.KeyedObjectPool KeyedObjectPool}).
{@link org.apache.commons.pool.impl.StackObjectPoolFactory StackObjectPoolFactory}
({@link org.apache.commons.pool.impl.StackKeyedObjectPoolFactory StackKeyedObjectPoolFactory})
provides an implementation of the
{@link org.apache.commons.pool.ObjectPoolFactory ObjectPoolFactory}
({@link org.apache.commons.pool.KeyedObjectPoolFactory KeyedObjectPoolFactory})
factory interface for this class.
{@link org.apache.commons.pool.impl.GenericObjectPool GenericObjectPool}
({@link org.apache.commons.pool.impl.GenericKeyedObjectPool GenericKeyedObjectPool})
provides a more robust (but also more complicated)
implementation of {@link org.apache.commons.pool.ObjectPool ObjectPool}
({@link org.apache.commons.pool.KeyedObjectPool KeyedObjectPool}).
{@link org.apache.commons.pool.impl.GenericObjectPoolFactory GenericObjectPoolFactory}
({@link org.apache.commons.pool.impl.GenericKeyedObjectPoolFactory GenericKeyedObjectPoolFactory})
provides an implementation of the
{@link org.apache.commons.pool.ObjectPoolFactory ObjectPoolFactory}
({@link org.apache.commons.pool.KeyedObjectPoolFactory KeyedObjectPoolFactory})
factory interface for this class.
See also the {@link org.apache.commons.pool} package.
Borrow an object from the pool. If there are no idle instances available in the pool, the configured
* factory's {@link PoolableObjectFactory#makeObject()} method is invoked to create a new instance. All instances are {@link PoolableObjectFactory#activateObject(Object) activated} and
* {@link PoolableObjectFactory#validateObject(Object) validated} before being returned by this
* method. If validation fails or an exception occurs activating or validating an idle instance,
* the failing instance is {@link PoolableObjectFactory#destroyObject(Object) destroyed} and another
* instance is retrieved from the pool, validated and activated. This process continues until either the
* pool is empty or an instance passes validation. If the pool is empty on activation or
* it does not contain any valid instances, the factory's Returns an instance to the pool after successful validation and passivation. The returning instance
* is destroyed if any of the following are true: Exceptions passivating or destroying instances are silently swallowed. Exceptions validating
* instances are propagated to the client. Create an object, and place it into the pool.
* addObject() is useful for "pre-loading" a pool with idle objects. Before being added to the pool, the newly created instance is
* {@link PoolableObjectFactory#validateObject(Object) validated} and
* {@link PoolableObjectFactory#passivateObject(Object) passivated}. If validation
* fails, the new instance is {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
* Exceptions generated by the factory Close this pool, and free any resources associated with it. Invokes
* {@link #clear()} to destroy and remove instances in the pool. Calling {@link #addObject} or {@link #borrowObject} after invoking
* this method on a pool will cause them to throw an
* {@link IllegalStateException}.
* Given a {@link KeyedPoolableObjectFactory}, this class will maintain
* a simple pool of instances. A finite number of "sleeping"
* or inactive instances is enforced, but when the pool is
* empty, new instances are created to support the new load.
* Hence this class places no limit on the number of "active"
* instances created by the pool, but is quite useful for
* re-using
* Calling {@link #addObject addObject} or {@link #borrowObject borrowObject} after invoking
* this method on a pool will cause them to throw an {@link IllegalStateException}.
*
* Given a {@link PoolableObjectFactory}, this class will maintain
* a simple pool of instances. A finite number of "sleeping"
* or idle instances is enforced, but when the pool is
* empty, new instances are created to support the new load.
* Hence this class places no limit on the number of "active"
* instances created by the pool, but is quite useful for
* re-using Objects without introducing
* artificial limits.
*
* @param Create a new StackObjectPool using the specified Negative values of Borrows an object from the pool. If there are idle instances available on the stack,
* the top element of the stack is popped to activate, validate and return to the client. If there
* are no idle instances available, the {@link PoolableObjectFactory#makeObject() makeObject}
* method of the pool's {@link PoolableObjectFactory} is invoked to create a new instance. All instances are {@link PoolableObjectFactory#activateObject(Object) activated} and
* {@link PoolableObjectFactory#validateObject(Object) validated} before being returned to the
* client. If validation fails or an exception occurs activating or validating an instance
* popped from the idle instance stack, the failing instance is
* {@link PoolableObjectFactory#destroyObject(Object) destroyed} and the next instance on
* the stack is popped, validated and activated. This process continues until either the
* stack is empty or an instance passes validation. If the stack is empty on activation or
* it does not contain any valid instances, the factory's Returns an instance to the pool, pushing it on top of the idle instance stack after successful
* validation and passivation. The returning instance is destroyed if any of the following are true: Exceptions passivating or destroying instances are silently swallowed. Exceptions validating
* instances are propagated to the client. Close this pool, and free any resources associated with it. Invokes
* {@link #clear()} to destroy and remove instances in the pool. Calling {@link #addObject} or {@link #borrowObject} after invoking
* this method on a pool will cause them to throw an
* {@link IllegalStateException}. Create an object, and place it on top of the stack.
* This method is useful for "pre-loading" a pool with idle objects. Before being added to the pool, the newly created instance is
* {@link PoolableObjectFactory#validateObject(Object) validated} and
* {@link PoolableObjectFactory#passivateObject(Object) passivated}. If validation
* fails, the new instance is {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
* Exceptions generated by the factory If a new instance is created and successfully validated and passivated and adding this
* instance to the pool causes {@link #getMaxSleeping() maxSleeping} to be exceeded, the oldest
* (bottom) instance in the pool is destroyed to make room for the newly created instance, which
* is pushed on top of the stack.
*
* @throws Exception when the {@link #getFactory() factory} has a problem creating or passivating an object.
*/
@Override
public synchronized void addObject() throws Exception {
assertOpen();
if (_factory == null) {
throw new IllegalStateException("Cannot add objects without a factory.");
}
T obj = _factory.makeObject();
boolean success = true;
if(!_factory.validateObject(obj)) {
success = false;
} else {
_factory.passivateObject(obj);
}
boolean shouldDestroy = !success;
if (success) {
T toBeDestroyed = null;
if(_pool.size() >= _maxSleeping) {
shouldDestroy = true;
toBeDestroyed = _pool.remove(0); // remove the stalest object
}
_pool.push(obj);
obj = toBeDestroyed; // swap returned obj with the stalest one so it can be destroyed
}
notifyAll(); // _numIdle has changed
if(shouldDestroy) { // by constructor, shouldDestroy is false when _factory is null
try {
_factory.destroyObject(obj);
} catch(Exception e) {
// ignored
}
}
}
/**
* Sets the {@link PoolableObjectFactory factory} this pool uses
* to create new instances. Trying to change
* the
* A keyed pool pools instances of multiple types. Each
* type may be accessed using an arbitrary key.
*
* Example of use:
*
* {@link KeyedObjectPool} implementations may choose to store at most
* one instance per key value, or may choose to maintain a pool of instances
* for each key (essentially creating a {@link java.util.Map Map} of
* {@link ObjectPool pools}).
* See {@link BaseKeyedObjectPool} for a simple base implementation.
* Instances returned from this method will have been either newly created with
* {@link KeyedPoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
* have been activated with {@link KeyedPoolableObjectFactory#activateObject activateObject} and
* then validated with {@link KeyedPoolableObjectFactory#validateObject validateObject}.
*
* By contract, clients must return the borrowed object using
* {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
* as defined in an implementation or sub-interface,
* using a
* The behaviour of this method when the pool has been exhausted
* is not strictly specified (although it may be specified by implementations).
* Older versions of this method would return Invalidates an object from the pool. By contract, This method should be used when an object that has been borrowed
* is determined (due to an exception or other problem) to be invalid.
* Calling {@link #addObject addObject} or {@link #borrowObject borrowObject} after invoking
* this method on a pool will cause them to throw an {@link IllegalStateException}.
*
* By contract, when an {@link KeyedObjectPool}
* delegates to a {@link KeyedPoolableObjectFactory},
*
* {@link KeyedPoolableObjectFactory} must be thread-safe. The only promise
* an {@link KeyedObjectPool} makes is that the same instance of an object will not
* be passed to more than one method of a
* It is important for implementations of this method to be aware
* that there is no guarantee about what state
* Also, an implementation must take in to consideration that
* instances lost to the garbage collector may never be destroyed.
*
*
* Example of use:
* See {@link BaseObjectPool} for a simple base implementation.
* Instances returned from this method will have been either newly created with
* {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
* have been activated with {@link PoolableObjectFactory#activateObject activateObject} and
* then validated with {@link PoolableObjectFactory#validateObject validateObject}.
*
* By contract, clients must return the borrowed instance using
* {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
* as defined in an implementation or sub-interface.
*
* The behaviour of this method when the pool has been exhausted
* is not strictly specified (although it may be specified by implementations).
* Older versions of this method would return Invalidates an object from the pool. By contract, This method should be used when an object that has been borrowed
* is determined (due to an exception or other problem) to be invalid.
* Calling {@link #addObject} or {@link #borrowObject} after invoking
* this method on a pool will cause them to throw an
* {@link IllegalStateException}.
*
Generic Object pooling API with several implementations.
The
The
Here is a simple example of pooling
A class that makes frequent use of a Map could then use a pool
as shown below:
The above example shows how one would use an
{@link org.apache.commons.pool.ObjectPool ObjectPool}. The other supplied
implementations or another special purpose pool would be used similarly.
Object pooling API.
The
The
The
{@link org.apache.commons.pool.ObjectPoolFactory ObjectPoolFactory}
defines a simple factory for
The
* By contract, when an {@link ObjectPool}
* delegates to a {@link PoolableObjectFactory},
*
* {@link PoolableObjectFactory} must be thread-safe. The only promise
* an {@link ObjectPool} makes is that the same instance of an object will not
* be passed to more than one method of a
* It is important for implementations of this method to be aware
* that there is no guarantee about what state
* Also, an implementation must take in to consideration that
* instances lost to the garbage collector may never be destroyed.
* Note:
* This should not be used on pool implementations that already provide proper synchronization
* such as the pools provided in the Commons Pool library. Wrapping a pool that
* {@link #wait() waits} for poolable objects to be returned before allowing another one to be
* borrowed with another layer of synchronization will cause liveliness issues or a deadlock.
* Note:
* This should not be used on pool implementations that already provide proper synchronization
* such as the pools provided in the Commons Pool library. Wrapping a pool that
* {@link #wait() waits} for poolable objects to be returned before allowing another one to be
* borrowed with another layer of synchronization will cause liveliness issues or a deadlock.
*
* The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink
* it's size. Values between 0 and 1 cause the pool to try to shrink it's size more often.
* Values greater than 1 cause the pool to less frequently try to shrink it's size.
*
* The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink
* it's size. Values between 0 and 1 cause the pool to try to shrink it's size more often.
* Values greater than 1 cause the pool to less frequently try to shrink it's size.
*
* The factor parameter provides a mechanism to tweak the rate at which the pool tries to shrink
* it's size. Values between 0 and 1 cause the pool to try to shrink it's size more often.
* Values greater than 1 cause the pool to less frequently try to shrink it's size.
*
* The perKey parameter determines if the pool shrinks on a whole pool basis or a per key basis.
* When perKey is false, the keys do not have an effect on the rate at which the pool tries to
* shrink it's size. When perKey is true, each key is shrunk independently.
* Note:
* This should not be used on pool implementations that already provide proper synchronization
* such as the pools provided in the Commons Pool library. Wrapping a pool that
* {@link #wait() waits} for poolable objects to be returned before allowing another one to be
* borrowed with another layer of synchronization will cause liveliness issues or a deadlock.
* Note:
* This should not be used on pool implementations that already provide proper synchronization
* such as the pools provided in the Commons Pool library. Wrapping a pool that
* {@link #wait() waits} for poolable objects to be returned before allowing another one to be
* borrowed with another layer of synchronization will cause liveliness issues or a deadlock.
* Note:
* This should not be used on pool implementations that already provide proper synchronization
* such as the pools provided in the Commons Pool library.
* hashCode = 1;
* Iterator i = list.iterator();
* while (i.hasNext()) {
* Object obj = i.next();
* hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());
* }
*
* This ensures that list1.equals(list2) implies that
* list1.hashCode()==list2.hashCode() for any two lists,
* list1 and list2, as required by the general
* contract of Object.hashCode.
*
* @return the hash code value for this list.
* @see Object#hashCode()
* @see Object#equals(Object)
* @see #equals(Object)
*/
@Override
public int hashCode() {
int hash = 1;
for(ListableKeyedObjectPool implementation.
* GenericKeyedObjectPool provides robust pooling functionality for
* keyed objects. A GenericKeyedObjectPool can be viewed as a map
* of pools, keyed on the (unique) key values provided to the
* {@link #preparePool preparePool}, {@link #addObject addObject} or
* {@link #borrowObject borrowObject} methods. Each time a new key value is
* provided to one of these methods, a new pool is created under the given key
* to be managed by the containing GenericKeyedObjectPool.
* GenericKeyedObjectPool provides a number of configurable
* parameters:
*
* maxTotal is set to a
* positive value and {@link #borrowObject borrowObject} is invoked
* when at the limit with no idle instances available, an attempt is made to
* create room by clearing the oldest 15% of the elements from the keyed
* pools. The default setting for this parameter is -1 (no limit).
*
*
* The default whenExhaustedAction setting is
* {@link #WHEN_EXHAUSTED_BLOCK}.
* false.
* false.
*
*
* timeBetweenEvictionRunsMillis > 0. The default setting
* for this parameter is 30 minutes.
* timeBetweenEvictionRunsMillis > 0. The default setting
* for this parameter is false.
* timeBetweenEvictionRunsMillis > 0, each time the idle object
* eviction thread runs, it will try to create enough idle instances so that
* there will be minIdle idle instances available under each
* key. This parameter is also used by {@link #preparePool preparePool}
* if true is provided as that method's
* populateImmediately parameter. The default setting for this
* parameter is 0.
*
*
* true.
* null factory must be provided either as a constructor argument
* or via a call to {@link #setFactory setFactory} before the pool is used.
* GenericKeyedObjectPool with no factory.
*
* @see #GenericKeyedObjectPool(KeyedPoolableObjectFactory)
* @see #setFactory(KeyedPoolableObjectFactory)
*/
public GenericKeyedObjectPool() {
this(null, DEFAULT_MAX_ACTIVE, DEFAULT_WHEN_EXHAUSTED_ACTION, DEFAULT_MAX_WAIT, DEFAULT_MAX_IDLE,
DEFAULT_TEST_ON_BORROW, DEFAULT_TEST_ON_RETURN, DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS,
DEFAULT_NUM_TESTS_PER_EVICTION_RUN, DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS, DEFAULT_TEST_WHILE_IDLE);
}
/**
* Create a new GenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy
* objects if not null
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param config a non-null {@link GenericKeyedObjectPool.Config} describing the configuration
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
* @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
* @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
* whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed from me at one time (see {@link #setMaxActive})
* @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
* whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
* @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
* @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
* method (see {@link #setTestOnBorrow})
* @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
* method (see {@link #setTestOnReturn})
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed from me at one time
* (see {@link #setMaxActive})
* @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
* @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
* whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
* @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed from me at one time
* (see {@link #setMaxActive})
* @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
* @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
* whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #getMaxWait})
* @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
* @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
* method (see {@link #setTestOnBorrow})
* @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
* method (see {@link #setTestOnReturn})
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed from me at one time
* (see {@link #setMaxActive})
* @param whenExhaustedAction the action to take when the pool is exhausted
* (see {@link #setWhenExhaustedAction})
* @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
* whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
* @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
* @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
* method (see {@link #setTestOnBorrow})
* @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
* method (see {@link #setTestOnReturn})
* @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle
* objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
* @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction
* thread (if any) (see {@link #setNumTestsPerEvictionRun})
* @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before
* it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis})
* @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any
* (see {@link #setTestWhileIdle})
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed from me at one time
* (see {@link #setMaxActive})
* @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
* @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
* whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
* @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
* @param maxTotal the maximum number of objects that can exists at one time (see {@link #setMaxTotal})
* @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
* method (see {@link #setTestOnBorrow})
* @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
* method (see {@link #setTestOnReturn})
* @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle
* objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
* @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction
* thread (if any) (see {@link #setNumTestsPerEvictionRun})
* @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool
* before it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis})
* @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any
* (see {@link #setTestWhileIdle})
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed at one time (see {@link #setMaxActive})
* @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
* @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
* whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
* @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
* @param maxTotal the maximum number of objects that can exists at one time (see {@link #setMaxTotal})
* @param minIdle the minimum number of idle objects to have in the pool at any one time (see {@link #setMinIdle})
* @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
* method (see {@link #setTestOnBorrow})
* @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
* method (see {@link #setTestOnReturn})
* @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle
* objects
* for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
* @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction
* thread (if any) (see {@link #setNumTestsPerEvictionRun})
* @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before
* it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis})
* @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any
* (see {@link #setTestWhileIdle})
* @since Pool 1.3
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactoryGenericKeyedObjectPool using the specified values.
* @param factory the KeyedPoolableObjectFactory to use to create, validate, and destroy objects
* if not null
* @param maxActive the maximum number of objects that can be borrowed at one time
* (see {@link #setMaxActive})
* @param whenExhaustedAction the action to take when the pool is exhausted (see {@link #setWhenExhaustedAction})
* @param maxWait the maximum amount of time to wait for an idle object when the pool is exhausted and
* whenExhaustedAction is {@link #WHEN_EXHAUSTED_BLOCK} (otherwise ignored) (see {@link #setMaxWait})
* @param maxIdle the maximum number of idle objects in my pool (see {@link #setMaxIdle})
* @param maxTotal the maximum number of objects that can exists at one time (see {@link #setMaxTotal})
* @param minIdle the minimum number of idle objects to have in the pool at any one time (see {@link #setMinIdle})
* @param testOnBorrow whether or not to validate objects before they are returned by the {@link #borrowObject}
* method (see {@link #setTestOnBorrow})
* @param testOnReturn whether or not to validate objects after they are returned to the {@link #returnObject}
* method (see {@link #setTestOnReturn})
* @param timeBetweenEvictionRunsMillis the amount of time (in milliseconds) to sleep between examining idle
* objects for eviction (see {@link #setTimeBetweenEvictionRunsMillis})
* @param numTestsPerEvictionRun the number of idle objects to examine per run within the idle object eviction
* thread (if any) (see {@link #setNumTestsPerEvictionRun})
* @param minEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before
* it is eligible for eviction (see {@link #setMinEvictableIdleTimeMillis})
* @param testWhileIdle whether or not to validate objects in the idle object eviction thread, if any
* (see {@link #setTestWhileIdle})
* @param lifo whether or not the pools behave as LIFO (last in first out) queues (see {@link #setLifo})
* @since Pool 1.4
*/
public GenericKeyedObjectPool(KeyedPoolableObjectFactorymaxTotal is set to a
* positive value and {@link #borrowObject borrowObject} is invoked
* when at the limit with no idle instances available, an attempt is made to
* create room by clearing the oldest 15% of the elements from the keyed
* pools.
*
* @param maxTotal The cap on the total number of instances across pools.
* Use a negative value for no limit.
* @see #getMaxTotal
*/
public void setMaxTotal(int maxTotal) {
synchronized(this) {
_maxTotal = maxTotal;
}
allocate();
}
/**
* Returns the action to take when the {@link #borrowObject} method
* is invoked when the pool is exhausted (the maximum number
* of "active" objects has been reached).
*
* @return one of {@link #WHEN_EXHAUSTED_BLOCK},
* {@link #WHEN_EXHAUSTED_FAIL} or {@link #WHEN_EXHAUSTED_GROW}
* @see #setWhenExhaustedAction
*/
public synchronized byte getWhenExhaustedAction() {
return _whenExhaustedAction;
}
/**
* Sets the action to take when the {@link #borrowObject} method
* is invoked when the pool is exhausted (the maximum number
* of "active" objects has been reached).
*
* @param whenExhaustedAction the action code, which must be one of
* {@link #WHEN_EXHAUSTED_BLOCK}, {@link #WHEN_EXHAUSTED_FAIL},
* or {@link #WHEN_EXHAUSTED_GROW}
* @see #getWhenExhaustedAction
*/
public void setWhenExhaustedAction(byte whenExhaustedAction) {
synchronized(this) {
switch(whenExhaustedAction) {
case WHEN_EXHAUSTED_BLOCK:
case WHEN_EXHAUSTED_FAIL:
case WHEN_EXHAUSTED_GROW:
_whenExhaustedAction = whenExhaustedAction;
break;
default:
throw new IllegalArgumentException("whenExhaustedAction " + whenExhaustedAction + " not recognized.");
}
}
allocate();
}
/**
* Returns the maximum amount of time (in milliseconds) the
* {@link #borrowObject} method should block before throwing
* an exception when the pool is exhausted and the
* {@link #setWhenExhaustedAction "when exhausted" action} is
* {@link #WHEN_EXHAUSTED_BLOCK}.
*
* When less than or equal to 0, the {@link #borrowObject} method
* may block indefinitely.
*
* @return the maximum number of milliseconds borrowObject will block.
* @see #setMaxWait
* @see #setWhenExhaustedAction
* @see #WHEN_EXHAUSTED_BLOCK
*/
public synchronized long getMaxWait() {
return _maxWait;
}
/**
* Sets the maximum amount of time (in milliseconds) the
* {@link #borrowObject} method should block before throwing
* an exception when the pool is exhausted and the
* {@link #setWhenExhaustedAction "when exhausted" action} is
* {@link #WHEN_EXHAUSTED_BLOCK}.
*
* When less than or equal to 0, the {@link #borrowObject} method
* may block indefinitely.
*
* @param maxWait the maximum number of milliseconds borrowObject will block or negative for indefinitely.
* @see #getMaxWait
* @see #setWhenExhaustedAction
* @see #WHEN_EXHAUSTED_BLOCK
*/
public void setMaxWait(long maxWait) {
synchronized(this) {
_maxWait = maxWait;
}
allocate();
}
/**
* Returns the cap on the number of "idle" instances per key.
* @return the maximum number of "idle" instances that can be held
* in a given keyed pool.
* @see #setMaxIdle
*/
public synchronized int getMaxIdle() {
return _maxIdle;
}
/**
* Sets the cap on the number of "idle" instances in the pool.
* If maxIdle is set too low on heavily loaded systems it is possible you
* will see objects being destroyed and almost immediately new objects
* being created. This is a result of the active threads momentarily
* returning objects faster than they are requesting them them, causing the
* number of idle objects to rise above maxIdle. The best value for maxIdle
* for heavily loaded system will vary but the default is a good starting
* point.
* @param maxIdle the maximum number of "idle" instances that can be held
* in a given keyed pool. Use a negative value for no limit.
* @see #getMaxIdle
* @see #DEFAULT_MAX_IDLE
*/
public void setMaxIdle(int maxIdle) {
synchronized(this) {
_maxIdle = maxIdle;
}
allocate();
}
/**
* Sets the minimum number of idle objects to maintain in each of the keyed
* pools. This setting has no effect unless
* timeBetweenEvictionRunsMillis > 0 and attempts to ensure
* that each pool has the required minimum number of instances are only
* made during idle object eviction runs.
* @param poolSize - The minimum size of the each keyed pool
* @since Pool 1.3
* @see #getMinIdle
* @see #setTimeBetweenEvictionRunsMillis
*/
public void setMinIdle(int poolSize) {
_minIdle = poolSize;
}
/**
* Returns the minimum number of idle objects to maintain in each of the keyed
* pools. This setting has no effect unless
* timeBetweenEvictionRunsMillis > 0 and attempts to ensure
* that each pool has the required minimum number of instances are only
* made during idle object eviction runs.
* @return minimum size of the each keyed pool
* @since Pool 1.3
* @see #setTimeBetweenEvictionRunsMillis
*/
public int getMinIdle() {
return _minIdle;
}
/**
* When true, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* before being returned by the {@link #borrowObject}
* method. If the object fails to validate,
* it will be dropped from the pool, and we will attempt
* to borrow another.
*
* @return true if objects are validated before being borrowed.
* @see #setTestOnBorrow
*/
public boolean getTestOnBorrow() {
return _testOnBorrow;
}
/**
* When true, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* before being returned by the {@link #borrowObject}
* method. If the object fails to validate,
* it will be dropped from the pool, and we will attempt
* to borrow another.
*
* @param testOnBorrow whether object should be validated before being returned by borrowObject.
* @see #getTestOnBorrow
*/
public void setTestOnBorrow(boolean testOnBorrow) {
_testOnBorrow = testOnBorrow;
}
/**
* When true, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* before being returned to the pool within the
* {@link #returnObject}.
*
* @return true when objects will be validated before being returned.
* @see #setTestOnReturn
*/
public boolean getTestOnReturn() {
return _testOnReturn;
}
/**
* When true, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* before being returned to the pool within the
* {@link #returnObject}.
*
* @param testOnReturn true so objects will be validated before being returned.
* @see #getTestOnReturn
*/
public void setTestOnReturn(boolean testOnReturn) {
_testOnReturn = testOnReturn;
}
/**
* Returns the number of milliseconds to sleep between runs of the
* idle object evictor thread.
* When non-positive, no idle object evictor thread will be
* run.
*
* @return milliseconds to sleep between evictor runs.
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized long getTimeBetweenEvictionRunsMillis() {
return _timeBetweenEvictionRunsMillis;
}
/**
* Sets the number of milliseconds to sleep between runs of the
* idle object evictor thread.
* When non-positive, no idle object evictor thread will be
* run.
*
* @param timeBetweenEvictionRunsMillis milliseconds to sleep between evictor runs.
* @see #getTimeBetweenEvictionRunsMillis
*/
public synchronized void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) {
_timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
startEvictor(_timeBetweenEvictionRunsMillis);
}
/**
* Returns the max number of objects to examine during each run of the
* idle object evictor thread (if any).
*
* @return number of objects to examine each eviction run.
* @see #setNumTestsPerEvictionRun
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized int getNumTestsPerEvictionRun() {
return _numTestsPerEvictionRun;
}
/**
* Sets the max number of objects to examine during each run of the
* idle object evictor thread (if any).
* ceil({@link #getNumIdle()})/abs({@link #getNumTestsPerEvictionRun})
* tests will be run. I.e., when the value is -n, roughly one nth of the
* idle objects will be tested per run. When the value is positive, the number of tests
* actually performed in each run will be the minimum of this value and the number of instances
* idle in the pools.
*
* @param numTestsPerEvictionRun number of objects to examine each eviction run.
* @see #setNumTestsPerEvictionRun
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) {
_numTestsPerEvictionRun = numTestsPerEvictionRun;
}
/**
* Returns the minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any).
*
* @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
* @see #setMinEvictableIdleTimeMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized long getMinEvictableIdleTimeMillis() {
return _minEvictableIdleTimeMillis;
}
/**
* Sets the minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any).
* When non-positive, no objects will be evicted from the pool
* due to idle time alone.
*
* @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
* it is eligible for eviction.
* @see #getMinEvictableIdleTimeMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) {
_minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
}
/**
* When true, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* by the idle object evictor (if any). If an object
* fails to validate, it will be dropped from the pool.
*
* @return true when objects are validated when borrowed.
* @see #setTestWhileIdle
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized boolean getTestWhileIdle() {
return _testWhileIdle;
}
/**
* When true, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* by the idle object evictor (if any). If an object
* fails to validate, it will be dropped from the pool.
*
* @param testWhileIdle true so objects are validated when borrowed.
* @see #getTestWhileIdle
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized void setTestWhileIdle(boolean testWhileIdle) {
_testWhileIdle = testWhileIdle;
}
/**
* Sets the configuration.
* @param conf the new configuration to use.
* @see GenericKeyedObjectPool.Config
*/
public synchronized void setConfig(GenericKeyedObjectPool.Config conf) {
setMaxIdle(conf.maxIdle);
setMaxActive(conf.maxActive);
setMaxTotal(conf.maxTotal);
setMinIdle(conf.minIdle);
setMaxWait(conf.maxWait);
setWhenExhaustedAction(conf.whenExhaustedAction);
setTestOnBorrow(conf.testOnBorrow);
setTestOnReturn(conf.testOnReturn);
setTestWhileIdle(conf.testWhileIdle);
setNumTestsPerEvictionRun(conf.numTestsPerEvictionRun);
setMinEvictableIdleTimeMillis(conf.minEvictableIdleTimeMillis);
setTimeBetweenEvictionRunsMillis(conf.timeBetweenEvictionRunsMillis);
}
/**
* Whether or not the idle object pools act as LIFO queues. True means
* that borrowObject returns the most recently used ("last in") idle object
* in a pool (if there are idle instances available). False means that
* the pools behave as FIFO queues - objects are taken from idle object
* pools in the order that they are returned.
*
* @return true if the pools are configured to act as LIFO queues
* @since 1.4
*/
public synchronized boolean getLifo() {
return _lifo;
}
/**
* Sets the LIFO property of the pools. True means that borrowObject returns
* the most recently used ("last in") idle object in a pool (if there are
* idle instances available). False means that the pools behave as FIFO
* queues - objects are taken from idle object pools in the order that
* they are returned.
*
* @param lifo the new value for the lifo property
* @since 1.4
*/
public synchronized void setLifo(boolean lifo) {
this._lifo = lifo;
}
//-- ObjectPool methods ------------------------------------------
/**
* maxActive and
* the total number of instances in circulation (under all keys) is less than maxTotal, a new instance
* is created, activated and (if applicable) validated and returned to the caller.NoSuchElementException
* ({@link #WHEN_EXHAUSTED_FAIL}), or grow ({@link #WHEN_EXHAUSTED_GROW} - ignoring maxActive, maxTotal properties).
* The length of time that this method will block when whenExhaustedAction == WHEN_EXHAUSTED_BLOCK
* is determined by the {@link #getMaxWait() maxWait} property.key.
*
* @param key the key to clear
*/
@Override
public void clear(K key) {
Mapkey.
*
* @param key the key to query
* @return the number of instances corresponding to the given key currently borrowed in this pool
*/
@Override
public synchronized int getNumActive(Object key) {
final ObjectQueue pool = (_poolMap.get(key));
return pool != null ? pool.activeCount : 0;
}
/**
* Returns the number of instances corresponding to the given key currently idle in this pool.
*
* @param key the key to query
* @return the number of instances corresponding to the given key currently idle in this pool
*/
@Override
public synchronized int getNumIdle(Object key) {
final ObjectQueue pool = (_poolMap.get(key));
return pool != null ? pool.queue.size() : 0;
}
/**
* returnObject calls on
* the same object/key pair (with no borrowObject calls in between) will result in multiple
* references to the object in the idle instance pool.obj.addObject is useful for "pre-loading" a pool with idle objects.
*
* @param key the key a new instance should be added to
* @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails.
* @throws IllegalStateException when no {@link #setFactory factory} has been set or after {@link #close} has been
* called on this pool.
*/
@Override
public void addObject(K key) throws Exception {
assertOpen();
if (_factory == null) {
throw new IllegalStateException("Cannot add objects without a factory.");
}
V obj = _factory.makeObject(key);
try {
assertOpen();
addObjectToPool(key, obj, false);
} catch (IllegalStateException ex) { // Pool closed
try {
_factory.destroyObject(key, obj);
} catch (Exception ex2) {
// swallow
}
throw ex;
}
}
/**
* Registers a key for pool control.
*
* If populateImmediately is true and
* minIdle > 0, the pool under the given key will be
* populated immediately with minIdle idle instances.
*
* @param key - The key to register for pool control.
* @param populateImmediately - If this is true, the pool
* will be populated immediately.
* @since Pool 1.3
*/
public synchronized void preparePool(K key, boolean populateImmediately) {
ObjectQueue pool = (_poolMap.get(key));
if (null == pool) {
pool = new ObjectQueue();
_poolMap.put(key,pool);
_poolList.add(key);
}
if (populateImmediately) {
try {
// Create the pooled objects
ensureMinIdle(key);
}
catch (Exception e) {
//Do nothing
}
}
}
/**
* numTests idle object eviction tests, evicting
* examined objects that meet the criteria for eviction. If
* testWhileIdle is true, examined objects are validated
* when visited (and removed if invalid); otherwise only objects that
* have been idle for more than minEvicableIdletimeMillis
* are removed.delay is non-positive, stop it
* if it is already running.
*
* @param delay milliseconds between evictor runs.
*/
protected synchronized void startEvictor(long delay) {
if (null != _evictor) {
EvictionTimer.cancel(_evictor);
_evictor = null;
}
if (delay > 0) {
_evictor = new Evictor();
EvictionTimer.schedule(_evictor, delay, delay);
}
}
/**
* Returns pool info including {@link #getNumActive()}, {@link #getNumIdle()}
* and currently defined keys.
*
* @return string containing debug information
*/
synchronized String debugInfo() {
StringBuffer buf = new StringBuffer();
buf.append("Active: ").append(getNumActive()).append("\n");
buf.append("Idle: ").append(getNumIdle()).append("\n");
Iterator_numTestsPerEvictionRun
* and _totalIdle.
*
* @see #setNumTestsPerEvictionRun
* @return the number of tests for the Evictor to run
*/
private synchronized int getNumTests() {
if (_numTestsPerEvictionRun >= 0) {
return Math.min(_numTestsPerEvictionRun, _totalIdle);
} else {
return(int)(Math.ceil(_totalIdle/Math.abs((double)_numTestsPerEvictionRun)));
}
}
/**
* This returns the number of objects to create during the pool
* sustain cycle. This will ensure that the minimum number of idle
* instances is maintained without going past the maxActive value.
*
* @param pool the ObjectPool to calculate the deficit for
* @param incrementInternal - Should the count of objects currently under
* some form of internal processing be
* incremented?
* @return The number of objects to be created
*/
private synchronized int calculateDeficit(ObjectQueue pool,
boolean incrementInternal) {
int objectDefecit = 0;
//Calculate no of objects needed to be created, in order to have
//the number of pooled objects < maxActive();
objectDefecit = getMinIdle() - pool.queue.size();
if (getMaxActive() > 0) {
int growLimit = Math.max(0, getMaxActive() - pool.activeCount - pool.queue.size() - pool.internalProcessingCount);
objectDefecit = Math.min(objectDefecit, growLimit);
}
// Take the maxTotal limit into account
if (getMaxTotal() > 0) {
int growLimit = Math.max(0, getMaxTotal() - getNumActive() - getNumIdle() - _totalInternalProcessing);
objectDefecit = Math.min(objectDefecit, growLimit);
}
if (incrementInternal && objectDefecit > 0) {
pool.incrementInternalProcessingCount();
}
return objectDefecit;
}
//--- inner classes ----------------------------------------------
/**
* A "struct" that keeps additional information about the actual queue of pooled objects.
*/
private class ObjectQueue {
/** Number of instances checked out to clients from this queue */
private int activeCount = 0;
/** Idle instance queue */
private final CursorableLinkedListGenericKeyedObjectPool.
* @see GenericKeyedObjectPool#GenericKeyedObjectPool(KeyedPoolableObjectFactory,GenericKeyedObjectPool.Config)
* @see GenericKeyedObjectPool#setConfig
*/
public static class Config {
//CHECKSTYLE: stop VisibilityModifier
/**
* @see GenericKeyedObjectPool#setMaxIdle
*/
public int maxIdle = GenericKeyedObjectPool.DEFAULT_MAX_IDLE;
/**
* @see GenericKeyedObjectPool#setMaxActive
*/
public int maxActive = GenericKeyedObjectPool.DEFAULT_MAX_ACTIVE;
/**
* @see GenericKeyedObjectPool#setMaxTotal
*/
public int maxTotal = GenericKeyedObjectPool.DEFAULT_MAX_TOTAL;
/**
* @see GenericKeyedObjectPool#setMinIdle
*/
public int minIdle = GenericKeyedObjectPool.DEFAULT_MIN_IDLE;
/**
* @see GenericKeyedObjectPool#setMaxWait
*/
public long maxWait = GenericKeyedObjectPool.DEFAULT_MAX_WAIT;
/**
* @see GenericKeyedObjectPool#setWhenExhaustedAction
*/
public byte whenExhaustedAction = GenericKeyedObjectPool.DEFAULT_WHEN_EXHAUSTED_ACTION;
/**
* @see GenericKeyedObjectPool#setTestOnBorrow
*/
public boolean testOnBorrow = GenericKeyedObjectPool.DEFAULT_TEST_ON_BORROW;
/**
* @see GenericKeyedObjectPool#setTestOnReturn
*/
public boolean testOnReturn = GenericKeyedObjectPool.DEFAULT_TEST_ON_RETURN;
/**
* @see GenericKeyedObjectPool#setTestWhileIdle
*/
public boolean testWhileIdle = GenericKeyedObjectPool.DEFAULT_TEST_WHILE_IDLE;
/**
* @see GenericKeyedObjectPool#setTimeBetweenEvictionRunsMillis
*/
public long timeBetweenEvictionRunsMillis = GenericKeyedObjectPool.DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS;
/**
* @see GenericKeyedObjectPool#setNumTestsPerEvictionRun
*/
public int numTestsPerEvictionRun = GenericKeyedObjectPool.DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
/**
* @see GenericKeyedObjectPool#setMinEvictableIdleTimeMillis
*/
public long minEvictableIdleTimeMillis = GenericKeyedObjectPool.DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
/**
* @see GenericKeyedObjectPool#setLifo
*/
public boolean lifo = GenericKeyedObjectPool.DEFAULT_LIFO;
//CHECKSTYLE: resume VisibilityModifier
}
/**
* Latch used to control allocation order of objects to threads to ensure
* fairness. That is, for each key, objects are allocated to threads in the order
* that threads request objects.
*
* @since 1.5
*/
private final class Latchtrue, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* before being returned by the {@link #borrowObject}
* method. If the object fails to validate,
* it will be dropped from the pool, and we will attempt
* to borrow another.
*
* @see #setTestOnBorrow
* @see #getTestOnBorrow
*/
private volatile boolean _testOnBorrow = DEFAULT_TEST_ON_BORROW;
/**
* When true, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* before being returned to the pool within the
* {@link #returnObject}.
*
* @see #getTestOnReturn
* @see #setTestOnReturn
*/
private volatile boolean _testOnReturn = DEFAULT_TEST_ON_RETURN;
/**
* When true, objects will be
* {@link org.apache.commons.pool.PoolableObjectFactory#validateObject validated}
* by the idle object evictor (if any). If an object
* fails to validate, it will be dropped from the pool.
*
* @see #setTestWhileIdle
* @see #getTestWhileIdle
* @see #getTimeBetweenEvictionRunsMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
private boolean _testWhileIdle = DEFAULT_TEST_WHILE_IDLE;
/**
* The number of milliseconds to sleep between runs of the
* idle object evictor thread.
* When non-positive, no idle object evictor thread will be
* run.
*
* @see #setTimeBetweenEvictionRunsMillis
* @see #getTimeBetweenEvictionRunsMillis
*/
private long _timeBetweenEvictionRunsMillis = DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS;
/**
* The number of objects to examine during each run of the
* idle object evictor thread (if any).
* ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})
* tests will be run. I.e., when the value is -n, roughly one nth of the
* idle objects will be tested per run.
*
* @see #setNumTestsPerEvictionRun
* @see #getNumTestsPerEvictionRun
* @see #getTimeBetweenEvictionRunsMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
private int _numTestsPerEvictionRun = DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
/**
* The minimum amount of time an object may sit idle in the pool
* before it is eligible for eviction by the idle object evictor
* (if any).
* When non-positive, no objects will be evicted from the pool
* due to idle time alone.
*
* @see #setMinEvictableIdleTimeMillis
* @see #getMinEvictableIdleTimeMillis
* @see #getTimeBetweenEvictionRunsMillis
* @see #setTimeBetweenEvictionRunsMillis
*/
private long _minEvictableIdleTimeMillis = DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
/** My hash of pools (ObjectQueue). */
private Mapnull.
*/
public GenericKeyedObjectPoolFactory(KeyedPoolableObjectFactory
*
*
*
* The default whenExhaustedAction setting is
* {@link #WHEN_EXHAUSTED_BLOCK} and the default maxWait
* setting is -1. By default, therefore, borrowObject will
* block indefinitely until an idle instance becomes available.
* false.
* false.
*
*
* timeBetweenEvictionRunsMillis > 0. The default
* setting for this parameter is 30 minutes.
* timeBetweenEvictionRunsMillis > 0. The default setting for
* this parameter is false.
* timeBetweenEvictionRunsMillis > 0. and it is superceded by
* {@link #setMinEvictableIdleTimeMillis minEvictableIdleTimeMillis}
* (that is, if minEvictableIdleTimeMillis is positive, then
* softMinEvictableIdleTimeMillis is ignored). The default setting for
* this parameter is -1 (disabled).
* timeBetweenEvictionRunsMillis > 0. The default setting for
* this parameter is 3.
*
*
* true.
* null factory must be provided either as a constructor argument
* or via a call to {@link #setFactory} before the pool is used.
* numActive + numIdle >= maxActive.
* This setting has no effect if the idle object evictor is disabled
* (i.e. if timeBetweenEvictionRunsMillis <= 0).
*
* @param minIdle The minimum number of objects.
* @see #getMinIdle
* @see #getTimeBetweenEvictionRunsMillis()
*/
public void setMinIdle(int minIdle) {
synchronized(this) {
_minIdle = minIdle;
}
allocate();
}
/**
* Returns the minimum number of objects allowed in the pool
* before the evictor thread (if active) spawns new objects.
* (Note no objects are created when: numActive + numIdle >= maxActive)
*
* @return The minimum number of objects.
* @see #setMinIdle
*/
public synchronized int getMinIdle() {
return _minIdle;
}
/**
* When true, objects will be
* {@link PoolableObjectFactory#validateObject validated}
* before being returned by the {@link #borrowObject}
* method. If the object fails to validate,
* it will be dropped from the pool, and we will attempt
* to borrow another.
*
* @return true if objects are validated before being borrowed.
* @see #setTestOnBorrow
*/
public boolean getTestOnBorrow() {
return _testOnBorrow;
}
/**
* When true, objects will be
* {@link PoolableObjectFactory#validateObject validated}
* before being returned by the {@link #borrowObject}
* method. If the object fails to validate,
* it will be dropped from the pool, and we will attempt
* to borrow another.
*
* @param testOnBorrow true if objects should be validated before being borrowed.
* @see #getTestOnBorrow
*/
public void setTestOnBorrow(boolean testOnBorrow) {
_testOnBorrow = testOnBorrow;
}
/**
* When true, objects will be
* {@link PoolableObjectFactory#validateObject validated}
* before being returned to the pool within the
* {@link #returnObject}.
*
* @return true when objects will be validated after returned to {@link #returnObject}.
* @see #setTestOnReturn
*/
public boolean getTestOnReturn() {
return _testOnReturn;
}
/**
* When true, objects will be
* {@link PoolableObjectFactory#validateObject validated}
* before being returned to the pool within the
* {@link #returnObject}.
*
* @param testOnReturn true so objects will be validated after returned to {@link #returnObject}.
* @see #getTestOnReturn
*/
public void setTestOnReturn(boolean testOnReturn) {
_testOnReturn = testOnReturn;
}
/**
* Returns the number of milliseconds to sleep between runs of the
* idle object evictor thread.
* When non-positive, no idle object evictor thread will be
* run.
*
* @return number of milliseconds to sleep between evictor runs.
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized long getTimeBetweenEvictionRunsMillis() {
return _timeBetweenEvictionRunsMillis;
}
/**
* Sets the number of milliseconds to sleep between runs of the
* idle object evictor thread.
* When non-positive, no idle object evictor thread will be
* run.
*
* @param timeBetweenEvictionRunsMillis number of milliseconds to sleep between evictor runs.
* @see #getTimeBetweenEvictionRunsMillis
*/
public synchronized void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) {
_timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
startEvictor(_timeBetweenEvictionRunsMillis);
}
/**
* Returns the max number of objects to examine during each run of the
* idle object evictor thread (if any).
*
* @return max number of objects to examine during each evictor run.
* @see #setNumTestsPerEvictionRun
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized int getNumTestsPerEvictionRun() {
return _numTestsPerEvictionRun;
}
/**
* Sets the max number of objects to examine during each run of the
* idle object evictor thread (if any).
* true when objects will be validated by the evictor.
* @see #setTestWhileIdle
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized boolean getTestWhileIdle() {
return _testWhileIdle;
}
/**
* When true, objects will be
* {@link PoolableObjectFactory#validateObject validated}
* by the idle object evictor (if any). If an object
* fails to validate, it will be dropped from the pool.
*
* @param testWhileIdle true so objects will be validated by the evictor.
* @see #getTestWhileIdle
* @see #setTimeBetweenEvictionRunsMillis
*/
public synchronized void setTestWhileIdle(boolean testWhileIdle) {
_testWhileIdle = testWhileIdle;
}
/**
* Whether or not the idle object pool acts as a LIFO queue. True means
* that borrowObject returns the most recently used ("last in") idle object
* in the pool (if there are idle instances available). False means that
* the pool behaves as a FIFO queue - objects are taken from the idle object
* pool in the order that they are returned to the pool.
*
* @return true if the pool is configured to act as a LIFO queue
* @since 1.4
*/
public synchronized boolean getLifo() {
return _lifo;
}
/**
* Sets the LIFO property of the pool. True means that borrowObject returns
* the most recently used ("last in") idle object in the pool (if there are
* idle instances available). False means that the pool behaves as a FIFO
* queue - objects are taken from the idle object pool in the order that
* they are returned to the pool.
*
* @param lifo the new value for the LIFO property
* @since 1.4
*/
public synchronized void setLifo(boolean lifo) {
this._lifo = lifo;
}
/**
* Sets my configuration.
*
* @param conf configuration to use.
* @see GenericObjectPool.Config
*/
public void setConfig(GenericObjectPool.Config conf) {
synchronized (this) {
setMaxIdle(conf.maxIdle);
setMinIdle(conf.minIdle);
setMaxActive(conf.maxActive);
setMaxWait(conf.maxWait);
setWhenExhaustedAction(conf.whenExhaustedAction);
setTestOnBorrow(conf.testOnBorrow);
setTestOnReturn(conf.testOnReturn);
setTestWhileIdle(conf.testWhileIdle);
setNumTestsPerEvictionRun(conf.numTestsPerEvictionRun);
setMinEvictableIdleTimeMillis(conf.minEvictableIdleTimeMillis);
setTimeBetweenEvictionRunsMillis(conf.timeBetweenEvictionRunsMillis);
setSoftMinEvictableIdleTimeMillis(conf.softMinEvictableIdleTimeMillis);
setLifo(conf.lifo);
}
allocate();
}
//-- ObjectPool methods ------------------------------------------
/**
* maxActive, a new
* instance is created, activated and (if applicable) validated and returned to the caller.NoSuchElementException
* ({@link #WHEN_EXHAUSTED_FAIL}), or grow ({@link #WHEN_EXHAUSTED_GROW} - ignoring maxActive).
* The length of time that this method will block when whenExhaustedAction == WHEN_EXHAUSTED_BLOCK
* is determined by the {@link #getMaxWait() maxWait} property.factory while there are borrowed objects will
* throw an {@link IllegalStateException}. If there are instances idle
* in the pool when this method is invoked, these will be destroyed
* using the original factory.
*
* @param factory the {@link PoolableObjectFactory} used to create new instances.
* @throws IllegalStateException when the factory cannot be set at this time
* @deprecated to be removed in version 2.0
*/
@Deprecated
@Override
public void setFactory(PoolableObjectFactorynumTests idle object eviction tests, evicting
* examined objects that meet the criteria for eviction. If
* testWhileIdle is true, examined objects are validated
* when visited (and removed if invalid); otherwise only objects that
* have been idle for more than minEvicableIdletimeMillis
* are removed.numTestsPerEvictionRun
* and the number of idle instances in the pool.
*
* @see #setNumTestsPerEvictionRun
* @return the number of tests for the Evictor to run
*/
private int getNumTests() {
if(_numTestsPerEvictionRun >= 0) {
return Math.min(_numTestsPerEvictionRun, _pool.size());
} else {
return(int)(Math.ceil(_pool.size()/Math.abs((double)_numTestsPerEvictionRun)));
}
}
//--- inner classes ----------------------------------------------
/**
* The idle object evictor {@link TimerTask}.
* @see GenericObjectPool#setTimeBetweenEvictionRunsMillis
*/
private class Evictor extends TimerTask {
/**
* Run pool maintenance. Evict objects qualifying for eviction and then
* invoke {@link GenericObjectPool#ensureMinIdle()}.
*/
@Override
public void run() {
try {
evict();
} catch(Exception e) {
// ignored
} catch(OutOfMemoryError oome) {
// Log problem but give evictor thread a chance to continue in
// case error is recoverable
oome.printStackTrace(System.err);
}
try {
ensureMinIdle();
} catch(Exception e) {
// ignored
}
}
}
/**
* A simple "struct" encapsulating the
* configuration information for a {@link GenericObjectPool}.
* @see GenericObjectPool#GenericObjectPool(org.apache.commons.pool.PoolableObjectFactory,
* org.apache.commons.pool.impl.GenericObjectPool.Config)
* @see GenericObjectPool#setConfig
*/
public static class Config {
//CHECKSTYLE: stop VisibilityModifier
/**
* @see GenericObjectPool#setMaxIdle
*/
public int maxIdle = GenericObjectPool.DEFAULT_MAX_IDLE;
/**
* @see GenericObjectPool#setMinIdle
*/
public int minIdle = GenericObjectPool.DEFAULT_MIN_IDLE;
/**
* @see GenericObjectPool#setMaxActive
*/
public int maxActive = GenericObjectPool.DEFAULT_MAX_ACTIVE;
/**
* @see GenericObjectPool#setMaxWait
*/
public long maxWait = GenericObjectPool.DEFAULT_MAX_WAIT;
/**
* @see GenericObjectPool#setWhenExhaustedAction
*/
public byte whenExhaustedAction = GenericObjectPool.DEFAULT_WHEN_EXHAUSTED_ACTION;
/**
* @see GenericObjectPool#setTestOnBorrow
*/
public boolean testOnBorrow = GenericObjectPool.DEFAULT_TEST_ON_BORROW;
/**
* @see GenericObjectPool#setTestOnReturn
*/
public boolean testOnReturn = GenericObjectPool.DEFAULT_TEST_ON_RETURN;
/**
* @see GenericObjectPool#setTestWhileIdle
*/
public boolean testWhileIdle = GenericObjectPool.DEFAULT_TEST_WHILE_IDLE;
/**
* @see GenericObjectPool#setTimeBetweenEvictionRunsMillis
*/
public long timeBetweenEvictionRunsMillis = GenericObjectPool.DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS;
/**
* @see GenericObjectPool#setNumTestsPerEvictionRun
*/
public int numTestsPerEvictionRun = GenericObjectPool.DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
/**
* @see GenericObjectPool#setMinEvictableIdleTimeMillis
*/
public long minEvictableIdleTimeMillis = GenericObjectPool.DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
/**
* @see GenericObjectPool#setSoftMinEvictableIdleTimeMillis
*/
public long softMinEvictableIdleTimeMillis = GenericObjectPool.DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
/**
* @see GenericObjectPool#setLifo
*/
public boolean lifo = GenericObjectPool.DEFAULT_LIFO;
//CHECKSTYLE: resume VisibilityModifier
}
/**
* Latch used to control allocation order of objects to threads to ensure
* fairness. That is, objects are allocated to threads in the order that
* threads request objects.
*/
private static final class Latchnull GenericObjectPool.Config describing the configuration.
* @throws NullPointerException when config is null.
* @see GenericObjectPool#GenericObjectPool(PoolableObjectFactory, GenericObjectPool.Config)
*/
public GenericObjectPoolFactory(PoolableObjectFactorySoftReferenceObjectPool without a factory.
* {@link #setFactory(PoolableObjectFactory) setFactory} should be called
* before any attempts to use the pool are made.
* Generally speaking you should prefer the {@link #SoftReferenceObjectPool(PoolableObjectFactory)} constructor.
*
* @see #SoftReferenceObjectPool(PoolableObjectFactory)
* @deprecated to be removed in pool 2.0. Use {@link #SoftReferenceObjectPool(PoolableObjectFactory)}.
*/
@Deprecated
public SoftReferenceObjectPool() {
_pool = new ArrayListSoftReferenceObjectPool with the specified factory.
*
* @param factory object factory to use.
*/
public SoftReferenceObjectPool(PoolableObjectFactorySoftReferenceObjectPool with the specified factory and initial idle object count.
*
* @param factory object factory to use.
* @param initSize initial size to attempt to prefill the pool.
* @throws Exception when there is a problem prefilling the pool.
* @throws IllegalArgumentException when factory is null.
* @deprecated because this is a SoftReference pool, prefilled idle obejects may be garbage collected before they are used.
* To be removed in Pool 2.0.
*/
@Deprecated
public SoftReferenceObjectPool(PoolableObjectFactorymakeObject method is used
* to create a new instance. If the created instance either raises an exception on activation or
* fails validation, NoSuchElementException is thrown. Exceptions thrown by MakeObject
* are propagated to the caller; but other than ThreadDeath or VirtualMachineError,
* exceptions generated by activation, validation or destroy methods are swallowed silently.
*
*makeObject or passivate are
* propagated to the caller. Exceptions destroying instances are silently swallowed.factory while there are borrowed objects will
* throw an {@link IllegalStateException}.
*
* @param factory the {@link PoolableObjectFactory} used to create new instances.
* @throws IllegalStateException when the factory cannot be set at this time
* @deprecated to be removed in pool 2.0
*/
@Deprecated
@Override
public synchronized void setFactory(PoolableObjectFactory_pool.
* This is used to help {@link #getNumIdle()} be more accurate with minimial
* performance overhead.
*/
private final ReferenceQueueStack-based KeyedObjectPool implementation.
* Objects without introducing
* artificial limits.
* SimpleKeyedObjectPool using
* the specified factory to create new instances.
*
* @param factory the {@link KeyedPoolableObjectFactory} used to populate the pool
*/
public StackKeyedObjectPool(KeyedPoolableObjectFactorySimpleKeyedObjectPool using
* the specified factory to create new instances.
* capping the number of "sleeping" instances to max
*
* @param factory the {@link KeyedPoolableObjectFactory} used to populate the pool
* @param max cap on the number of "sleeping" instances in the pool
*/
public StackKeyedObjectPool(KeyedPoolableObjectFactorySimpleKeyedObjectPool using
* the specified factory to create new instances.
* capping the number of "sleeping" instances to max,
* and initially allocating a container capable of containing
* at least init instances.
*
* @param factory the {@link KeyedPoolableObjectFactory} used to populate the pool
* @param max cap on the number of "sleeping" instances in the pool
* @param init initial size of the pool (this specifies the size of the container,
* it does not cause the pool to be pre-populated.)
*/
public StackKeyedObjectPool(KeyedPoolableObjectFactoryobj to the pool under key. If adding the
* returning instance to the pool results in {@link #_maxSleeping maxSleeping}
* exceeded for the given key, the oldest instance in the idle object pool
* is destroyed to make room for the returning instance.
*
* @param key the pool key
* @param obj returning instance
*/
@Override
public synchronized void returnObject(K key, V obj) throws Exception {
decrementActiveCount(key);
if (null != _factory) {
if (_factory.validateObject(key, obj)) {
try {
_factory.passivateObject(key, obj);
} catch (Exception ex) {
_factory.destroyObject(key, obj);
return;
}
} else {
return;
}
}
if (isClosed()) {
if (null != _factory) {
try {
_factory.destroyObject(key, obj);
} catch (Exception e) {
// swallowed
}
}
return;
}
StackaddObject is useful for "pre-loading" a pool with idle objects.
*
* @param key the key a new instance should be added to
* @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails.
* @throws IllegalStateException when no {@link #setFactory factory} has been set or after {@link #close} has been called on this pool.
*/
@Override
public synchronized void addObject(K key) throws Exception {
assertOpen();
if (_factory == null) {
throw new IllegalStateException("Cannot add objects without a factory.");
}
V obj = _factory.makeObject(key);
try {
if (!_factory.validateObject(key, obj)) {
return;
}
} catch (Exception e) {
try {
_factory.destroyObject(key, obj);
} catch (Exception e2) {
// swallowed
}
return;
}
_factory.passivateObject(key, obj);
Stackkey.
*
* @param key the key to query
* @return the number of instances corresponding to the given key currently borrowed in this pool
*/
@Override
public synchronized int getNumActive(K key) {
return getActiveCount(key);
}
/**
* Returns the number of instances corresponding to the given key currently idle in this pool.
*
* @param key the key to query
* @return the number of instances corresponding to the given key currently idle in this pool
*/
@Override
public synchronized int getNumIdle(K key) {
try {
return(_pools.get(key)).size();
} catch(Exception e) {
return 0;
}
}
/**
* Clears the pool, removing all pooled instances.
*/
@Override
public synchronized void clear() {
Iteratorkey.
*
* @param key the key to clear
*/
@Override
public synchronized void clear(K key) {
Stackfactory after a pool has been used will frequently
* throw an {@link UnsupportedOperationException}.
*
* @param factory the {@link KeyedPoolableObjectFactory} used to manage object instances
* @throws IllegalStateException when the factory cannot be set at this time
* @deprecated to be removed in pool 2.0
*/
@Deprecated
@Override
public synchronized void setFactory(KeyedPoolableObjectFactoryeach pool.
* @since 1.5.5
*/
public int getMaxSleeping() {
return _maxSleeping;
}
/**
* @return the initial capacity of each pool.
* @since 1.5.5
*/
public int getInitSleepingCapacity() {
return _initSleepingCapacity;
}
/**
* @return the _totActive
*/
public int getTotActive() {
return _totActive;
}
/**
* @return the _totIdle
*/
public int getTotIdle() {
return _totIdle;
}
/**
* @return the _activeCount
* @since 1.5.5
*/
public Mapeach pool.
* @deprecated to be removed in pool 2.0. Use {@link #getMaxSleeping()}
*/
@Deprecated
protected int _maxSleeping = DEFAULT_MAX_SLEEPING;
/**
* The initial capacity of each pool.
* @deprecated to be removed in pool 2.0. Use {@link #getInitSleepingCapacity()}.
*/
@Deprecated
protected int _initSleepingCapacity = DEFAULT_INIT_SLEEPING_CAPACITY;
/**
* Total number of object borrowed and not yet returned for all pools.
* @deprecated to be removed in pool 2.0. Use {@link #getTotActive()}.
*/
@Deprecated
protected int _totActive = 0;
/**
* Total number of objects "sleeping" for all pools
* @deprecated to be removed in pool 2.0. Use {@link #getTotIdle()}.
*/
@Deprecated
protected int _totIdle = 0;
/**
* Number of active objects borrowed and not yet returned by pool
* @deprecated to be removed in pool 2.0. Use {@link #getActiveCount()}.
*/
@Deprecated
protected HashMapfactory to create new instances,
* capping the number of "sleeping" instances to maxIdle, and initially allocating a container
* capable of containing at least initIdleCapacity instances. The pool is not pre-populated.
* The initIdleCapacity parameter just determines the initial size of the underlying
* container, which can increase beyond this value if maxIdle > initIdleCapacity.maxIdle are ignored (i.e., the pool is created using
* {@link #DEFAULT_MAX_SLEEPING}) as are non-positive values for initIdleCapacity.
*
* @param factory the {@link PoolableObjectFactory} used to populate the pool
* @param maxIdle cap on the number of "sleeping" instances in the pool
* @param initIdleCapacity initial size of the pool (this specifies the size of the container,
* it does not cause the pool to be pre-populated.)
*/
public StackObjectPool(PoolableObjectFactorymakeObject method is used
* to create a new instance. If a null instance is returned by the factory or the created
* instance either raises an exception on activation or fails validation, NoSuchElementException
* is thrown. Exceptions thrown by MakeObject are propagated to the caller; but
* other than ThreadDeath or VirtualMachineError, exceptions generated by
* activation, validation or destroy methods are swallowed silently.
*
* If adding a validated, passivated returning instance to the stack would cause
* {@link #getMaxSleeping() maxSleeping} to be exceeded, the oldest (bottom) instance on the stack
* is destroyed to make room for the returning instance, which is pushed on top of the stack.makeObject or passivate are
* propagated to the caller. Exceptions destroying instances are silently swallowed.factory while there are borrowed objects will
* throw an {@link IllegalStateException}.
*
* @param factory the {@link PoolableObjectFactory} used to create new instances.
* @throws IllegalStateException when the factory cannot be set at this time
* @deprecated to be removed in pool 2.0
*/
@Deprecated
@Override
public synchronized void setFactory(PoolableObjectFactory Object obj =
* null;
* Object key = "Key";
*
* try {
* obj = pool.borrowObject(key);
* //...use the object...
* } catch(Exception e) {
* // invalidate the object
* pool.invalidateObject(key, obj);
* // do not return the object to the pool twice
* obj = null;
* } finally {
* // make sure the object is returned to the pool
* if(null != obj) {
* pool.returnObject(key, obj);
* }
* }key.
* key that is {@link Object#equals equivalent} to the one used to
* borrow the instance in the first place.
* null to indicate exhaustion,
* newer versions are encouraged to throw a {@link NoSuchElementException}.
*
* @param key the key used to obtain the object
* @return an instance from this pool.
* @throws IllegalStateException after {@link #close close} has been called on this pool
* @throws Exception when {@link KeyedPoolableObjectFactory#makeObject makeObject} throws an exception
* @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance
*/
V borrowObject(K key) throws Exception, NoSuchElementException, IllegalStateException;
/**
* Return an instance to the pool.
* By contract, obj must have been obtained
* using {@link #borrowObject borrowObject}
* or a related method as defined in an implementation
* or sub-interface
* using a key that is equivalent to the one used to
* borrow the instance in the first place.
*
* @param key the key used to obtain the object
* @param obj a {@link #borrowObject borrowed} instance to be returned.
* @throws Exception
*/
void returnObject(K key, V obj) throws Exception;
/**
* obj must have been obtained
* using {@link #borrowObject borrowObject} or a related method as defined
* in an implementation or sub-interface using a key that is
* equivalent to the one used to borrow the Object in the first place.addObject is useful for "pre-loading" a pool with idle objects
* (Optional operation).
*
* @param key the key a new instance should be added to
* @throws Exception when {@link KeyedPoolableObjectFactory#makeObject} fails.
* @throws IllegalStateException after {@link #close} has been called on this pool.
* @throws UnsupportedOperationException when this pool cannot add new idle objects.
*/
void addObject(K key) throws Exception, IllegalStateException, UnsupportedOperationException;
/**
* Returns the number of instances
* corresponding to the given key
* currently idle in this pool (optional operation).
* Returns a negative value if this information is not available.
*
* @param key the key to query
* @return the number of instances corresponding to the given key currently idle in this pool or a negative value if unsupported
* @throws UnsupportedOperationException deprecated: when this implementation doesn't support the operation
*/
int getNumIdle(K key) throws UnsupportedOperationException;
/**
* Returns the number of instances
* currently borrowed from but not yet returned
* to the pool corresponding to the
* given key (optional operation).
* Returns a negative value if this information is not available.
*
* @param key the key to query
* @return the number of instances corresponding to the given key currently borrowed in this pool or a negative value if unsupported
* @throws UnsupportedOperationException deprecated: when this implementation doesn't support the operation
*/
int getNumActive(K key) throws UnsupportedOperationException;
/**
* Returns the total number of instances
* currently idle in this pool (optional operation).
* Returns a negative value if this information is not available.
*
* @return the total number of instances currently idle in this pool or a negative value if unsupported
* @throws UnsupportedOperationException deprecated: when this implementation doesn't support the operation
*/
int getNumIdle() throws UnsupportedOperationException;
/**
* Returns the total number of instances
* current borrowed from this pool but not
* yet returned (optional operation).
* Returns a negative value if this information is not available.
*
* @return the total number of instances currently borrowed from this pool or a negative value if unsupported
* @throws UnsupportedOperationException deprecated: when this implementation doesn't support the operation
*/
int getNumActive() throws UnsupportedOperationException;
/**
* Clears the pool, removing all pooled instances (optional operation).
* Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
*
* @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
void clear() throws Exception, UnsupportedOperationException;
/**
* Clears the specified pool, removing all
* pooled instances corresponding to
* the given key (optional operation).
* Throws {@link UnsupportedOperationException} if the pool cannot be cleared.
*
* @param key the key to clear
* @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
void clear(K key) throws Exception, UnsupportedOperationException;
/**
* Close this pool, and free any resources associated with it.
* factory after a pool has been used will frequently
* throw an {@link UnsupportedOperationException}. It is up to the pool
* implementation to determine when it is acceptable to call this method.
*
* @param factory the {@link KeyedPoolableObjectFactory} used to create new instances.
* @throws IllegalStateException when the factory cannot be set at this time
* @throws UnsupportedOperationException when this implementation doesn't support the operation
* @deprecated to be removed in pool 2.0
*/
@Deprecated
void setFactory(KeyedPoolableObjectFactory
*
* validateObject may also be used to test an
* instance being {@link KeyedObjectPool#returnObject returned} to the pool
* before it is {@link #passivateObject passivated}. It will only be invoked
* on an activated instance.
* validateObject,
* or for reasons specific to the pool implementation.) There is no
* guarantee that the instance being destroyed will
* be considered active, passive or in a generally consistent state.
* KeyedPoolableObjectFactory
* at a time.
* obj
* will be in and the implementation should be prepared to handle
* unexpected errors.
* false if obj should be destroyed.
*
* @param key the key used when selecting the object
* @param obj the instance to be validated
* @return false if obj is not valid and should
* be dropped from the pool, true otherwise.
*/
boolean validateObject(K key, V obj);
/**
* Reinitialize an instance to be returned by the pool.
*
* @param key the key used when selecting the object
* @param obj the instance to be activated
* @throws Exception if there is a problem activating obj,
* this exception may be swallowed by the pool.
* @see #destroyObject
*/
void activateObject(K key, V obj) throws Exception;
/**
* Uninitialize an instance to be returned to the idle object pool.
*
* @param key the key used when selecting the object
* @param obj the instance to be passivated
* @throws Exception if there is a problem passivating obj,
* this exception may be swallowed by the pool.
* @see #destroyObject
*/
void passivateObject(K key, V obj) throws Exception;
}
commons-pool-1.6-src/src/java/org/apache/commons/pool/ObjectPool.java 100644 0 0 21271 11701070262 23004 0 ustar 0 0 /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.pool;
import java.util.NoSuchElementException;
/**
* A pooling interface.
* ObjectPool defines a trivially simple pooling interface. The only
* required methods are {@link #borrowObject borrowObject}, {@link #returnObject returnObject}
* and {@link #invalidateObject invalidateObject}.
* Object obj =
* null;
*
* try {
* obj = pool.borrowObject();
* try {
* //...use the object...
* } catch(Exception e) {
* // invalidate the object
* pool.invalidateObject(obj);
* // do not return the object to the pool twice
* obj = null;
* } finally {
* // make sure the object is returned to the pool
* if(null != obj) {
* pool.returnObject(obj);
* }
* }
* } catch(Exception e) {
* // failed to borrow an object
* }null to indicate exhaustion,
* newer versions are encouraged to throw a {@link NoSuchElementException}.
* obj must have been obtained
* using {@link #borrowObject() borrowObject}
* or a related method as defined in an implementation
* or sub-interface.
*
* @param obj a {@link #borrowObject borrowed} instance to be returned.
* @throws Exception
*/
void returnObject(T obj) throws Exception;
/**
* obj must have been obtained
* using {@link #borrowObject borrowObject} or a related method as defined in
* an implementation or sub-interface.addObject is useful for "pre-loading" a pool with idle objects.
* (Optional operation).
*
* @throws Exception when {@link PoolableObjectFactory#makeObject} fails.
* @throws IllegalStateException after {@link #close} has been called on this pool.
* @throws UnsupportedOperationException when this pool cannot add new idle objects.
*/
void addObject() throws Exception, IllegalStateException, UnsupportedOperationException;
/**
* Return the number of instances
* currently idle in this pool (optional operation).
* This may be considered an approximation of the number
* of objects that can be {@link #borrowObject borrowed}
* without creating any new instances.
* Returns a negative value if this information is not available.
*
* @return the number of instances currently idle in this pool or a negative value if unsupported
* @throws UnsupportedOperationException deprecated: if this implementation does not support the operation
*/
int getNumIdle() throws UnsupportedOperationException;
/**
* Return the number of instances
* currently borrowed from this pool
* (optional operation).
* Returns a negative value if this information is not available.
*
* @return the number of instances currently borrowed from this pool or a negative value if unsupported
* @throws UnsupportedOperationException deprecated: if this implementation does not support the operation
*/
int getNumActive() throws UnsupportedOperationException;
/**
* Clears any objects sitting idle in the pool, releasing any
* associated resources (optional operation).
* Idle objects cleared must be {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
*
* @throws UnsupportedOperationException if this implementation does not support the operation
*/
void clear() throws Exception, UnsupportedOperationException;
/**
* Close this pool, and free any resources associated with it.
* factory after a pool has been used will frequently
* throw an {@link UnsupportedOperationException}. It is up to the pool
* implementation to determine when it is acceptable to call this method.
*
* @param factory the {@link PoolableObjectFactory} used to create new instances.
* @throws IllegalStateException when the factory cannot be set at this time
* @throws UnsupportedOperationException if this implementation does not support the operation
* @deprecated to be removed in pool 2.0
*/
@Deprecated
void setFactory(PoolableObjectFactoryorg.apache.commons.pool package defines a simple
interface for a pool of object instances, and a handful of base
classes that may be useful when creating pool implementations.
The API supports pooling of unique objects which can be requested
via a key as well as pools where all objects are equivalent.
org.apache.commons.pool.impl package contains
several pool implementations.
{@link org.apache.commons.pool.impl.StackObjectPool StackObjectPool}
is useful for supporting reuse of a limited number of instances while
allowing new instances to be created as needed to support high demand.
{@link org.apache.commons.pool.impl.GenericObjectPool
GenericObjectPool} has many configuration options and can support
a limited set of objects such as would be useful in a database
connection pool.
{@link org.apache.commons.pool.impl.SoftReferenceObjectPool
SoftReferenceObjectPool} has no limit on the number of objects in the
pool, but the garbage collector can remove idle objects from the pool
as needed. There are also keyed versions of the first two.
HashMap's. First
create an {@link org.apache.commons.pool.ObjectPoolFactory
ObjectPoolFactory}
public class HashMapFactory
extends {@link org.apache.commons.pool.BasePoolableObjectFactory BasePoolableObjectFactory}
{
/**
* Creates an instance that can be returned by the pool.
* @return an instance that can be returned by the pool.
*/
public Object makeObject()
throws Exception
{
return new HashMap();
}
/**
* Uninitialize an instance to be returned to the pool.
* @param obj the instance to be passivated
*/
public void passivateObject(Object obj)
throws Exception
{
Map map = (Map)obj;
map.clear();
}
}
public class Foo
{
private {@link org.apache.commons.pool.ObjectPool ObjectPool} pool;
public Foo()
{
{@link org.apache.commons.pool.PoolableObjectFactory PoolableObjectFactory} factory = new HashMapFactory();
pool = new StackObjectPool(factory, 1000);
}
public doSomething()
{
...
Map map = null;
try
{
map = (Map)pool.borrowObject();
// use map
...
}
finally
{
if (map != null)
{
pool.returnObject(map);
}
}
...
}
}
org.apache.commons.pool package defines a simple
interface for a pool of object instances, and a handful of base
classes that may be useful when creating pool implementations.
pool package itself doesn't define a specific object
pooling implementation, but rather a contract that implementations may
support in order to be fully interchangeable.
pool package separates the way in which instances are
pooled from the way in which they are created, resulting in a pair of
interfaces:
ObjectPools, which may be
useful for some applications.
pool package also provides a keyed pool interface,
which pools instances of multiple types, accessed according to an
arbitrary key. See
{@link org.apache.commons.pool.KeyedObjectPool KeyedObjectPool},
{@link org.apache.commons.pool.KeyedPoolableObjectFactory KeyedPoolableObjectFactory},
and
{@link org.apache.commons.pool.KeyedObjectPoolFactory KeyedObjectPoolFactory}.
*
* validateObject may also be used to test an
* instance being {@link ObjectPool#returnObject returned} to the pool
* before it is {@link #passivateObject passivated}. It will only be invoked
* on an activated instance.
* validateObject,
* or for reasons specific to the pool implementation.) There is no
* guarantee that the instance being destroyed will
* be considered active, passive or in a generally consistent state.
* PoolableObjectFactory
* at a time.
* obj
* will be in and the implementation should be prepared to handle
* unexpected errors.
* false if obj should be destroyed.
*
* @param obj the instance to be validated
* @return false if obj is not valid and should
* be dropped from the pool, true otherwise.
*/
boolean validateObject(T obj);
/**
* Reinitialize an instance to be returned by the pool.
*
* @param obj the instance to be activated
* @throws Exception if there is a problem activating obj,
* this exception may be swallowed by the pool.
* @see #destroyObject
*/
void activateObject(T obj) throws Exception;
/**
* Uninitialize an instance to be returned to the idle object pool.
*
* @param obj the instance to be passivated
* @throws Exception if there is a problem passivating obj,
* this exception may be swallowed by the pool.
* @see #destroyObject
*/
void passivateObject(T obj) throws Exception;
}
commons-pool-1.6-src/src/java/org/apache/commons/pool/PoolUtils.java 100644 0 0 262533 11701070263 22727 0 ustar 0 0 /*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.pool;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.NoSuchElementException;
import java.util.Timer;
import java.util.TimerTask;
/**
* This class consists exclusively of static methods that operate on or return ObjectPool
* or KeyedObjectPool related interfaces.
*
* @author Sandy McArthur
* @version $Revision: 1222670 $ $Date: 2011-12-23 08:18:25 -0500 (Fri, 23 Dec 2011) $
* @since Pool 1.3
*/
public final class PoolUtils {
/**
* Timer used to periodically check pools idle object count.
* Because a {@link Timer} creates a {@link Thread} this is lazily instantiated.
*/
private static Timer MIN_IDLE_TIMER; //@GuardedBy("this")
/**
* PoolUtils instances should NOT be constructed in standard programming.
* Instead, the class should be used procedurally: PoolUtils.adapt(aPool);.
* This constructor is public to permit tools that require a JavaBean instance to operate.
*/
public PoolUtils() {
}
/**
* Should the supplied Throwable be re-thrown (eg if it is an instance of
* one of the Throwables that should never be swallowed). Used by the pool
* error handling for operations that throw exceptions that normally need to
* be ignored.
* @param t The Throwable to check
* @throws ThreadDeath if that is passed in
* @throws VirtualMachineError if that is passed in
* @since Pool 1.5.5
*/
public static void checkRethrow(Throwable t) {
if (t instanceof ThreadDeath) {
throw (ThreadDeath) t;
}
if (t instanceof VirtualMachineError) {
throw (VirtualMachineError) t;
}
// All other instances of Throwable will be silently swallowed
}
/**
* Adapt a KeyedPoolableObjectFactory instance to work where a PoolableObjectFactory is
* needed. This method is the equivalent of calling
* {@link #adapt(KeyedPoolableObjectFactory, Object) PoolUtils.adapt(aKeyedPoolableObjectFactory, new Object())}.
*
* @param keyedFactory with an internal key.
* @throws IllegalArgumentException when keyedFactory is null.
* @see #adapt(KeyedPoolableObjectFactory, Object)
* @since Pool 1.3
*/
public static KeyedPoolableObjectFactory instance to work where a PoolableObjectFactory is
* needed using the specified key when delegating.
*
* @param keyedFactory with the specified key.
* @throws IllegalArgumentException when keyedFactory or key is null.
* @see #adapt(KeyedPoolableObjectFactory)
* @since Pool 1.3
*/
public static PoolableObjectFactory instance to work where a KeyedPoolableObjectFactory is
* needed. The key is ignored.
*
* @param factory ignoring the key.
* @throws IllegalArgumentException when factory is null.
* @since Pool 1.3
*/
public static KeyedObjectPool instance to work where an ObjectPool is needed. This is the
* equivalent of calling {@link #adapt(KeyedObjectPool, Object) PoolUtils.adapt(aKeyedObjectPool, new Object())}.
*
* @param keyedPool with an internal key.
* @throws IllegalArgumentException when keyedPool is null.
* @see #adapt(KeyedObjectPool, Object)
* @since Pool 1.3
*/
public static KeyedObjectPool instance to work where an ObjectPool is needed using the
* specified key when delegating.
*
* @param keyedPool with the specified key.
* @throws IllegalArgumentException when keyedPool or key is null.
* @see #adapt(KeyedObjectPool)
* @since Pool 1.3
*/
public static ObjectPool to work where an KeyedObjectPool is needed.
* The key is ignored.
*
* @param pool ignoring the key.
* @throws IllegalArgumentException when pool is null.
* @since Pool 1.3
*/
public static ObjectPool and dynamically checks the type of objects borrowed and returned to the pool.
* If an object is passed to the pool that isn't of type type a {@link ClassCastException} will be thrown.
*
* @param ObjectPool that will only allow objects of type
* @since Pool 1.3
*/
public static KeyedObjectPool and dynamically checks the type of objects borrowed and returned to the keyedPool.
* If an object is passed to the keyedPool that isn't of type type a {@link ClassCastException} will be thrown.
*
* @param KeyedObjectPool that will only allow objects of type
* @since Pool 1.3
*/
public static pool is null or
* when minIdle is negative or when period isn't
* valid for {@link Timer#schedule(TimerTask, long, long)}.
* @since Pool 1.3
*/
public static keyedPool, key is null or
* when minIdle is negative or when period isn't
* valid for {@link Timer#schedule(TimerTask, long, long)}.
* @since Pool 1.3
*/
public static Collection keys in the keyedPool.
* At most one idle object will be added per period.
*
* @param keyedPool, keys, or any of the values in the
* collection is null or when minIdle is negative or when period isn't
* valid for {@link Timer#schedule(TimerTask, long, long)}.
* @see #checkMinIdle(KeyedObjectPool, Object, int, long)
* @since Pool 1.3
*/
public static addObject() on pool count number of times.
*
* @param pool is null.
* @since Pool 1.3
*/
public static addObject(Object) on keyedPool with key count
* number of times.
*
* @param key.
* @throws Exception when {@link KeyedObjectPool#addObject(Object)} fails.
* @throws IllegalArgumentException when keyedPool or key is null.
* @since Pool 1.3
*/
public static addObject(Object) on keyedPool with each key in keys for
* count number of times. This has the same effect as calling
* {@link #prefill(KeyedObjectPool, Object, int)} for each key in the keys collection.
*
* @param key.
* @throws Exception when {@link KeyedObjectPool#addObject(Object)} fails.
* @throws IllegalArgumentException when keyedPool, keys, or
* any value in keys is null.
* @see #prefill(KeyedObjectPool, Object, int)
* @since Pool 1.3
*/
public static Timer for checking keyedPool's idle count. Lazily create the {@link Timer} as needed.
*
* @return the {@link Timer} for checking keyedPool's idle count.
* @since Pool 1.3
*/
private static synchronized Timer getMinIdleTimer() {
if (MIN_IDLE_TIMER == null) {
MIN_IDLE_TIMER = new Timer(true);
}
return MIN_IDLE_TIMER;
}
/**
* Adaptor class that wraps and converts a KeyedPoolableObjectFactory with a fixed
* key to a PoolableObjectFactory.
*/
private static class PoolableObjectFactoryAdaptor