K
- The type of keys maintained by this pool.V
- Type of element pooled in this pool.public interface KeyedObjectPool<K,V> extends Closeable
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.
KeyedPooledObjectFactory
,
ObjectPool
,
GenericKeyedObjectPool
Modifier and Type | Method and Description |
---|---|
void |
addObject(K key)
Create an object using the
factory or
other implementation dependent mechanism, passivate it, and then place it
in the idle object pool. |
default void |
addObjects(Collection<K> keys,
int count)
|
default void |
addObjects(K key,
int count)
|
V |
borrowObject(K key)
Obtains an instance from this pool for the specified
key . |
void |
clear()
Clears the pool, removing all pooled instances (optional operation).
|
void |
clear(K key)
Clears the specified pool, removing all pooled instances corresponding to
the given
key (optional operation). |
void |
close()
Close this pool, and free any resources associated with it.
|
int |
getNumActive()
Returns the total number of instances currently borrowed from this pool but
not yet returned.
|
int |
getNumActive(K key)
Returns the number of instances currently borrowed from but not yet
returned to the pool corresponding to the given
key . |
int |
getNumIdle()
Returns the total number of instances currently idle in this pool.
|
int |
getNumIdle(K key)
Returns the number of instances corresponding to the given
key currently idle in this pool. |
void |
invalidateObject(K key,
V obj)
Invalidates an object from the pool.
|
void |
returnObject(K key,
V obj)
Return an instance to the pool.
|
void addObject(K key) throws Exception, IllegalStateException, UnsupportedOperationException
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).key
- the key a new instance should be added toException
- when KeyedPooledObjectFactory.makeObject(K)
fails.IllegalStateException
- after close()
has been called on this pool.UnsupportedOperationException
- when this pool cannot add new idle objects.default void addObjects(Collection<K> keys, int count) throws Exception, IllegalArgumentException
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.keys
- Collection
of keys to add objects for.count
- the number of idle objects to add for each key
.Exception
- when addObject(Object)
fails.IllegalArgumentException
- when keyedPool
, keys
, or any value
in keys
is null
.addObjects(Object, int)
default void addObjects(K key, int count) throws Exception, IllegalArgumentException
key
- the key to add objects for.count
- the number of idle objects to add for key
.Exception
- when addObject(Object)
fails.IllegalArgumentException
- when key
is null
.V borrowObject(K key) throws Exception, NoSuchElementException, IllegalStateException
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 behaviour of this method when the pool has been exhausted is not strictly specified (although it may be specified by implementations).
key
- the key used to obtain the objectIllegalStateException
- after close
has been called on this poolException
- when makeObject
throws an exceptionNoSuchElementException
- when the pool is exhausted and cannot or will not return
another instancevoid clear() throws Exception, UnsupportedOperationException
UnsupportedOperationException
- when this implementation doesn't
support the operationException
- if the pool cannot be clearedvoid clear(K key) throws Exception, UnsupportedOperationException
key
(optional operation).key
- the key to clearUnsupportedOperationException
- when this implementation doesn't
support the operationException
- if the key cannot be clearedvoid close()
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.
close
in interface AutoCloseable
close
in interface Closeable
int getNumActive()
int getNumActive(K key)
key
.
Returns a negative value if this information is not available.key
- the key to querykey
.int getNumIdle()
int getNumIdle(K key)
key
currently idle in this pool. Returns a negative value if
this information is not available.key
- the key to querykey
currently idle in this pool.void invalidateObject(K key, V obj) throws Exception
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.
void returnObject(K key, V obj) throws Exception
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.key
- the key used to obtain the objectobj
- a borrowed
instance to be returned.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.Exception
- if an instance cannot be returned to the poolCopyright © 2020. All rights reserved.