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.
See the downloads page for information on obtaining releases.
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
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 PoolableObjectFactory
s used by
1.x pools create and manage pooled objects directly, version 2 PooledObjectFactory
s create and
manage
PooledObject
s. 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 PooledObject
s. To use DefaultPooledObject
wrappers, use
@Override public PooledObject<Foo> wrap(Foo foo) { return new DefaultPooledObject<Foo>(foo); }
Foo
is the type of the objects being pooled (the return type of create()
).
KeyedPooledObjectFactory
defines a similar interface for KeyedObjectPool
s:
public interface KeyedPoolableObjectFactory<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
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
can grow as needed, but allows the garbage collector to evict idle instances from the pool as needed.
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.
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 PooledObjectFactory
s, 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.