Borrows an object from the sub-pool associated with the given key using
the specified waiting time which only applies if
{@link #getBlockWhenExhausted()} is true.
<p>
If there is one or more idle instances available in the sub-pool
associated with the given key, then an idle instance will be selected
based on the value of {@link #getLifo()}, activated and returned. If
activation fails, or {@link #getTestOnBorrow() testOnBorrow} is set to
<code>true</code> 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.
<p>
If there are no idle instances available in the sub-pool associated with
the given key, behavior depends on the {@link #getMaxTotalPerKey()
maxTotalPerKey}, {@link #getMaxTotal() maxTotal}, and (if applicable)
{@link #getBlockWhenExhausted()} and the value passed in to the
<code>borrowMaxWaitMillis</code> parameter. If the number of instances checked
out from the sub-pool under the given key is less than
<code>maxTotalPerKey</code> and the total number of instances in
circulation (under all keys) is less than <code>maxTotal</code>, a new
instance is created, activated and (if applicable) validated and returned
to the caller. If validation fails, a <code>NoSuchElementException</code>
will be thrown.
<p>
If the associated sub-pool is exhausted (no available idle instances and
no capacity to create new ones), this method will either block
({@link #getBlockWhenExhausted()} is true) or throw a
<code>NoSuchElementException</code>
({@link #getBlockWhenExhausted()} is false).
The length of time that this method will block when
{@link #getBlockWhenExhausted()} is true is determined by the value
passed in to the <code>borrowMaxWait</code> parameter.
<p>
When <code>maxTotal</code> is set to a positive value and this method is
invoked when at the limit with no idle instances available under the requested
key, an attempt is made to create room by clearing the oldest 15% of the
elements from the keyed sub-pools.
<p>
When the pool is exhausted, multiple calling threads may be
simultaneously blocked waiting for instances to become available. A
"fairness" algorithm has been implemented to ensure that threads receive
available instances in request arrival order.
@param key pool key
@param borrowMaxWaitMillis The time to wait in milliseconds for an object
to become available
@return object instance from the keyed pool
@throws NoSuchElementException if a keyed object instance cannot be
returned because the pool is exhausted.
@throws Exception if a keyed object instance cannot be returned due to an
error
Borrows an object from the sub-pool associated with the given key using the specified waiting time which only applies if {@link #getBlockWhenExhausted()} is true. <p> If there is one or more idle instances available in the sub-pool associated with the given key, then an idle instance will be selected based on the value of {@link #getLifo()}, activated and returned. If activation fails, or {@link #getTestOnBorrow() testOnBorrow} is set to <code>true</code> 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. <p> If there are no idle instances available in the sub-pool associated with the given key, behavior depends on the {@link #getMaxTotalPerKey() maxTotalPerKey}, {@link #getMaxTotal() maxTotal}, and (if applicable) {@link #getBlockWhenExhausted()} and the value passed in to the <code>borrowMaxWaitMillis</code> parameter. If the number of instances checked out from the sub-pool under the given key is less than <code>maxTotalPerKey</code> and the total number of instances in circulation (under all keys) is less than <code>maxTotal</code>, a new instance is created, activated and (if applicable) validated and returned to the caller. If validation fails, a <code>NoSuchElementException</code> will be thrown. <p> If the associated sub-pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block ({@link #getBlockWhenExhausted()} is true) or throw a <code>NoSuchElementException</code> ({@link #getBlockWhenExhausted()} is false). The length of time that this method will block when {@link #getBlockWhenExhausted()} is true is determined by the value passed in to the <code>borrowMaxWait</code> parameter. <p> When <code>maxTotal</code> is set to a positive value and this method is invoked when at the limit with no idle instances available under the requested key, an attempt is made to create room by clearing the oldest 15% of the elements from the keyed sub-pools. <p> When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances to become available. A "fairness" algorithm has been implemented to ensure that threads receive available instances in request arrival order.
@param key pool key @param borrowMaxWaitMillis The time to wait in milliseconds for an object to become available
@return object instance from the keyed pool
@throws NoSuchElementException if a keyed object instance cannot be returned because the pool is exhausted.
@throws Exception if a keyed object instance cannot be returned due to an error