<?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">Commons Documentation Team</author>
      <author email="rwaldhoff@apache.org">Rodney Waldhoff</author>
      <revision>$Id: index.xml 1221705 2011-12-21 13:03:54Z ggregory $</revision>
   </properties>

   <body>
      <section name="The Pool Component">
         <p>
          Pool provides an Object-pooling API, with three major aspects:
          <ol>
           <li>
            A generic object pool interface that clients and implementors can use to provide easily 
            interchangable pooling implementations.
           </li>
           <li>
            A toolkit for creating modular object pools.
           </li>
           <li>
            Several general purpose pool implementations.
           </li>
          </ol>
         </p>
      </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/pool/package-summary.html">org.apache.commons.pool</a> 
            package defines a handful of pooling interfaces and some base classes 
            that may be useful when creating new pool implementations.
        </p>
        <subsection name="ObjectPool">
          <p>
             <a href="./apidocs/org/apache/commons/pool/ObjectPool.html"><code>ObjectPool</code></a>
             defines a trivially simple pooling interface:
          </p>
<source>
public interface ObjectPool&lt;T&gt; {
    T borrowObject();
    void returnObject(T borrowed);
}
</source>           
          <p>
            Some client classes won't integrate with <i>Pool</i> any more than this.
            Clients written to this interface can use arbitrary <code>ObjectPool</code> 
            implementations interchangeably. 
          </p>           
          <p>
             <a href="./apidocs/org/apache/commons/pool/BaseObjectPool.html"><code>BaseObjectPool</code></a>
             provides an abstract base implementation of <code>ObjectPool</code>. Clients are
             encouraged but not required to extend <code>BaseObjectPool</code> for new 
             <code>ObjectPool</code> implementations.
          </p>
          <p>
             <a href="./apidocs/org/apache/commons/pool/KeyedObjectPool.html"><code>KeyedObjectPool</code></a>
             defines a similar interface for pools composed of heterogeneous objects:
          </p>
<source>
public interface KeyedObjectPool&lt;K, V&gt; {
    V borrowObject(K key);
    void returnObject(K key, V borrowed);
}
</source>           
        </subsection>
        <subsection name="PoolableObjectFactory">
          <p>
             The <i>Pool</i> package makes it possible separate the way in which instances
             are pooled from the way in which instances are created and destroyed. 
             <a href="./apidocs/org/apache/commons/pool/PoolableObjectFactory.html"><code>PoolableObjectFactory</code></a>
             supports this by providing a generic interface for the lifecycle of a pooled object:
          </p>
<source>
public interface PoolableObjectFactory&lt;T&gt; {
    T makeObject();
    void activateObject(T obj);
    void passivateObject(T obj);
    boolean validateObject(T obj);
    void destroyObject(T obj);
}
</source>           
          <p>
             <code>ObjectPool</code> implementations may be written to accept arbitrary
             <code>PoolableObjectFactory</code>s.
             This makes is possible for clients to select pooling-behavior distinct 
             from the kinds of objects that are pooled.  
          </p>           
          <p>
             <a href="./apidocs/org/apache/commons/pool/BasePoolableObjectFactory.html"><code>BasePoolableObjectFactory</code></a>
             provides an abstract base implementation of <code>PoolableObjectFactory</code> that
             makes implementations a snap.
          </p>
          <p>
             <a href="./apidocs/org/apache/commons/pool/KeyedPoolableObjectFactory.html"><code>KeyedPoolableObjectFactory</code></a>
             defines a similar interface for <code>KeyedObjectPool</code>s:
          </p>
<source>
public interface KeyedPoolableObjectFactory&lt;K, V&gt; {
    V makeObject(K key);
    void activateObject(K key, V obj);
    void passivateObject(K key, V obj);
    boolean validateObject(K key, V obj);
    void destroyObject(K key, V obj);
}
</source>           
          <p>
             <a href="./apidocs/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.html"><code>BaseKeyedPoolableObjectFactory</code></a>
             provides an abstract base implementation of <code>KeyedPoolableObjectFactory</code> that
             makes implementations a snap.
          </p>
        </subsection>
        <p>
            The 
            <a href="./apidocs/org/apache/commons/pool/impl/package-summary.html">org.apache.commons.pool.impl</a> 
            package provides some <i>Pool</i> implementations.
        </p>
        <subsection name="StackObjectPool">
          <p>
             <a href="./apidocs/org/apache/commons/pool/impl/StackObjectPool.html"><code>StackObjectPool</code></a>
             will pool a finite number of "idle" instances, but will create new instances a needed in 
             order to support high demand.
          </p>
          <p>
             <a href="./apidocs/org/apache/commons/pool/impl/StackKeyedObjectPool.html"><code>StackKeyedObjectPool</code></a>
             offers the same behavior for keyed pools.
          </p>
        </subsection>
        <subsection name="GenericObjectPool">
          <p>
             <a href="./apidocs/org/apache/commons/pool/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.
          </p>
          <p>
             <a href="./apidocs/org/apache/commons/pool/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/pool/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>
   </body>
</document>
