Pool – Overview

Apache Commons Pool

The Apache Commons Pool open source software library provides an object-pooling API and a number of object pool implementations. Version 2 of Apache Commons Pool contains a completely re-written pooling implementation compared to the 1.x series. In addition to performance and scalability improvements, version 2 includes robust instance tracking and pool monitoring.

Version 2.7.x and up requires Java 8 or above.
Version 2.6.x requires Java 7 or above.
Version 2.5.x requires Java 7 or above.
Version 2.0 requires 6 or above.

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.

PooledObjectFactory

PooledObjectFactory provides a generic interface for managing the lifecycle of a pooled object:

public interface PooledObjectFactory<T> {
    activateObject(PooledObject<T>)
    destroyObject(PooledObject<T>)
    destroyObject(PooledObject<T>, DestroyMode)
    makeObject()
    passivateObject(PooledObject<T>)
    validateObject(PooledObject<T>)
}

Users of 1.x versions of Commons Pool will notice that while the PoolableObjectFactorys used by 1.x pools create and manage pooled objects directly, version 2 PooledObjectFactorys create and manage PooledObjects. These object wrappers maintain object pooling state, enabling PooledObjectFactory methods to have access to data such as instance creation time or time of last use. A DefaultPooledObject is provided, with natural implementations for pooling state methods. The simplest way to implement a PoolableObjectFactory is to have it extend BasePooledObjectFactory. This factory provides a makeObject() that returns wrap(create()) where create and wrap are abstract. You provide an implementation of create to create the underlying objects that you want to manage in the pool and wrap to wrap created instances in PooledObjects. To use DefaultPooledObject wrappers, use

@Override
 public PooledObject<Foo> wrap(Foo foo) {
    return new DefaultPooledObject<Foo>(foo);
 }

where Foo is the type of the objects being pooled (the return type of create()).

KeyedPooledObjectFactory defines a similar interface for KeyedObjectPools:

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

BaseKeyedPooledObjectFactory provides an abstract base implementation of KeyedPooledObjectFactory.

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. As of version 2, GenericObjectPool also provides abandoned instance tracking and removal.

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.

Migrating from Pool 2.x to Pool 2.y

Client code that uses a Pool 2.x release should require no code changes to work with a later Pool 2.x release.

New Pool 2.x releases may include support for new configuration attributes. These will be listed in the change log. Note that the MBean interfaces (those with names ending in MXBean or MBean) such as DefaultPooledObjectInfoMBean, GenericKeyedObjectPoolMXBean or GenericKeyedObjectPoolMXBean may change from one release to the next to support these new attributes. These interfaces should, therefore, not be implemented by client as the changes will not be backwards compatible.

Migrating from Pool 1.x to Pool 2.x

The migration from Apache Commons Pool 1.x to 2.x will require some code changes. The most significant changes are the changes in package name from org.apache.commons.pool to org.apache.commons.pool2 and the change in the implementation classes to use PooledObjectFactorys, as described above.

The key implementation classes (GenericObjectPool and GenericKeyedObjectPool) have retained their names so no changes should be required there although a number of attributes have been renamed to improve consistency and ensure attributes with the same name in different pools have the same meaning. It is likely that some changes will be required to use the new attribute names.