Overview – Apache Commons Pool

<!DOCTYPE html>  <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="author" content="Apache Commons Documentation Team" /> <title>Overview – Apache Commons Pool</title> <link rel="stylesheet" href="./css/bootstrap.min.css" type="text/css" /> <link rel="stylesheet" href="./css/site.css" type="text/css" /> <link rel="stylesheet" href="./css/print.css" media="print" /> <script type="text/javascript" src="./js/jquery.min.js"></script> <script type="text/javascript" src="./js/bootstrap.min.js"></script> <script type="text/javascript" src="./js/prettify.min.js"></script> <script type="text/javascript" src="./js/site.js"></script> </head> <body class="composite"> <a href="https://commons.apache.org/" id="bannerLeft"> <img class="logo-left" src=" ./images/commons-logo.png " alt="Apache Commons logo"/> </a> <a href="index.html" id="bannerRight"> <img class="logo-right" src=" images/logo.png " alt="Commons Pool"/> </a> <div class="clear"></div> <div class="navbar"> <div class="navbar-inner"> <div class="container-fluid"> <a class="brand" href="https://commons.apache.org/proper/commons-pool/">Apache Commons Pool ™</a> <ul class="nav"> <li id="publishDate">Last Published: 27 Jan 2025</li> <li class="divider">|</li> <li id="projectVersion">Version: 2.12.2-SNAPSHOT</li> </ul> <div class="pull-right"> <ul class="nav"> <li> <a href="https://www.apachecon.com/" class="externalLink" title="ApacheCon"> ApacheCon</a> </li> <li> <a href="https://www.apache.org" class="externalLink" title="Apache"> Apache</a> </li> <li> <a href="../../" title="Commons"> Commons</a> </li> </ul> </div> </div> </div> </div> <div class="container-fluid"> <table class="layout-table"> <tr> <td class="sidebar"> <div class="well sidebar-nav"> <ul class="nav nav-list"> <li class="nav-header">Commons Pool</li> <li class="none active"> <a href="index.html" title="About"> About</a> </li> <li class="none"> <a href="mail-lists.html" title="Asking Questions"> Asking Questions</a> </li> <li class="none"> <a href="changes.html" title="Release History"> Release History</a> </li> <li class="none"> <a href="issue-management.html" title="Issue Tracking"> Issue Tracking</a> </li> <li class="none"> <a href="dependency-info.html" title="Dependency Management"> Dependency Management</a> </li> <li class="none"> <a href="apidocs/index.html" title="Javadoc"> Javadoc</a> </li> <li class="none"> <a href="https://javadoc.io/doc/org.apache.commons/commons-pool2/" class="externalLink" title="Javadoc Archive 2.x"> Javadoc Archive 2.x</a> </li> <li class="none"> <a href="https://javadoc.io/doc/commons-pool/commons-pool/" class="externalLink" title="Javadoc Archive 1.x"> Javadoc Archive 1.x</a> </li> <li class="none"> <a href="scm.html" title="Sources"> Sources</a> </li> <li class="none"> <a href="security.html" title="Security"> Security</a> </li> <li class="none"> <a href="https://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="License"> License</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/policies/conduct.html" class="externalLink" title="Code of Conduct"> Code of Conduct</a> </li> <li class="none"> <a href="download_pool.cgi" title="Download"> Download</a> </li> <li class="none"> <a href="examples.html" title="Examples"> Examples</a> </li> </ul> <ul class="nav nav-list"> <li class="nav-header">Project Documentation</li> <li class="expanded"> <a href="project-info.html" title="Project Information"> Project Information</a> <ul> <li class="none active"> <a href="index.html" title="About"> About</a> </li> <li class="none"> <a href="summary.html" title="Summary"> Summary</a> </li> <li class="none"> <a href="team.html" title="Team"> Team</a> </li> <li class="none"> <a href="scm.html" title="Source Code Management"> Source Code Management</a> </li> <li class="none"> <a href="issue-management.html" title="Issue Management"> Issue Management</a> </li> <li class="none"> <a href="mailing-lists.html" title="Mailing Lists"> Mailing Lists</a> </li> <li class="none"> <a href="dependency-info.html" title="Maven Coordinates"> Maven Coordinates</a> </li> <li class="none"> <a href="dependency-management.html" title="Dependency Management"> Dependency Management</a> </li> <li class="none"> <a href="dependencies.html" title="Dependencies"> Dependencies</a> </li> <li class="none"> <a href="dependency-convergence.html" title="Dependency Convergence"> Dependency Convergence</a> </li> <li class="none"> <a href="ci-management.html" title="CI Management"> CI Management</a> </li> <li class="none"> <a href="distribution-management.html" title="Distribution Management"> Distribution Management</a> </li> </ul> </li> <li class="collapsed"> <a href="project-reports.html" title="Project Reports"> Project Reports</a> </li> </ul> <ul class="nav nav-list"> <li class="nav-header">Commons</li> <li class="none"> <a href="../../" title="Home"> Home</a> </li> <li class="none"> <a href="https://www.apache.org/licenses/" class="externalLink" title="License"> License</a> </li> <li class="collapsed"> <a href="../../components.html" title="Components"> Components</a> </li> <li class="collapsed"> <a href="../../sandbox/index.html" title="Sandbox"> Sandbox</a> </li> <li class="collapsed"> <a href="../../dormant/index.html" title="Dormant"> Dormant</a> </li> </ul> <ul class="nav nav-list"> <li class="nav-header">General Information</li> <li class="none"> <a href="../../security.html" title="Security"> Security</a> </li> <li class="none"> <a href="../../volunteering.html" title="Volunteering"> Volunteering</a> </li> <li class="none"> <a href="../../patches.html" title="Contributing Patches"> Contributing Patches</a> </li> <li class="none"> <a href="../../building.html" title="Building Components"> Building Components</a> </li> <li class="none"> <a href="../../commons-parent-pom.html" title="Commons Parent POM"> Commons Parent POM</a> </li> <li class="none"> <a href="../../build-plugin/index.html" title="Commons Build Plugin"> Commons Build Plugin</a> </li> <li class="none"> <a href="../../release-plugin/index.html" title="Commons Release Plugin"> Commons Release Plugin</a> </li> <li class="none"> <a href="../../site-publish.html" title="Site Publication"> Site Publication</a> </li> <li class="none"> <a href="../../releases/index.html" title="Releasing Components"> Releasing Components</a> </li> <li class="none"> <a href="https://cwiki.apache.org/confluence/display/commons/FrontPage" class="externalLink" title="Wiki"> Wiki</a> </li> </ul> <ul class="nav nav-list"> <li class="nav-header">ASF</li> <li class="none"> <a href="https://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works"> How the ASF works</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/getinvolved.html" class="externalLink" title="Get Involved"> Get Involved</a> </li> <li class="none"> <a href="https://www.apache.org/dev/" class="externalLink" title="Developer Resources"> Developer Resources</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/policies/conduct.html" class="externalLink" title="Code of Conduct"> Code of Conduct</a> </li> <li class="none"> <a href="https://privacy.apache.org/policies/privacy-policy-public.html" class="externalLink" title="Privacy"> Privacy</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"> Sponsorship</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"> Thanks</a> </li> </ul> </div> <div id="poweredBy"> <a href="https://www.apache.org/events/current-event.html" title="ApacheCon" class="builtBy"> <img class="builtBy" alt="ApacheCon" src="https://www.apache.org/events/current-event-125x125.png" /> </a> <a href="https://maven.apache.org/" title="Maven" class="builtBy"> <img class="builtBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png" /> </a> </div> </td> <td class="content"> <section><a id="Apache_Commons_Pool"></a> <h1>Apache Commons Pool</h1> <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.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><a id="Releases"></a> <h1>Releases</h1> <p> See the <a href="/download_pool.cgi">downloads</a> page for information on obtaining releases. </p> </section> <section><a id="Features"></a> <h1>Features</h1> <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> <section><a id="PooledObjectFactory"></a> <h2>PooledObjectFactory</h2> <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> <pre><code> public interface PooledObjectFactory<T> { activateObject(PooledObject<T>) destroyObject(PooledObject<T>) destroyObject(PooledObject<T>, DestroyMode) makeObject() passivateObject(PooledObject<T>) validateObject(PooledObject<T>) } </code></pre> <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 </p> <pre><code> @Override public PooledObject<Foo> wrap(Foo foo) { return new DefaultPooledObject<Foo>(foo); } </code></pre> where <code>Foo</code> is the type of the objects being pooled (the return type of <code>create()</code>). <p> <a href="./apidocs/org/apache/commons/pool2/KeyedPooledObjectFactory.html"><code>KeyedPooledObjectFactory</code></a> defines a similar interface for <code>KeyedObjectPool</code>s: </p> <pre><code> 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); } </code></pre> <p> <a href="./apidocs/org/apache/commons/pool2/BaseKeyedPooledObjectFactory.html"><code>BaseKeyedPooledObjectFactory</code></a> provides an abstract base implementation of <code>KeyedPooledObjectFactory</code>. </p> </section> <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> <section><a id="GenericObjectPool"></a> <h2>GenericObjectPool</h2> <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> </section> <section><a id="SoftReferenceObjectPool"></a> <h2>SoftReferenceObjectPool</h2> <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> </section> </section> <section><a id="Migrating_from_Pool_2.x_to_Pool_2.y"></a> <h1>Migrating from Pool 2.x to Pool 2.y</h1> <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><a id="Migrating_from_Pool_1.x_to_Pool_2.x"></a> <h1>Migrating from Pool 1.x to Pool 2.x</h1> <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> </td> </tr> </table> </div> <div class="footer"> <p>Copyright © 2001-2025 <a href="https://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved.</p> </div> </body> </html>

CINXE.COM

Overview – Apache Commons Pool