src/site/xdoc/index.xml - commons-pool - Git at Google

 <?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

        https://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 xmlns="http://maven.apache.org/XDOC/2.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
    <properties>
       <title>Overview</title>
       <author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
    </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&lt;T&gt; {
     activateObject(PooledObject&lt;T&gt;)
     destroyObject(PooledObject&lt;T&gt;)
     destroyObject(PooledObject&lt;T&gt;, DestroyMode)
     makeObject()
     passivateObject(PooledObject&lt;T&gt;)
     validateObject(PooledObject&lt;T&gt;)
 }
 </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 KeyedPooledObjectFactory&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.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>
	<?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

	https://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 xmlns="http://maven.apache.org/XDOC/2.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
	<properties>
	<title>Overview</title>
	<author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
	</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>