net.sf.mmm.util.pool.base
Class AbstractPool<E>

java.lang.Object
  net.sf.mmm.util.pool.base.AbstractPool<E>

Type Parameters:

E - is the generic type of the pooled elements.

All Implemented Interfaces:

Pool<E>

Direct Known Subclasses:

ByteArrayPoolImpl, CharArrayPoolImpl

public abstract class AbstractPool<E>
extends Object
implements Pool<E>

This is the abstract base implementation of the Pool interface.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

static int	DEFAULT_CAPACITY The default capacity used.
private Object	lock The synchronization lock.
private Object[]	pool The buffer representing the pool.
private int	size The actual size (number of elements in pool).

Constructor Summary

	AbstractPool() The constructor.
private	AbstractPool(boolean threadsafe, int capacity, Object lock) The constructor.
	AbstractPool(int capacity, boolean threadsafe) The constructor.
	AbstractPool(int capacity, Object lock) The constructor for a thread-safe pool with an externally given lock for synchronization.

Method Summary

E	borrow() This method borrows an element from this pool.
private E	borrowInternal()
void	clear() This method clears the complete pool.
private void	clearInternal()
protected abstract E	create() This method creates a new element.
int	getCapacity() This method gets the capacity of this pool.
int	getSize() This method gets the size of the pool.
boolean	isEmpty() This method determines if the pool is empty.
void	release(E element) This method releases the given element.
protected boolean	reset(E element) This method resets the given element so it can be reused.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CAPACITY

public static final int DEFAULT_CAPACITY

The default capacity used.

See Also:

Constant Field Values

pool

private final Object[] pool

The buffer representing the pool.

lock

private final Object lock

The synchronization lock.

size

private int size

The actual size (number of elements in pool).

Constructor Detail

AbstractPool

public AbstractPool()

The constructor. ATTENTION:
This constructor uses a default capacity of 16. A suitable default capacity depends on the type of objects that are pooled ( <E>).

AbstractPool

public AbstractPool(int capacity,
                    boolean threadsafe)

The constructor.

Parameters:

capacity - is the capacity.

threadsafe - if true the pool needs to be accessed by multiple Threads concurrently, false otherwise.

AbstractPool

public AbstractPool(int capacity,
                    Object lock)

The constructor for a thread-safe pool with an externally given lock for synchronization.

Parameters:

capacity - is the capacity.

lock - is an object used for synchronization.

AbstractPool

private AbstractPool(boolean threadsafe,
                     int capacity,
                     Object lock)

The constructor.

Parameters:

threadsafe - if true the pool needs to be accessed by multiple Threads concurrently, false otherwise.

capacity - the capacity of this pool.

lock - is an explicit synchronization-lock object. It may be null. If it is NOT null, threadsafe has to be true.

Method Detail

borrow

public E borrow()

This method borrows an element from this pool. If you do NOT need the object anymore you should release it.
If this pool is empty, a new instance is created for you. Otherwise a existing instance (that has been released before) will be returned so it can be reused.

Specified by:

borrow in interface Pool<E>

Returns:

an element from the pool. Typically this method never returns null. This may only happen if explicitly documented by the chosen implementation.

borrowInternal

private E borrowInternal()

Returns:

the borrowed object.

See Also:

borrow()

create

protected abstract E create()

This method creates a new element. It is used if there is no instance left in the pool.

Returns:

the new instance.

reset

protected boolean reset(E element)

This method resets the given element so it can be reused. It is called if an element is released and will be stored in the pool. The implementation depends on the type of element. Some types may become inconsistent if they are directly reused. Further this method may clear data from the element for security reasons, because the same instance may be given to some other component that is NOT trusted enough (because it may be vulnerably).

Parameters:

element - the element to reset.

Returns:

true if the given element can be reused and should be added to the pool, false otherwise.

isEmpty

public boolean isEmpty()

This method determines if the pool is empty.

Specified by:

isEmpty in interface Pool<E>

Returns:

true if the pool is empty.

See Also:

Collection.isEmpty()

getSize

public int getSize()

This method gets the size of the pool.

Returns:

the size

getCapacity

public int getCapacity()

This method gets the capacity of this pool. This value is the maximum size of this pool. If that size is reached further released objects are NOT pooled and can be freed by the garbage-collector.
ATTENTION:
The optimal capacity of a Pool depends heavily on the type of objects that are pooled. For some lightweight objects a very high capacity may suite. However for big buffers (e.g. char[65536]) the capacity should be very low because otherwise your heap might get crowded.

Returns:

the capacity of the pool.

release

public void release(E element)

This method releases the given element. It will be put back into the pool.
ATTENTION:
Only call this method if you are sure that the given element is NOT in use anymore. Therefore no reference should exist on the element and you should NOT have passed the element to a third-party library that may keep it in some cache.

Specified by:

release in interface Pool<E>

Parameters:

element - is the element to add to the pool.

See Also:

Collection.add(Object)

clear

public void clear()

This method clears the complete pool. After the call of this method, the pool will be empty.

clearInternal

private void clearInternal()

See Also:

clear()