<?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 2.10.x requires Java 8 or above.</li>
          <li>Version 2.9.x requires Java 8 or above.</li>
          <li>Version 2.8.x requires Java 8 or above.</li>
          <li>Version 2.7.x 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.pool2</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&lt;T&gt; {
    PooledObject&lt;T&gt; makeObject();
    void activateObject(PooledObject&lt;T&gt; obj);
    void passivateObject(PooledObject&lt;T&gt; obj);
    boolean validateObject(PooledObject&lt;T&gt; obj);
    void destroyObject(PooledObject&lt;T&gt; obj);
}
</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&lt;Foo&gt; wrap(Foo foo) {
    return new DefaultPooledObject&lt;Foo&gt;(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 KeyedPoolableObjectFactory&lt;K,V&gt; {
    PooledObject&lt;V&gt; makeObject(K key);
    void activateObject(K key, PooledObject&lt;V&gt; obj);
    void passivateObject(K key, PooledObject&lt;V&gt; obj);
    boolean validateObject(K key, PooledObject&lt;V&gt; obj);
    void destroyObject(K key, PooledObject&lt;V&gt; 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.pool2.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.pool2</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>
