de.bb.util

Class Pool

java.lang.Object

de.bb.util.Pool

public class Pool
extends java.lang.Object

Used to manage objects. The managed objects

• must be obtained by key,
• must be released by key,
• can be locked for exclusive use,
• can be validated direct,
• can be validated indirect, by validating the key

.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Pool.Factory Defines the requirements for an object that creates, destroys and validates objects, which are maintained by a Pool.

Constructor Summary

Constructors

Constructor and Description
Pool(Pool.Factory f) Create a Pool object, with a default timeout of 30 mins.
Pool(Pool.Factory f, long keepAlive) Create a Pool object.

Method Summary

Methods

Modifier and Type	Method and Description
int	getMaxCount() Query the max count of objects in this Pool object.
int	getthreshold() Query the current threshold value.
int	lock(java.lang.Object key) Increase the lock count for an object to grant exclusive usage.
int	lockCount(java.lang.Object key) Retrieve the lockCount for a given key.
java.lang.Object	obtain(java.lang.Object key) Obtain an object from the pool.
java.lang.Object	obtain(java.lang.Object key, long timeout) Obtain an object from the pool with a specified max wait time.
void	release(java.lang.Object key, java.lang.Object o) release an object to the pool.
java.lang.Object	renew(java.lang.Object key) Replace the current object by a new object, without changing lock counts.
java.lang.Object	retrieve(java.lang.Object key) Retrieve the object for a given key.
void	setKeepAlive(long keepAlive) Set the timeout for unused objects.
void	setMaxCount(int max) Defines how many objects are maximal maintained.
void	setThreshold(int th) Defines how many unused objects are not destroyed.
int	size() Get total count of objects in this pool.
int	unlock(java.lang.Object key) decrease the lock count for an object.
void	validate() Validate the current pool.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Pool

public Pool(Pool.Factory f)

Create a Pool object, with a default timeout of 30 mins.

Parameters:

f - a Factory to create, validate and destroy the maintained objects.

Pool

public Pool(Pool.Factory f,
    long keepAlive)

Create a Pool object.

Parameters:

f - a Factory to create, validate and destroy the maintained objects.

keepAlive - a timeout after unused object are removed and destroyed.

Method Detail

setThreshold

public void setThreshold(int th)

Defines how many unused objects are not destroyed. Reducing this value does not immediately cause a reduction of the unused objects!

Parameters:

th - set the count of unused objects that are not destroyed

setKeepAlive

public void setKeepAlive(long keepAlive)

Set the timeout for unused objects. Setting this value does not immediately affect the timeouts of already unused objects!

Parameters:

keepAlive - set the count of unused objects that are not destroyed

getthreshold

public int getthreshold()

Query the current threshold value.

Returns:

the current threshold value.

setMaxCount

public void setMaxCount(int max)

Defines how many objects are maximal maintained.

Parameters:

max - set the max count of objects

See Also:

getMaxCount()

getMaxCount

public int getMaxCount()

Query the max count of objects in this Pool object.

Returns:

the max count of objects in this Pool object.

See Also:

setMaxCount(int)

size

public int size()

Get total count of objects in this pool.

Returns:

get the total count of objects in this pool.

obtain

public java.lang.Object obtain(java.lang.Object key)
                        throws java.lang.Exception

Obtain an object from the pool. This function waits infinite! If there is an object associated to the key, that same object is returned.

Parameters:

key - a key, must not be null.

Returns:

an object from the pool.

Throws:

java.lang.Exception - an exception, if an error occurs.

obtain

public java.lang.Object obtain(java.lang.Object key,
                      long timeout)
                        throws java.lang.Exception

Obtain an object from the pool with a specified max wait time. If there is an object associated to the key, that same object is returned.

Parameters:

key - a key, must not be null.

timeout - a timeout for max wait

Returns:

an object from the pool.

Throws:

java.lang.Exception - an exception, if an error occurs.

release

public void release(java.lang.Object key,
           java.lang.Object o)
             throws java.lang.IllegalArgumentException

release an object to the pool.

Parameters:

key - a key, must not be null.

o - the releases object.

Throws:

java.lang.IllegalArgumentException - when the key does not own an object.

retrieve

public java.lang.Object retrieve(java.lang.Object key)

Retrieve the object for a given key.

Parameters:

key - a key Object - not null

Returns:

the object or null

lockCount

public int lockCount(java.lang.Object key)

Retrieve the lockCount for a given key.

Parameters:

key - a key Object - not null

Returns:

the lockCount for a given key

lock

public int lock(java.lang.Object key)
         throws java.lang.IllegalArgumentException

Increase the lock count for an object to grant exclusive usage. As long the lock counter is greater than zero, all obtains with that id will return the same object. Also no other caller may obtain that object.

Parameters:

key - the object attached to this key to lock.

Returns:

returns current lock count.

Throws:

java.lang.IllegalArgumentException - when the key does not own an object.

unlock

public int unlock(java.lang.Object key)
           throws java.lang.IllegalArgumentException

decrease the lock count for an object.

Parameters:

key - the object attached to this key to lock.

Returns:

returns current lock count.

Throws:

java.lang.IllegalArgumentException - when the key does not own an object.

renew

public java.lang.Object renew(java.lang.Object key)
                       throws java.lang.Exception

Replace the current object by a new object, without changing lock counts. The old object gets destroyed, so it MUST be really unusable.

Parameters:

key - the key where the old object is bound.

Returns:

the renewed object

Throws:

java.lang.IllegalArgumentException - when the key does not own an object.

java.lang.Exception - other Exceptions on creation error.

validate

public void validate()

Validate the current pool. All keys are validated. Object attached to invalid keys are destroyed.