src/site/xdoc/index.xml (154 lines of code) (raw):
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>
<properties>
<title>Overview</title>
<author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
<revision>$Id$</revision>
</properties>
<body>
<section name="Apache Commons Pool">
<p>
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.
</p>
<ul>
<li>Version 3.0.0 and up requires Java 8 or above.</li>
<li>Version 2.7.x and up requires Java 8 or above.</li>
<li>Version 2.6.x requires Java 7 or above.</li>
<li>Version 2.5.x requires Java 7 or above.</li>
<li>Version 2.0 requires 6 or above.</li>
</ul>
</section>
<section name="Releases">
<p>
See the <a href="downloads.html">downloads</a> page for information
on obtaining releases.
</p>
</section>
<section name="Features">
<p>
The
<a href="./apidocs/org/apache/commons/pool2/package-summary.html">org.apache.commons.pool3</a>
package defines a handful of pooling interfaces and some base classes
that may be useful when creating new pool implementations.
</p>
<subsection name="PooledObjectFactory">
<p>
<a href="./apidocs/org/apache/commons/pool2/PooledObjectFactory.html"><code>PooledObjectFactory</code></a>
provides a generic interface for managing the lifecycle of a pooled object:
</p>
<source>
public interface PooledObjectFactory<T> {
activateObject(PooledObject<T>)
destroyObject(PooledObject<T>)
destroyObject(PooledObject<T>, DestroyMode)
makeObject()
passivateObject(PooledObject<T>)
validateObject(PooledObject<T>)
}
</source>
<p>
Users of 1.x versions of Commons Pool will notice that while the <code>PoolableObjectFactory</code>s used by
1.x pools create and manage pooled objects directly, version 2 <code>PooledObjectFactory</code>s create and
manage
<a href="./apidocs/org/apache/commons/pool2/PooledObject"><code>PooledObject</code></a>s. These object wrappers
maintain object pooling state, enabling <code>PooledObjectFactory</code> methods to have access to data such
as instance creation time or time of last use. A
<a href="./apidocs/org/apache/commons/pool2/impl/DefaultPooledObject"><code>DefaultPooledObject</code></a> is
provided, with natural implementations for pooling state methods. The simplest way to implement a
<code>PoolableObjectFactory</code> is to have it extend
<a href="./apidocs/org/apache/commons/pool2/BasePooledObjectFactory.html"><code>BasePooledObjectFactory</code></a>.
This factory provides a <code>makeObject()</code> that returns <code>wrap(create())</code>
where <code>create</code> and <code>wrap</code> are abstract. You provide an implementation of <code>create</code>
to create the underlying objects that you want to manage in the pool and <code>wrap</code> to wrap created
instances in <code>PooledObject</code>s. To use <code>DefaultPooledObject</code> wrappers, use
<source>
@Override
public PooledObject<Foo> wrap(Foo foo) {
return new DefaultPooledObject<Foo>(foo);
}
</source>
where <code>Foo</code> is the type of the objects being pooled (the return type of <code>create()</code>).
</p>
<p>
<a href="./apidocs/org/apache/commons/pool2/KeyedPooledObjectFactory.html"><code>KeyedPooledObjectFactory</code></a>
defines a similar interface for <code>KeyedObjectPool</code>s:
</p>
<source>
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);
}
</source>
<p>
<a href="./apidocs/org/apache/commons/pool2/BaseKeyedPooledObjectFactory.html"><code>BaseKeyedPooledObjectFactory</code></a>
provides an abstract base implementation of <code>KeyedPooledObjectFactory</code>.
</p>
</subsection>
<p>
The
<a href="./apidocs/org/apache/commons/pool2/impl/package-summary.html">org.apache.commons.pool3.impl</a>
package provides some <i>Pool</i> implementations.
</p>
<subsection name="GenericObjectPool">
<p>
<a href="./apidocs/org/apache/commons/pool2/impl/GenericObjectPool.html"><code>GenericObjectPool</code></a>
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, <code>GenericObjectPool</code>
also provides abandoned instance tracking and removal.
</p>
<p>
<a href="./apidocs/org/apache/commons/pool2/impl/GenericKeyedObjectPool.html"><code>GenericKeyedObjectPool</code></a>
offers the same behavior for keyed pools.
</p>
</subsection>
<subsection name="SoftReferenceObjectPool">
<p>
<a href="./apidocs/org/apache/commons/pool2/impl/SoftReferenceObjectPool.html"><code>SoftReferenceObjectPool</code></a>
can grow as needed, but allows the garbage collector to evict idle instances from the pool as needed.
</p>
</subsection>
</section>
<section name="Migrating from Pool 2.x to Pool 2.y">
<p>
Client code that uses a Pool 2.x release should require no code
changes to work with a later Pool 2.x release.
</p>
<p>
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
<a href="./apidocs/org/apache/commons/pool2/impl/DefaultPooledObjectInfoMBean.html"><code>DefaultPooledObjectInfoMBean</code></a>,
<a href="./apidocs/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMXBean.html"><code>GenericKeyedObjectPoolMXBean</code></a> or
<a href="./apidocs/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMXBean.html"><code>GenericKeyedObjectPoolMXBean</code></a>
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.
</p>
</section>
<section name="Migrating from Pool 1.x to Pool 2.x">
<p>
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 <code>org.apache.commons.pool</code> to
<code>org.apache.commons.pool3</code> and the change in the implementation
classes to use <code>PooledObjectFactory</code>s, as described above.
</p>
<p>
The key implementation classes (<code>GenericObjectPool</code> and
<code>GenericKeyedObjectPool</code>) 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.
</p>
</section>
</body>
</document>