bloritsch 2002/09/30 11:34:44
Modified: event/src/xdocs menu.xml
Added: event/src/xdocs event-howto.xml mpool-howto.xml
Removed: event/src/xdocs thread-howto.xml thread.xml
Log:
Update the docs with MPool how-to
Revision Changes Path
1.11 +0 -4 jakarta-avalon-excalibur/event/src/xdocs/menu.xml
Index: menu.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/menu.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- menu.xml 27 Sep 2002 20:30:44 -0000 1.10
+++ menu.xml 30 Sep 2002 18:34:43 -0000 1.11
@@ -14,7 +14,6 @@
<item href="event.html" name="Event"/>
<item href="command.html" name="Command"/>
<item href="mpool.html" name="MPool"/>
- <item href="thread.html" name="Thread"/>
<item href="util.html" name="Util"/>
</menu>
@@ -23,10 +22,7 @@
<item href="event-howto.html" name="Use Event Queues"/>
-->
<item href="command-howto.html" name="Use the Command Manager"/>
-<!--
<item href="mpool-howto.html" name="Use MPool"/>
- -->
- <item href="thread-howto.html" name="Use Thread Pools"/>
<item href="util-howto.html" name="Use System Util"/>
<item href="cpuparser-howto.html" name="Extend System Util"/>
</menu>
1.1 jakarta-avalon-excalibur/event/src/xdocs/event-howto.xml
Index: event-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Excalibur Event - Overview</title>
<authors>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
This is the Excalibur Event package which includes event queues,
asynchronous command processing, and the interfaces to support
event based programming. Event is heavily influenced by Matt
Welsh's work with the
<fork href="http://www.cs.berkeley.edu/~mdw/proj/seda/";>SEDA
architecture</fork>.
We forked the portion of his SandStorm server that had to do with
event processing. From there we cleaned up the API and made it as
generic as we could.
</p>
<p>
The Event package actually has five related sub packages inside
of it. Event is the basic interfaces for the Queues, Sinks,
Sources, etc. Command houses code for the CommandManager so that
your code can safely process Commands (a type of event) in the
background. MPool, short for Managed Pool, houses code for a
pool implementation that manages its size asynchronously so you
don't have to worry about it. Thread is the thread pool code
which uses MPool to keep track of the threads. Lastly, Util
provides some basic utilities so that we can programatically
determine the number of processors your hardware has.
</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/09/30 18:34:43 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-excalibur/event/src/xdocs/mpool-howto.xml
Index: mpool-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Excalibur Event - How To Use MPool</title>
<authors>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Setting Up the PoolManager">
<p>
In order to set up a CommandManager. For those instructions,
follow <link href="command-howto.html">the Command "How To"</link>.
From there, you want to set up the PoolManager using the following
code:
</p>
<source>
<![CDATA[
// Using the CommandManager in the variable "commandManager"
PoolManager poolManager = new DefaultPoolManager( commandManager );
]]>
</source>
</s1>
<s1 title="Creating Your Pool">
<p>
The PoolManager is responsible for manufacturing managed pools,
and for managing their sizes. All PoolManager managed pools are
"soft" limiting. They will continue to grow while they are being
accessed heavily, but it will shrink during times of inactivity.
To create your pool, use the following code:
</p>
<source>
<![CDATA[
int initialEntries = 20;
ObjectFactory objectFactory = new MySpecialObjectFactory();
Pool managedPool = poolManager.getManagedPool( objectFactory, initialEntries );
]]>
</source>
<s2 title="Writing an ObjectFactory">
<p>
Writing an Object Factory is not that difficult. You just need to
implement the ObjectFactory interface. Below is an example
implementation:
</p>
<source>
<![CDATA[
public class MySpecialObjectFactory implements ObjectFactory
{
private final Class m_mySpecialClass;
/** Create default object type */
public MySpecialObjectFactory()
{
this( MySpecialObject.class );
}
/** Create generic object type */
public MySpecialObjectFactory( Class specialClass )
{
if ( null == specialClass )
{
throw new IllegalArgumentException ("Class cannot be null");
}
m_mySpecialClass = specialClass;
}
/** Implement the getCreatedClass() method */
public Class getCreatedClass()
{
return m_mySpecialClass;
}
/** Create an instance */
public Object newInstance()
throws Exception
{
return getCreatedClass().newInstance();
}
/** Dispose of an instance */
public void dispose( Object obj )
{
// perform permanent cleanup code
}
}
]]>
</source>
</s2>
<s2 title="Unmanaged Pools">
<p>
There are two unmanaged pool types in MPool:
FixedSizePool and BlockingFixedSizePool. They are
similar to one another, but differ in how they respond
to insufficient resources. The FixedSizePool fails fast,
and throws an exception. The BlockingFixedSizePool tries
to wait for a specified number of milliseconds.
</p>
<p>
The Fixed Size Pools are not managed because they will only
have a certain number of pooled objects at any time. They
will never grow or shrink. They are useful for instances
where the number of elements are known in advanced. One
example is a JDBC connection pool because some vendors require
you to pay per connection licensing fees.
</p>
</s2>
</s1>
<s1 title="Using the Pool">
<p>
Using the pools are quite simple:
</p>
<source>
<![CDATA[
Object pooledResource = managedPool.acquire();
// do whatever I want with the pooled resource
managedPool.release( pooledResource );
]]>
</source>
<p>
What if we have an object that needs to perform some simple
clieanup? Have your Object implement the <code>Resettable</code>
interface. What if we are migrating from the old Pool package?
you don't have to do anything. MPool knows about the old Pool
package, and will check for its recyclable method. It will only
call the Resettable.reset() method if your object implements both
interfaces. Both of these will work:
</p>
<source>
<![CDATA[
import org.apache.excalibur.mpool.Resettable;
public class ResettableObject implements Resettable
{
// All the methods and stuff for the real object...
public void reset()
{
// perform small cleanup code...
}
}
]]>
</source>
<source>
<![CDATA[
import org.apache.avalon.excalibur.pool.Recyclable;
public class ResettableObject implements Recyclable
{
// All the methods and stuff for the real object...
public void recycle()
{
// perform small cleanup code...
}
}
]]>
</source>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/09/30 18:34:43 $
</legal>
</footer>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
