You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by John McNally <jm...@collab.net> on 2002/04/05 19:31:05 UTC
[pool] patch for javadoc
Here is a patch that adds an overview to the javadoc for the pool
package. It attempts to show how one would use the component to pool a
particular object in a very simple way.
I also noticed that the text of pool/package.html is copied into an
xdoc, with some notes that it be used as a starting point. I think it
is better to remove the duplication and just have the xdoc link to the
javadoc. If there is anything better to be said, it should be done in
one location. As the pool package is not complex, the javadoc is enough
documentation to make the package useful.
Note: I put the overview.html next to commons/pool/package.html.
john mcnally
Re: [pool] patch for javadoc
Posted by John McNally <jm...@collab.net>.
John McNally wrote:
>
> Try this again. I had both files listed as attachments, don't know why
> only the first one was attached. So here is the html file, hopefuly.
>
> john
>
Argh. still did not work. Here it is inline:
<!-- $Id: $ -->
<html>
<head>
<title>Overview of the org.apache.commons.pool component</title>
</head>
<body>
<p>
Generic Object pooling API with several implementations.
</p>
<p>
The <code>org.apache.commons.pool</code> package defines a simple
interface for a pool of object instances, and a handful of base
classes that may be useful when creating pool implementations.
The api supports pooling of unique objects which can be requested
via a key as well as pools where all objects are equivalent.
</p>
<p>
The <code>org.apache.commons.pool.impl</code> package contains
several pool implementations.
{@link org.apache.commons.pool.impl.StackObjectPool StackObjectPool}
is useful for supporting reuse of a limited number of instances while
allowing new instances to be created as needed to support high demand.
{@link org.apache.commons.pool.impl.GenericObjectPool
GenericObjectPool} has many configuration options and can support
a limited set of objects such as would be useful in a database
connection pool.
{@link org.apache.commons.pool.impl.SoftReferenceObjectPool
SoftReferenceObjectPool} has no limit on the number of objects in the
pool, but garbage collector can remove idle objects from the pool as
needed. There are also keyed versions of the first two.
</p>
<p>
Here is a simple example of pooling <code>HashMap</code>'s. First
create an {@link org.apache.commons.pool.ObjectPoolFactory
ObjectPoolFactory}
</p>
<pre>
public class HashMapFactory
extends {@link org.apache.commons.pool.BasePoolableObjectFactory BasePoolableObjectFactory}
{
/**
* Creates an instance that can be returned by the pool.
* @return an instance that can be returned by the pool.
*/
public Object makeObject()
throws Exception
{
return new HashMap();
}
/**
* Uninitialize an instance to be returned to the pool.
* @param obj the instance to be passivated
*/
public void passivateObject(Object obj)
throws Exception
{
Map map = (Map)obj;
map.clear();
}
}
</pre>
<p>
A class that makes frequent use of a Map could then use a pool
as shown below:
</p>
<pre>
public class Foo
{
private {@link org.apache.commons.pool.ObjectPool ObjectPool} pool;
public Foo()
{
{@link org.apache.commons.pool.PoolableObjectFactory PoolableObjectFactory} factory = new HashMapFactory();
pool = new StackObjectPool(factory, 1000);
}
public doSomething()
{
...
Map map = null;
try
{
map = (Map)pool.borrowObject();
// use map
...
}
finally
{
if (map != null)
{
pool.returnObject(map);
}
}
...
}
}
</pre>
<p>
The above example shows how one would use an
{@link org.apache.commons.pool.ObjectPool ObjectPool}. The other supplied
implementations or another special purpose pool would be used similarly.
</p>
</body>
</html>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [pool] patch for javadoc
Posted by John McNally <jm...@collab.net>.
Try this again. I had both files listed as attachments, don't know why
only the first one was attached. So here is the html file, hopefuly.
john
John McNally wrote:
>
> Here is a patch that adds an overview to the javadoc for the pool
> package. It attempts to show how one would use the component to pool a
> particular object in a very simple way.
>
> I also noticed that the text of pool/package.html is copied into an
> xdoc, with some notes that it be used as a starting point. I think it
> is better to remove the duplication and just have the xdoc link to the
> javadoc. If there is anything better to be said, it should be done in
> one location. As the pool package is not complex, the javadoc is enough
> documentation to make the package useful.
>
> Note: I put the overview.html next to commons/pool/package.html.
>
> john mcnally
>
> ------------------------------------------------------------------------
> Index: build.xml
> ===================================================================
> RCS file: /home/cvspublic/jakarta-commons/pool/build.xml,v
> retrieving revision 1.5
> diff -u -r1.5 build.xml
> --- build.xml 15 Jan 2002 01:20:52 -0000 1.5
> +++ build.xml 5 Apr 2002 17:13:46 -0000
> @@ -153,7 +153,8 @@
> destdir="${dest.doc.api}"
> windowtitle="${Name-Long}"
> doctitle="${Name-Long}"
> - bottom="<small>Copyright &copy; 2001 Apache Software Foundation. Documenation generated ${TODAY}</small>."
> + bottom="<small>Copyright &copy; 2001 Apache Software Foundation. Documentation generated ${TODAY}</small>."
> + Overview="${workdir}/org/apache/commons/pool/overview.html"
> public="true"
> version="true"
> author="true"
>
> ------------------------------------------------------------------------
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>