Top Description Methods
org.apache.commons.pool2

public Interface KeyedObjectPool<K, V>

extends Closeable
Known Direct Implementers
org.apache.commons.pool2.PoolUtils.ErodingKeyedObjectPool, org.apache.commons.pool2.PoolUtils.SynchronizedKeyedObjectPool, org.apache.commons.pool2.impl.GenericKeyedObjectPool, org.apache.commons.pool2.proxy.ProxiedKeyedObjectPool
Type Parameters
<K>
The type of keys maintained by this pool.
<V>
Type of element pooled in this pool.
Imports
java.io.Closeable, java.util.Collection, .Collections, .List, .NoSuchElementException
A "keyed" pooling interface.

A keyed pool maintains a pool of instances for each key value.

Example of use: 

 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);
    }
}

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 Map of pools).

See GenericKeyedObjectPool for an implementation.

Since
2.0
See Also
KeyedPooledObjectFactory, ObjectPool, GenericKeyedObjectPool

Method Summary

Modifier and TypeMethod and Description
public void
addObject(K
the key a new instance should be added to
key)

Creates an object using the factory or other implementation dependent mechanism, passivate it, and then place it in the idle object pool.

public default void
addObjects(final Collection<K>
Collection of keys to add objects for.
keys, final int
the number of idle objects to add for each key.
count)

Calls KeyedObjectPool#addObject(Object) with each key in keys for count number of times.

public default void
addObjects(final K
the key to add objects for.
key, final int
the number of idle objects to add for key.
count)

Calls KeyedObjectPool#addObject(Object) key count number of times.

public V

Returns:

an instance from this pool.
borrowObject(K
the key used to obtain the object
key)

Borrows an instance from this pool for the specified key.

public void
clear()

Clears the pool, removing all pooled instances (optional operation).

public void
clear(K
the key to clear
key)

Clears the specified pool, removing all pooled instances corresponding to the given key (optional operation).

public void
close()

Redeclares java.io.Closeable.close.

Closes this pool, and free any resources associated with it.
public default List<K>

Returns:

a copy of the pool key list.
getKeys()

Gets a copy of the pool key list.

public int

Returns:

the total number of instances currently borrowed from this pool but not yet returned.
getNumActive()

Gets the total number of instances currently borrowed from this pool but not yet returned.

public int

Returns:

the number of instances currently borrowed from but not yet returned to the pool corresponding to the given key.
getNumActive(K
the key to query
key)

Gets the number of instances currently borrowed from but not yet returned to the pool corresponding to the given key.

public int

Returns:

the total number of instances currently idle in this pool.
getNumIdle()

Gets the total number of instances currently idle in this pool.

public int

Returns:

the number of instances corresponding to the given key currently idle in this pool.
getNumIdle(K
the key to query
key)

Gets the number of instances corresponding to the given key currently idle in this pool.

public void
invalidateObject(K
the key used to obtain the object
key, V
a borrowed instance to be returned.
obj)

Invalidates an object from the pool.

public default void
invalidateObject(final K
the key used to obtain the object
key, final V
a borrowed instance to be returned.
obj, final DestroyMode
destroy activation context provided to the factory
destroyMode)

Invalidates an object from the pool, using the provided DestroyMode.

public void
returnObject(K
the key used to obtain the object
key, V
a borrowed instance to be returned.
obj)

Return an instance to the pool.

Method Detail

addObjectback to summary
public void addObject(K key) throws Exception

Creates an object using the factory or other implementation dependent mechanism, passivate it, and then place it in the idle object pool. addObject is useful for "pre-loading" a pool with idle objects (Optional operation).

Parameters
key:K

the key a new instance should be added to

Exceptions
Exception:
when KeyedPooledObjectFactory#makeObject fails.
IllegalStateException:
after close has been called on this pool.
UnsupportedOperationException:
when this pool cannot add new idle objects.
addObjectsback to summary
public default void addObjects(final Collection<K> keys, final int count) throws Exception

Calls KeyedObjectPool#addObject(Object) with each key in keys for count number of times. This has the same effect as calling addObjects(Object, int) for each key in the keys collection.

Parameters
keys:Collection<K>

Collection of keys to add objects for.

count:int

the number of idle objects to add for each key.

Exceptions
Exception:
when KeyedObjectPool#addObject(Object) fails.
IllegalArgumentException:
when keyedPool, keys, or any value in keys is null.
See Also
addObjects(Object, int)
addObjectsback to summary
public default void addObjects(final K key, final int count) throws Exception

Calls KeyedObjectPool#addObject(Object) key count number of times.

Parameters
key:K

the key to add objects for.

count:int

the number of idle objects to add for key.

Exceptions
Exception:
when KeyedObjectPool#addObject(Object) fails.
IllegalArgumentException:
when key is null.
Since
2.8.0
borrowObjectback to summary
public V borrowObject(K key) throws Exception

Borrows an instance from this pool for the specified key.

Instances returned from this method will have been either newly created with makeObject or will be a previously idle object and have been activated with activateObject and then (optionally) validated with validateObject.

By contract, clients must return the borrowed object using returnObject, invalidateObject, 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.

The behavior of this method when the pool has been exhausted is not strictly specified (although it may be specified by implementations).

Parameters
key:K

the key used to obtain the object

Returns:V

an instance from this pool.

Exceptions
Exception:
when makeObject throws an exception
IllegalStateException:
after close has been called on this pool
NoSuchElementException:
when the pool is exhausted and cannot or will not return another instance
clearback to summary
public void clear() throws Exception

Clears the pool, removing all pooled instances (optional operation).

Exceptions
Exception:
if the pool cannot be cleared
UnsupportedOperationException:
when this implementation doesn't support the operation
clearback to summary
public void clear(K key) throws Exception

Clears the specified pool, removing all pooled instances corresponding to the given key (optional operation).

Parameters
key:K

the key to clear

Exceptions
Exception:
if the key cannot be cleared
UnsupportedOperationException:
when this implementation doesn't support the operation
closeback to summary
public void close()

Redeclares java.io.Closeable.close.

Closes this pool, and free any resources associated with it.

Calling addObject or borrowObject after invoking this method on a pool will cause them to throw an IllegalStateException.

Implementations should silently fail if not all resources can be freed.

Annotations
@Override
getKeysback to summary
public default List<K> getKeys()

Gets a copy of the pool key list.

Note

The default implementation returns an empty list. Implementations should override this method.

Returns:List<K>

a copy of the pool key list.

Since
2.12.0
getNumActiveback to summary
public int getNumActive()

Gets the total number of instances currently borrowed from this pool but not yet returned. Returns a negative value if this information is not available.

Returns:int

the total number of instances currently borrowed from this pool but not yet returned.

getNumActiveback to summary
public int getNumActive(K key)

Gets the number of instances currently borrowed from but not yet returned to the pool corresponding to the given key. Returns a negative value if this information is not available.

Parameters
key:K

the key to query

Returns:int

the number of instances currently borrowed from but not yet returned to the pool corresponding to the given key.

getNumIdleback to summary
public int getNumIdle()

Gets the total number of instances currently idle in this pool. Returns a negative value if this information is not available.

Returns:int

the total number of instances currently idle in this pool.

getNumIdleback to summary
public int getNumIdle(K key)

Gets the number of instances corresponding to the given key currently idle in this pool. Returns a negative value if this information is not available.

Parameters
key:K

the key to query

Returns:int

the number of instances corresponding to the given key currently idle in this pool.

invalidateObjectback to summary
public void invalidateObject(K key, V obj) throws Exception

Invalidates an object from the pool.

By contract, obj must have been obtained using 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.

This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.

Parameters
key:K

the key used to obtain the object

obj:V

a borrowed instance to be returned.

Exceptions
Exception:
if the instance cannot be invalidated
invalidateObjectback to summary
public default void invalidateObject(final K key, final V obj, final DestroyMode destroyMode) throws Exception

Invalidates an object from the pool, using the provided DestroyMode.

By contract, obj must have been obtained using 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.

This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.

Parameters
key:K

the key used to obtain the object

obj:V

a borrowed instance to be returned.

destroyMode:DestroyMode

destroy activation context provided to the factory

Exceptions
Exception:
if the instance cannot be invalidated
Since
2.9.0
returnObjectback to summary
public void returnObject(K key, V obj) throws Exception

Return an instance to the pool. By contract, obj must have been obtained using 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.

Parameters
key:K

the key used to obtain the object

obj:V

a borrowed instance to be returned.

Exceptions
Exception:
if an instance cannot be returned to the pool
IllegalStateException:
if an attempt is made to return an object to the pool that is in any state other than allocated (i.e. borrowed). Attempting to return an object more than once or attempting to return an object that was never borrowed from the pool will trigger this exception.