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="[EMAIL PROTECTED]">
<meta name="author" value="Rodney Waldhoff">
<meta name="email" value="[EMAIL PROTECTED]">
<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 © 1999-2002, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
![http://jakarta.apache.org/images/jakarta-logo.gif"](http://jakarta.apache.org/images/jakarta-logo.gif"){kind=link}