commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rwaldh...@apache.org
Subject cvs commit: jakarta-commons/docs/pool examples.html index.html downloads.html contributors.html
Date Mon, 29 Apr 2002 18:02:32 GMT
rwaldhoff    02/04/29 11:02:32

  Modified:    docs/pool index.html downloads.html contributors.html
  Added:       docs/pool examples.html
  Log:
  adding examples doc
  
  Revision  Changes    Path
  1.4       +26 -32    jakarta-commons/docs/pool/index.html
  
  Index: index.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/docs/pool/index.html,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- index.html	29 Apr 2002 14:29:11 -0000	1.3
  +++ index.html	29 Apr 2002 18:02:31 -0000	1.4
  @@ -18,7 +18,7 @@
               
              
                                       
  -            <title>HTTP Client - Home</title>
  +            <title>Pool - Home</title>
           </head>
   
           <body bgcolor="#ffffff" text="#000000" link="#525D76">        
  @@ -52,12 +52,14 @@
           <ul>
                       <li>    <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/index.html">API Documentation</a>
   </li>
  +                    <li>    <a href="./examples.html">Examples</a>
  +</li>
                   </ul>
               <p><strong>Project Files</strong></p>
           <ul>
                       <li>    <a href="./downloads.html">Downloads</a>
   </li>
  -                    <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/pool/">CVS</a>
  +                    <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/pool/">Source</a>
   </li>
                       <li>    <a href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-commons/pool/PROPOSAL.html?content-type=text/html">Original Proposal</a>
   </li>
  @@ -141,12 +143,10 @@
                <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/ObjectPool.html"><code>ObjectPool</code></a>
                defines a trivially simple pooling interface:
             </p>
  -                                                <pre>
  -            public interface ObjectPool {
  -                Object borrowObject();
  -                void returnObject(Object borrowed);
  -            }
  -          </pre>
  +                                                <pre>public interface ObjectPool
{
  +    Object borrowObject();
  +    void returnObject(Object borrowed);
  +}</pre>
                                                   <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>

  @@ -162,12 +162,10 @@
                <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/KeyedObjectPool.html"><code>KeyedObjectPool</code></a>
                defines a similiar interface for pools composed of heterogenous objects:
             </p>
  -                                                <pre>
  -            public interface KeyedObjectPool {
  -                Object borrowObject(Object key);
  -                void returnObject(Object key, Object borrowed);
  -            }
  -          </pre>
  +                                                <pre>public interface KeyedObjectPool
{
  +    Object borrowObject(Object key);
  +    void returnObject(Object key, Object borrowed);
  +}</pre>
                               </blockquote>
         </td></tr>
         <tr><td><br/></td></tr>
  @@ -186,15 +184,13 @@
                <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/PoolableObjectFactory.html"><code>PoolableObjectFactory</code></a>
                supports this by providing a generic inteface for the lifecycle of a pooled
object:
             </p>
  -                                                <pre>
  -            public interface PoolableObjectFactory {
  -                Object makeObject();
  -                void activateObject(Object obj);
  -                void passivateObject(Object obj);
  -                boolean validateObject(Object obj);
  -                void destroyObject(Object obj);
  -            }
  -          </pre>
  +                                                <pre>public interface PoolableObjectFactory
{
  +    Object makeObject();
  +    void activateObject(Object obj);
  +    void passivateObject(Object obj);
  +    boolean validateObject(Object obj);
  +    void destroyObject(Object obj);
  +}</pre>
                                                   <p>
                <code>ObjectPool</code> implementations may be written to accept
arbitrary
                <code>PoolableObjectFactory</code>s.
  @@ -210,15 +206,13 @@
                <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/KeyedPoolableObjectFactory.html"><code>KeyedPoolableObjectFactory</code></a>
                defines a similiar interface for <code>KeyedObjectPool</code>s:
             </p>
  -                                                <pre>
  -            public interface KeyedPoolableObjectFactory {
  -                Object makeObject(Object key);
  -                void activateObject(Object key, Object obj);
  -                void passivateObject(Object key, Object obj);
  -                boolean validateObject(Object key, Object obj);
  -                void destroyObject(Object key, Object obj);
  -            }
  -          </pre>
  +                                                <pre>public interface KeyedPoolableObjectFactory
{
  +    Object makeObject(Object key);
  +    void activateObject(Object key, Object obj);
  +    void passivateObject(Object key, Object obj);
  +    boolean validateObject(Object key, Object obj);
  +    void destroyObject(Object key, Object obj);
  +}</pre>
                                                   <p>
                <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.html"><code>BaseKeyedPoolableObjectFactory</code></a>
                provides an abstract base implementation of <code>KeyedPoolableObjectFactory</code>
that
  
  
  
  1.2       +4 -2      jakarta-commons/docs/pool/downloads.html
  
  Index: downloads.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/docs/pool/downloads.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- downloads.html	23 Apr 2002 00:22:45 -0000	1.1
  +++ downloads.html	29 Apr 2002 18:02:32 -0000	1.2
  @@ -18,7 +18,7 @@
               
              
                                       
  -            <title>HTTP Client - Downloads</title>
  +            <title>Pool - Downloads</title>
           </head>
   
           <body bgcolor="#ffffff" text="#000000" link="#525D76">        
  @@ -52,12 +52,14 @@
           <ul>
                       <li>    <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/index.html">API Documentation</a>
   </li>
  +                    <li>    <a href="./examples.html">Examples</a>
  +</li>
                   </ul>
               <p><strong>Project Files</strong></p>
           <ul>
                       <li>    <a href="./downloads.html">Downloads</a>
   </li>
  -                    <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/pool/">CVS</a>
  +                    <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/pool/">Source</a>
   </li>
                       <li>    <a href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-commons/pool/PROPOSAL.html?content-type=text/html">Original Proposal</a>
   </li>
  
  
  
  1.3       +4 -2      jakarta-commons/docs/pool/contributors.html
  
  Index: contributors.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/docs/pool/contributors.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- contributors.html	29 Apr 2002 12:22:01 -0000	1.2
  +++ contributors.html	29 Apr 2002 18:02:32 -0000	1.3
  @@ -18,7 +18,7 @@
               
              
                                       
  -            <title>HTTP Client - Contributors</title>
  +            <title>Pool - Contributors</title>
           </head>
   
           <body bgcolor="#ffffff" text="#000000" link="#525D76">        
  @@ -52,12 +52,14 @@
           <ul>
                       <li>    <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/index.html">API Documentation</a>
   </li>
  +                    <li>    <a href="./examples.html">Examples</a>
  +</li>
                   </ul>
               <p><strong>Project Files</strong></p>
           <ul>
                       <li>    <a href="./downloads.html">Downloads</a>
   </li>
  -                    <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/pool/">CVS</a>
  +                    <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/pool/">Source</a>
   </li>
                       <li>    <a href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-commons/pool/PROPOSAL.html?content-type=text/html">Original Proposal</a>
   </li>
  
  
  
  1.1                  jakarta-commons/docs/pool/examples.html
  
  Index: examples.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  
  <!-- Content Stylesheet for Site -->
  
          
  <!-- start the processing -->
      <!-- ====================================================================== -->
      <!-- Main Page Section -->
      <!-- ====================================================================== -->
      <html>
          <head>
              <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
  
                                                      <meta name="author" value="Commons
Documentation Team">
              <meta name="email" value="commons-dev@jakarta.apache.org">
                                          <meta name="author" value="Rodney Waldhoff">
              <meta name="email" value="rwaldhoff@apache.org">
              
             
                                      
              <title>Pool - Examples</title>
          </head>
  
          <body bgcolor="#ffffff" text="#000000" link="#525D76">        
              <table border="0" width="100%" cellspacing="0">
                  <!-- TOP IMAGE -->
                  <tr>
                      <td align="left">
  <a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif"
border="0"/></a>
  </td>
  <td align="right">
  <a href="http://jakarta.apache.org/commons/pool"><img src="./images/logo.jpg" alt="Commons"
border="0"/></a>
  </td>
                  </tr>
              </table>
              <table border="0" width="100%" cellspacing="4">
                  <tr><td colspan="2">
                      <hr noshade="" size="1"/>
                  </td></tr>
                  
                  <tr>
                      <!-- LEFT SIDE NAVIGATION -->
                      <td width="20%" valign="top" nowrap="true">
                                  <p><strong>Home</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/commons/index.html">Jakarta Commons</a>
  </li>
                      <li>    <a href="./index.html">Pool</a>
  </li>
                  </ul>
              <p><strong>Information</strong></p>
          <ul>
                      <li>    <a href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/index.html">API Documentation</a>
  </li>
                      <li>    <a href="./examples.html">Examples</a>
  </li>
                  </ul>
              <p><strong>Project Files</strong></p>
          <ul>
                      <li>    <a href="./downloads.html">Downloads</a>
  </li>
                      <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/pool/">Source</a>
  </li>
                      <li>    <a href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-commons/pool/PROPOSAL.html?content-type=text/html">Original Proposal</a>
  </li>
                  </ul>
              <p><strong>About Us</strong></p>
          <ul>
                      <li>    <a href="./contributors.html">Contributors</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/license.html">License</a>
  </li>
                  </ul>
              <p><strong>Jakarta Community</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/site/getinvolved.html">Get Involved</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/site/mail.html">Mailing Lists</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/site/cvsindex.html">CVS Repositories</a>
  </li>
                  </ul>
                          </td>
                      <td width="80%" align="left" valign="top">
                                                                      <table border="0"
cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="A Simple Pool Client"><strong>A Simple Pool Client</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
          Suppose you're writing a set of <code>java.io.Reader</code> utilities,
and would like to
          provide a method for dumping the contents of a <code>Reader</code> to
a <code>String</code>.
          Here's the code for the <code>ReaderUtil</code>, implemented without
an <code>ObjectPool</code>:
         </p>
                                                  <pre><font color="#000080">import</font><font
color="#000000"> java.io.Reader; 
  </font><font color="#000080">import</font><font color="#000000">
java.io.IOException; 
   
  </font><font color="#000080">public</font><font color="#000000">
</font><font color="#000080">class</font><font color="#000000"> ReaderUtil
{ 
      </font><font color="#000080">public</font><font color="#000000">
ReaderUtil() { 
      } 
   
      </font><font color="#808080"><i>/** 
       * Dumps the contents of the {@link Reader} to a 
       * String, closing the {@link Reader} when done. 
       */</i></font><font color="#000000"> 
      </font><font color="#000080">public</font><font color="#000000">
String readToString(Reader in) </font><font color="#000080">throws</font><font
color="#000000"> IOException { 
          StringBuffer buf = </font><font color="#000080">new</font><font
color="#000000"> StringBuffer(); 
          </font><font color="#000080">try</font><font color="#000000">
{ 
              </font><font color="#000080">for</font><font color="#000000">(</font><font
color="#000080">int</font><font color="#000000"> c = in.read(); c != -</font><font
color="#0000ff">1</font><font color="#000000">; c = in.read()) { 
                  buf.append((</font><font color="#000080">char</font><font
color="#000000">)c); 
              } 
              </font><font color="#000080">return</font><font color="#000000">
buf.toString(); 
          } </font><font color="#000080">catch</font><font color="#000000">(IOException
e) { 
              </font><font color="#000080">throw</font><font color="#000000">
e; 
          } </font><font color="#000080">finally</font><font color="#000000">
{ 
              </font><font color="#000080">try</font><font color="#000000">
{ 
                  in.close(); 
              } </font><font color="#000080">catch</font><font color="#000000">(Exception
e) { 
                  </font><font color="#808080"><i>// ignored</i></font><font
color="#000000"> 
              } 
          } 
      } 
  }</font></pre>
                                                  <p>
          For the sake of this example, let's assume we want to to pool the <code>StringBuffer</code>s

          used to buffer the <code>Reader</code>'s contents. (A pool of <code>StringBuffer</code>s

          may or may not be useful in practice. We're just using it as a simple example here.)
         </p>
                                                  <p>
          Let's further assume that a complete pool implementation will be provided via 
          a constructor. (We'll show you how to create such an implementation in just a moment.)
 
          Then to use the pool we simply call <code>borrowObject</code> to obtain
the buffer, and
          then call <code>returnObject</code> when we're done with it.
          Then a <code>ReaderUtil</code> implementation using a pool of <code>StringBuffer</code>s
might look 
          like this (changed code is in <b>bold face</b>):
         </p>
                                                  <pre><b><font color="#000080">import</font><font
color="#000000"> org.apache.commons.pool.ObjectPool;</font></b>
  <font color="#000080">import</font><font color="#000000"> java.io.Reader;

  </font><font color="#000080">import</font><font color="#000000">
java.io.IOException; 
   
  </font><font color="#000080">public</font><font color="#000000">
</font><font color="#000080">class</font><font color="#000000"> ReaderUtil
{ 
      </font><b><font color="#000080">private</font><font color="#000000">
ObjectPool pool;</font></b>
   
      <font color="#000080">public</font><font color="#000000"> ReaderUtil(<b>ObjectPool
pool</b>) { 
          </font><font color="#000080"><b>this</b></font><font
color="#000000"><b>.pool = pool;</b>
      } 
   
      </font><font color="#808080"><i>/** 
       * Dumps the contents of the {@link Reader} to a 
       * String, closing the {@link Reader} when done. 
       */</i></font><font color="#000000"> 
      </font><font color="#000080">public</font><font color="#000000">
String readToString(Reader in) </font><font color="#000080">throws</font><font
color="#000000"> IOException { 
          StringBuffer buf = </font><font color="#000080"><b>null</b></font><font
color="#000000"><b>;</b>
          </font><font color="#000080">try</font><font color="#000000">
{ 
              <b>buf = (StringBuffer)(pool.borrowObject());</b>
              </font><font color="#000080">for</font><font color="#000000">(</font><font
color="#000080">int</font><font color="#000000"> c = in.read(); c != -</font><font
color="#0000ff">1</font><font color="#000000">; c = in.read()) { 
                  buf.append((</font><font color="#000080">char</font><font
color="#000000">)c); 
              } 
              </font><font color="#000080">return</font><font color="#000000">
buf.toString(); 
          } </font><font color="#000080">catch</font><font color="#000000">(IOException
e) { 
              </font><font color="#000080">throw</font><font color="#000000">
e; 
          <b>}</b> </font><font color="#000080"><b>catch</b></font><font
color="#000000"><b>(Exception e) {</b></font>
              <b><font color="#000080">throw</font><font color="#000000">
</font><font color="#000080">new</font><font color="#000000"> RuntimeException(</font><font
color="#008000">"Unable to borrow buffer from pool"</font></b><font color="#000000"><b>
+ </b>
                      <b>e.toString());</b>
          } </font><font color="#000080">finally</font><font color="#000000">
{ 
              </font><font color="#000080">try</font><font color="#000000">
{ 
                  in.close(); 
              } </font><font color="#000080">catch</font><font color="#000000">(Exception
e) { 
                  </font><font color="#808080"><i>// ignored</i></font><font
color="#000000"> 
              } 
              </font><b><font color="#000080">try</font><font color="#000000">
{</font></b>
                  <font color="#000080"><b>if</b></font><font color="#000000"><b>(</b></font><font
color="#000080"><b>null</b></font><font color="#000000"><b>
!= buf) {</b>
                      <b>pool.returnObject(buf);</b>
                  <b>}</b>
              <b>} </b></font><font color="#000080"><b>catch</b></font><font
color="#000000"><b>(Exception e) {</b></font>
                  <b><font color="#808080"><i>// ignored</i></font></b><font
color="#000000">
              <b>}</b>
          } 
      } 
  }</font></pre>
                                                  <p>
         Since we've constrained ourselves to the <code>ObjectPool</code> interface,
an arbitrary pool 
         implementation (returning, in our case, <code>StringBuffer</code>s) can
be used.  When a different
         or "better" pool implemenatation comes along, we can simply drop it into our <code>ReaderUtil</code>
         without changing a line of code.  
        </p>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2"
width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="A PoolableObjectFactory"><strong>A PoolableObjectFactory</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
          Recall that <i>Pool</i> provides a simple toolkit for creating object
pools.  The 
          <code>PoolableObjectFactory</code> interface is an important part of
this toolkit.
          <code>PoolableObjectFactory</code> defines lifecycle methods for pooled
objects. 
          We can use it to separate the kinds of objects that are pooled and how they are

          created, persisted, or destroyed, from the pooling algorithm itself.
         </p>
                                                  <p>
          Suppose we have an <code>ObjectPool</code> implementation that accepts
a 
          <code>PoolableObjectFactory</code> (for example, any of the implementations
in the
          <code>org.apache.commons.pool.impl</code> package).  Then we need only
provide 
          the factory implemenation in order to pool a new kind of object.  
         </p>
                                                  <p>
          Here's a <code>PoolableObjectFactory</code> implementation that creates
          <code>StringBuffer</code>s as used above.
         </p>
                                                  <pre><font color="#000080">import</font><font
color="#000000"> org.apache.commons.pool.BasePoolableObjectFactory; 
   
  </font><font color="#000080">public</font><font color="#000000">
</font><font color="#000080">class</font><font color="#000000"> StringBufferFactory
</font><font color="#000080">extends</font><font color="#000000">
BasePoolableObjectFactory { 
      </font><font color="#808080"><i>// for makeObject we'll simply return
a new buffer</i></font><font color="#000000"> 
      </font><font color="#000080">public</font><font color="#000000">
Object makeObject() { 
          </font><font color="#000080">return</font><font color="#000000">
</font><font color="#000080">new</font><font color="#000000"> StringBuffer();

      } 
       
      </font><font color="#808080"><i>// when an object is returned to the
pool, </i></font><font color="#000000"> 
      </font><font color="#808080"><i>// we'll clear it out</i></font><font
color="#000000"> 
      </font><font color="#000080">public</font><font color="#000000">
</font><font color="#000080">void</font><font color="#000000"> passivateObject(Object
obj) { 
          StringBuffer buf = (StringBuffer)obj; 
          buf.setLength(</font><font color="#0000ff">0</font><font color="#000000">);

      } 
       
      </font><font color="#808080"><i>// for all other methods, the no-op
</i></font><font color="#000000"> 
      </font><font color="#808080"><i>// implementation in BasePoolableObjectFactory</i></font><font
color="#000000"> 
      </font><font color="#808080"><i>// will suffice</i></font><font
color="#000000"> 
  }</font></pre>
                                                  <p>
         We can, for example, use this factory with the <code>StackObjectPool</code>
to instantiate our
         <code>ReaderUtil</code> as follows:
        </p>
                                                  <pre><font color="#000080">new</font>
ReaderUtil(<font color="#000080">new</font> StackObjectPool(<font color="#000080">new</font>
StringBufferFactory()))</pre>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                          </td>
                  </tr>
  
                  <!-- FOOTER -->
                  <tr><td colspan="2">
                      <hr noshade="" size="1"/>
                  </td></tr>
                  <tr><td colspan="2">
                      <div align="center"><font color="#525D76" size="-1"><em>
                      Copyright &#169; 1999-2002, Apache Software Foundation
                      </em></font></div>
                  </td></tr>
              </table>
          </body>
      </html>
  <!-- end the processing -->
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message