The Pool Component

Pool provides an Object-pooling API, with three major aspects:

  1. A generic object pool interface that clients and implementors can use to provide easily interchangeable pooling implementations.
  2. A toolkit for creating modular object pools.
  3. Several general purpose pool implementations.

Releases

See the downloads page for information on obtaining releases.

Features

The org.apache.commons.pool2 package defines a handful of pooling interfaces and some base classes that may be useful when creating new pool implementations.

ObjectPool

ObjectPool defines a trivially simple pooling interface:

public interface ObjectPool<T> {
    T borrowObject();
    void returnObject(T borrowed);
}

Some client classes won't integrate with Pool any more than this. Clients written to this interface can use arbitrary ObjectPool implementations interchangeably.

BaseObjectPool provides an abstract base implementation of ObjectPool. Clients are encouraged but not required to extend BaseObjectPool for new ObjectPool implementations.

KeyedObjectPool defines a similar interface for pools composed of heterogeneous objects:

public interface KeyedObjectPool<K,V> {
    V borrowObject(K key);
    void returnObject(K key, V borrowed);
}

PoolableObjectFactory

The Pool package makes it possible separate the way in which instances are pooled from the way in which instances are created and destroyed. PoolableObjectFactory supports this by providing a generic interface for the lifecycle of a pooled object:

public interface PoolableObjectFactory<T> {
    T makeObject();
    void activateObject(T obj);
    void passivateObject(T obj);
    boolean validateObject(T obj);
    void destroyObject(T obj);
}

ObjectPool implementations may be written to accept arbitrary PoolableObjectFactorys. This makes is possible for clients to select pooling-behavior distinct from the kinds of objects that are pooled.

BasePoolableObjectFactory provides an abstract base implementation of PoolableObjectFactory that makes implementations a snap.

KeyedPoolableObjectFactory defines a similar interface for KeyedObjectPools:

public interface KeyedPoolableObjectFactory<K,V> {
    V makeObject(K key);
    void activateObject(K key, V obj);
    void passivateObject(K key, V obj);
    boolean validateObject(K key, V obj);
    void destroyObject(K key, V obj);
}

BaseKeyedPoolableObjectFactory provides an abstract base implementation of KeyedPoolableObjectFactory that makes implementations a snap.

The org.apache.commons.pool2.impl package provides some Pool implementations.

GenericObjectPool

GenericObjectPool provides a wide variety of configuration options, including the ability to cap the number of idle or active instances, to evict instances as they sit idle in the pool, etc.

GenericKeyedObjectPool offers the same behavior for keyed pools.

SoftReferenceObjectPool

SoftReferenceObjectPool can grow as needed, but allows the garbage collector to evict idle instances from the pool as needed.