org.apache.commons.pool
Interface KeyedObjectPool
- BaseKeyedObjectPool, GenericKeyedObjectPool, StackKeyedObjectPool
public interface KeyedObjectPool
A "keyed" pooling interface.
A keyed pool pools instances of multiple types. Each
type may be accessed using an arbitrary key.
Example of use:
Object obj = null;
Object key = "Key";
try {
obj = pool.borrowObject(key);
//...use the object...
} catch(Exception e) {
//...handle any exceptions...
} 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
).
$Revision: 155430 $ $Date: 2005-02-26 08:13:28 -0500 (Sat, 26 Feb 2005) $ void | addObject(Object key) - Create an object using my
factory or other
implementation dependent mechanism, and place it into the pool.
|
Object | borrowObject(Object key) - Obtain an instance from my pool
for the specified key.
|
void | clear() - Clears my pool, removing all pooled instances
(optional operation).
|
void | clear(Object 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
current borrowed from my pool but not
yet returned (optional operation).
|
int | getNumActive(Object key) - Returns the number of instances
currently borrowed from but not yet returned
to my pool corresponding to the
given key (optional operation).
|
int | getNumIdle() - Returns the total number of instances
currently idle in my pool (optional operation).
|
int | getNumIdle(Object key) - Returns the number of instances
corresponding to the given key
currently idle in my pool (optional operation).
|
void | invalidateObject(Object key, Object obj) - 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.
|
void | returnObject(Object key, Object obj) - Return an instance to my pool.
|
void | setFactory(KeyedPoolableObjectFactory factory) - Sets the
factory I use
to create new instances (optional operation).
|
addObject
public void addObject(Object key)
throws Exception
Create an object using my
factory
or other
implementation dependent mechanism, and place it into the pool.
addObject() is useful for "pre-loading" a pool with idle objects.
(Optional operation).
borrowObject
public Object borrowObject(Object key)
throws Exception
Obtain an instance from my pool
for the specified key.
By contract, clients MUST return
the borrowed object using
returnObject
,
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 object
- an instance from my pool.
clear
public void clear()
throws Exception,
UnsupportedOperationException
Clears my pool, removing all pooled instances
(optional operation).
Throws UnsupportedOperationException
if the pool cannot be cleared.
clear
public void clear(Object key)
throws Exception,
UnsupportedOperationException
Clears the specified pool, removing all
pooled instances corresponding to
the given key (optional operation).
Throws UnsupportedOperationException
if the pool cannot be cleared.
close
public void close()
throws Exception
Close this pool, and free any resources associated with it.
getNumActive
public int getNumActive()
throws UnsupportedOperationException
Returns the total number of instances
current borrowed from my pool but not
yet returned (optional operation).
Throws UnsupportedOperationException
if this information is not available.
- the total number of instances currently borrowed from my pool
getNumActive
public int getNumActive(Object key)
throws UnsupportedOperationException
Returns the number of instances
currently borrowed from but not yet returned
to my pool corresponding to the
given key (optional operation).
Throws UnsupportedOperationException
if this information is not available.
- the number of instances corresponding to the given key currently borrowed in my pool
getNumIdle
public int getNumIdle()
throws UnsupportedOperationException
Returns the total number of instances
currently idle in my pool (optional operation).
Throws UnsupportedOperationException
if this information is not available.
- the total number of instances currently idle in my pool
getNumIdle
public int getNumIdle(Object key)
throws UnsupportedOperationException
Returns the number of instances
corresponding to the given key
currently idle in my pool (optional operation).
Throws UnsupportedOperationException
if this information is not available.
- the number of instances corresponding to the given key currently idle in my pool
invalidateObject
public void invalidateObject(Object key,
Object 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.
If the connection should be validated before or after borrowing,
then the
PoolableObjectFactory.validateObject(Object)
method should be
used instead.
obj
- a borrowed
instance to be returned.
returnObject
public void returnObject(Object key,
Object obj)
throws Exception
Return an instance to my 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.
key
- the key used to obtain the objectobj
- a borrowed
instance to be returned.
setFactory
public void setFactory(KeyedPoolableObjectFactory factory)
throws IllegalStateException,
UnsupportedOperationException
Sets the
factory
I use
to create new instances (optional operation).
Copyright © 2001-2003 Apache Software Foundation. Documenation generated October 14 2006.