svn commit: r1539838 - /commons/proper/pool/trunk/src/site/xdoc/index.xml

[ps...@apache.org]

Author: psteitz
Date: Thu Nov  7 22:06:46 2013
New Revision: 1539838

URL: http://svn.apache.org/r1539838
Log:
Added requirement to implement wrap when using BasePooledObjectFactory; added PooledObject change to migration note.

Modified:
    commons/proper/pool/trunk/src/site/xdoc/index.xml

Modified: commons/proper/pool/trunk/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/site/xdoc/index.xml?rev=1539838&r1=1539837&r2=1539838&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/site/xdoc/index.xml (original)
+++ commons/proper/pool/trunk/src/site/xdoc/index.xml Thu Nov  7 22:06:46 2013
@@ -74,15 +74,17 @@ public interface PooledObjectFactory<
             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 looks like this:
- <source>
- public PooledObject&lt;T&gt; makeObject() throws Exception {
-        return new DefaultPooledObject&lt;T&gt;(create());
+            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>create()</code> is abstract.  You just provide an implementation of <code>create()</code> that creates
-           the underlying objects that you want to manage in the pool and <code>BasePooledObjectFactory</code> takes care of
-           wrapping instances in <code>DefaultPooledObject</code>s.
+          where <code>Foo</code> is the type of the objects being pooled (the return type of <code>create()</code>).
           </p>
           <p>
             Another important difference between 1.x and version 2 pools is that the implementations provided maintain references
@@ -134,9 +136,10 @@ public interface KeyedPoolableObjectFact
       <section name="Migrating from Pool 1.x">
         <p>
           The migration from Apache Commons Pool 1.x to 2.x will require some
-          code changes. The most significant change is the change in package
+          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>.
+          <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