AbstractPool (JavaDocs for mmm-all dev-SNAPSHOT)

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

Fields
Modifier and Type	Field and Description
`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

Constructors
Modifier	Constructor and Description
	`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

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`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()
```
    Description copied from interface: Pool
    
    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()
```
    Description copied from interface: Pool
    
    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)
```
    Description copied from interface: Pool
    
    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()

Class AbstractPool<E>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_CAPACITY

pool

lock

size

Constructor Detail

AbstractPool

AbstractPool

AbstractPool

AbstractPool

Method Detail

borrow

borrowInternal

create

reset

isEmpty

getSize

getCapacity

release

clear

clearInternal