The behaviour of this method when the pool has been exhausted is not specified (although it may be specified by implementations). @return an instance from my pool.
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 thenext 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 thenumber of instances checked out from the pool under the given key is less than 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.
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 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.
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.
@param key pool key @return object instance from the keyed pool @throws NoSuchElementException if a keyed object instance cannot be returned.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 poolwill be activated and returned. If activation fails, or {@link #getTestOnBorrow() testOnBorrow} is setto 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 maxActive,
a new instance is created, activated and (if applicable) validated and returned to the caller.
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 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.
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.
@return object instance @throws NoSuchElementException if an instance cannot be returnedInstances returned from this method will have been either newly created with {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object andhave been activated with {@link PoolableObjectFactory#activateObject activateObject} andthen 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 null
to indicate exhaustion, newer versions are encouraged to throw a {@link NoSuchElementException}.
|
|
|
|
|
|
|
|
|
|