Commons

Home

Information

Project Files

About Us

Jakarta Community

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 interchangable pooling implementations.
  2. A toolkit for creating modular object pools.
  3. Several general purpose pool implementations.

See the downloads page for information on obtaining releases.


Features

The org.apache.commons.pool 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 {
    Object borrowObject();
    void returnObject(Object 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 similiar interface for pools composed of heterogenous objects:

public interface KeyedObjectPool {
    Object borrowObject(Object key);
    void returnObject(Object key, Object 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 inteface for the lifecycle of a pooled object:

public interface PoolableObjectFactory {
    Object makeObject();
    void activateObject(Object obj);
    void passivateObject(Object obj);
    boolean validateObject(Object obj);
    void destroyObject(Object 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 similiar interface for KeyedObjectPools:

public interface KeyedPoolableObjectFactory {
    Object makeObject(Object key);
    void activateObject(Object key, Object obj);
    void passivateObject(Object key, Object obj);
    boolean validateObject(Object key, Object obj);
    void destroyObject(Object key, Object obj);
}

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


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

StackObjectPool

StackObjectPool will pool a finite number of "idle" instances, but will create new instances a needed in order to support high demand.

StackKeyedObjectPool offers the same behavior for keyed pools.


GenericObjectPool

GenericObjectPool provides a wide variety of configuration options, including the ablity 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.




Copyright © 1999-2003, Apache Software Foundation