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.