org.apache.tephra.distributed

Class ElasticPool<T,E extends Exception>

java.lang.Object

org.apache.tephra.distributed.ElasticPool<T,E>

Type Parameters:

T - the type of the elements

E - the type of exception thrown by create()

public abstract class ElasticPool<T,E extends Exception>
extends Object

An Elastic Pool is an object pool that can dynamically grow. Normally, an element is obtained by a client and then returned to the pool after use. However, if the element gets into a bad state, the element can be discarded, based upon the recycle() method returning false. This will cause the element to be removed from the pool, and for a subsequent request, a new element can be created on the fly to replace the discarded one. The pool starts with zero (active) elements. Every time a client attempts to obtain an element, an element from the pool is returned if available. Otherwise, if the number of active elements is less than the pool's limit, a new element is created (using abstract method create(), this must be overridden by all implementations), and the number of active elements is increased by one. If the limit is reached, then obtain() blocks until either an element is returned to the pool or, if the obtain method with timeout parameters is used, a timeout occurs. Every time an element is returned to the pool, it is "recycled" to restore its fresh state for the next use or destroyed, depending on its state.

Constructor Summary

Constructors

Constructor and Description
ElasticPool(int sizeLimit)

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract T	create() A method to create a new element.
T	obtain() Get a element from the pool.
T	obtain(long timeout, TimeUnit unit) Get a element from the pool.
protected boolean	recycle(T element) A method to recycle an existing element when it is returned to the pool.
void	release(T element) Returns an element to the pool of available elements.

Methods inherited from class java.lang.Object

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

Constructor Detail

ElasticPool

public ElasticPool(int sizeLimit)

Method Detail

create

protected abstract T create()
                     throws E extends Exception

A method to create a new element. Will be called every time the pool of available elements is empty but the limit of active elements is not exceeded.

Returns:

a new element

Throws:

E extends Exception

recycle

protected boolean recycle(T element)

A method to recycle an existing element when it is returned to the pool. This methods ensures that the element is in a fresh state before it can be reused by the next agent. If the element is not to be returned to the pool, calling code is responsible for destroying it and returning false.

Parameters:

element - the element to recycle

Returns:

true to reuse element, false to remove it from the pool

obtain

public T obtain()
         throws E extends Exception,
                InterruptedException

Get a element from the pool. If there is an available element in the pool, it will be returned. Otherwise, if the number of active elements does not exceed the limit, a new element is created with create() and returned. Otherwise, blocks until an element is either released and returned to the pool, or an element is discarded, allowing for the creation of a new element.

Returns:

an element

Throws:

E extends Exception

InterruptedException

obtain

public T obtain(long timeout,
       TimeUnit unit)
         throws E extends Exception,
                TimeoutException,
                InterruptedException

Get a element from the pool. If there is an available element in the pool, it will be returned. Otherwise, if the number of active elements does ot exceed the limit, a new element is created with create() and returned. Otherwise, blocks until an element is either released and returned to the pool, an element is discarded, allowing for the creation of a new element, or a timeout occurs.

Parameters:

timeout - the timeout for trying to obtain an element

unit - the timeout unit for trying to obtain an element

Returns:

an element

Throws:

TimeoutException - if a client is not able to be obtained within the given timeout

E extends Exception

InterruptedException

release

public void release(T element)

Returns an element to the pool of available elements. The element must have been obtained from this pool through obtain(). The recycle() method is called before the element is available for obtain().

Parameters:

element - the element to be returned