You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rw...@apache.org on 2002/04/29 20:02:32 UTC
cvs commit: jakarta-commons/docs/pool examples.html index.html downloads.html contributors.html
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 © 1999-2002, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>