bloritsch 2002/09/30 14:01:21
Added: docs/excalibur/event command-howto.html command.html
cpuparser-howto.html event-howto.html event.html
mpool-howto.html mpool.html util-howto.html
util.html
docs/excalibur/event/api allclasses-noframe.html
constant-values.html
Log:
add missing docs
Revision Changes Path
1.1 jakarta-avalon-site/docs/excalibur/event/command-howto.html
Index: command-howto.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event - How To Use
Command</title></head><body bgcolor="white" class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8" cellspacing="0"
border="0"><tbody><tr><td align="left"><a href="http://jakarta.apache.org/";><img
border="0" src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - How To Use Command</h1><h2></h2></div><div
class="h3">
<div class="h3"><h3>Setting Up The Command Manager</h3></div>
<p>
Using Command is a two step process. You have to set it up,
and then you can send Commands to it. Because Command uses
an Event Pipeline to move the Commands through the Queue to
the EventHandler, we need to set up a ThreadManager. Currently
the only ThreadManager that works as advertized is the TPCThreadManager.
TPC stands for "Thread Per CPU". The TPCThreadManager allows
you to customize its behaviour by passing in some parameters.
The code snippet below is fairly typical:
</p>
<pre>
ThreadManager threadManager = new TPCThreadManager();
threadManager.enableLogging( getLogger().getChildLogger("threadmanager") );
Parameters params = new Parameters();
params.setParameter( "threads-per-processor", "2" );
params.setParameter( "sleep-time", "1000" );
params.setParameter( "block-timeout", "250" );
threadManager.parameterize( params );
threadManager.initialize();
</pre>
<p>
We create a Threadmanager, pass in the Logger, pass in the Parameters,
and then initialize it. The table below provides all the parameter names
that TPCThreadManager recognizes:
</p>
<table><caption></caption>
<tr>
<td rowspan="" colspan=""><b>Name</b>
</td> <td rowspan="" colspan=""><b>Description</b>
</td> <td rowspan="" colspan=""><b>Default Value</b>
</td>
</tr>
<tr>
<td rowspan="" colspan="">processors
</td>
<td rowspan="" colspan="">Number of processors (autodetected if less than
one)
</td>
<td rowspan="" colspan="">Results from SystemUtil.numProcessors()
</td>
</tr>
<tr>
<td rowspan="" colspan="">threads-per-processor
</td>
<td rowspan="" colspan="">Threads per processor to use (Rewritten to 1 if
less than one)
</td>
<td rowspan="" colspan="">1
</td>
</tr>
<tr>
<td rowspan="" colspan="">sleep-time
</td>
<td rowspan="" colspan="">Time (in milliseconds) to wait between queue
pipeline processing runs
</td>
<td rowspan="" colspan="">1000
</td>
</tr>
<tr>
<td rowspan="" colspan="">block-timeout
</td>
<td rowspan="" colspan="">Time (in milliseconds) to wait for a thread to
process a pipeline
</td>
<td rowspan="" colspan="">1000
</td>
</tr>
</table>
<p>
Once the ThreadManager is set up and used, we can set up the CommandManager.
We do this by instantiating the CommandManager, and registering it with the
ThreadManager. Below is a code snippet showing how that is done:
</p>
<pre>
// Create the CommandManager
CommandManager commandManager = new CommandManager();
// Register it with the ThreadManager
threadManager.register( commandManager );
</pre>
<div class="h3"><h3>Running Commands</h3></div>
<p>
There are three Command interfaces: Command, DelayedCommand, and
RepeatedCommand.
Each one of those has a special purpose. The Command interface exposes the
method
that the CommandManager will execute named, oddly enough, "execute()". The
Delayed Command is used to specify a number of milliseconds to wait before
the
command is run. That delay is based on when the CommandManager receives the
DelayedCommand, not on when the object was created. Lastly the
RepeatedCommand
interface is used to determine how long and how many times the Command will
be executed. Below is a code snippet showing how to send Commands to the
CommandManager:
</p>
<pre>
Sink commandSink = commandManager.getCommandSink();
commandSink.enqueu( new MySpecialCommand() );
</pre>
<p>
It's not that hard to use the CommandManager. Writing a Command is as easy
as
implementing the java.lang.Runnable interface. There are two distinct
advantages
to using the Command infrastructure: your Command can throw exceptions and
it
won't cause anything to break, and you have the ability to automatically
have
your Command run again. Just keep in mind that the Command infrastructure
was
meant for short lived management functions happening in the background, not
a long lived thread. If you want to give the illusion that your Command is
running a long time without tying up system resources the whole time, then
write a RepeatedCommand. Below is an example RepeatedCommand that is used
for the DefaultPoolManager in MPool:
</p>
<pre>
/**
* This is run every 10 seconds, starting after a 10 second delay.
* It gives the appearance of being a long running thread, but it
* does not consume a Thread for the times it would otherwise be
* asleep.
*/
private static final class PoolManagerCommand
implements RepeatedCommand
{
private final BucketMap m_map;
private final int m_min = 4;
private final int m_max = 256;
private final int m_grow = 4;
protected PoolManagerCommand( BucketMap map )
{
m_map = map;
}
public long getDelayInterval()
{
return 10 * 1000L;
}
public long getRepeatInterval()
{
return 10 * 1000L;
}
/**
* Anything less than one (zero or less) means to repeat as long
* as the CommandManager is in service.
*/
public int getNumberOfRepeats()
{
return -1;
}
public void execute()
throws Exception
{
Iterator i = m_map.keySet().iterator();
while( i.hasNext() )
{
ManagablePool pool = (ManagablePool)i.next();
long key = ( (Long)m_map.get( pool ) ).longValue();
int size = pool.size( key );
if( size < m_min )
{
pool.grow( m_grow, key );
}
if( size > m_max )
{
pool.shrink( m_grow, key );
}
}
}
}
</pre>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1 jakarta-avalon-site/docs/excalibur/event/command.html
Index: command.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event -
Command</title></head><body bgcolor="white" class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8" cellspacing="0"
border="0"><tbody><tr><td align="left"><a href="http://jakarta.apache.org/";><img
border="0" src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - Command</h1><h2></h2></div><div class="h3">
<div class="h3"><h3>Why Command Was Created</h3></div>
<p>
Command was created as a way to offload management functions
to a CommandManager which would execute the functions in the
background. The benefits of this approach are tremendous
when you are handling several requests at the same time. As
load increases, you don't increase the frequency in which
certain functions are performed (as in the normal synchronous
management), and you reduce the time for the critical path
to execute. The critical path is the part of your code that
actually solves your problems as opposed to managing resources.
</p>
<div class="h3"><h3>When To Use Command</h3></div>
<p>
A better question might be "when should I not to use Command?".
The complexity of the thread management and command timing is
completely hidden from you. That makes Command as easy to
use as any event based system like Swing. That said, if you
have a really trivial system, or you do not work with heavy
request loads it is definitely easier to design your system
the old fashioned way. If you do expect your application to
work under heavy load, you will find Command to be indespensible.
</p>
<div class="h3"><h3>Core Concepts</h3></div>
<p>
Command is built on top of <a href="event.html">Event</a>.
That means we use a Command Sink to enqueue Commands for the
CommandManager to process. The CommandManager then executes the
commands as they are pulled off of the queue. A Command can be
a repeating command, so CommandManager will automatically requeue
that command for you.
</p>
<div class="h4"><h4>Command</h4></div>
<p>
A Command is an object that performs any function you desire.
You create it by simply implementing the Command interface.
There are three types of commands: a generic command that is
executed immediately in a background thread, a delayed command
that is executed after a specified period of time, and a
repeated command that is executed again and again until the
Command Manager is shut down.
</p>
<div class="h4"><h4>Command Manager</h4></div>
<p>
The Command Manager takes care of processing both Commands
and Signals. With Signals, it will notify the registered
Signal listener. With commands it schedules their execution
in a background thread.
</p>
<div class="h4"><h4>Thread Manager</h4></div>
<p>
A Thread Manager takes care of the threading policy for the
Command Manager. It manages the thread pool size, and how
often the Event Pipeline (the path from a Source to an
EventHandler) is checked.
</p>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1 jakarta-avalon-site/docs/excalibur/event/cpuparser-howto.html
Index: cpuparser-howto.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event - How To
Extend System Util</title></head><body bgcolor="white" class="composite"
marginheight="0" marginwidth="0"><div id="banner"><table width="100%" cellpadding="8"
cellspacing="0" border="0"><tbody><tr><td align="left"><a
href="http://jakarta.apache.org/";><img border="0"
src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - How To Extend System Util</h1><h2></h2></div><div
class="h3">
<div class="h3"><h3>System Util Design</h3></div>
<p>
SystemUtil determins which CPUParser it needs by examining
the results from <code>System.getProperty( "os.name" )</code>.
It strips all the whitespace from the name, and appends it
to the <code>org.apache.excalibur.util.system</code> package.
For example, if the "os.name" property returns "Windows XP",
then the full class name needs to be
<code>org.apache.excalibur.util.system.WindowsXP</code>.
</p>
<div class="h3"><h3>Writing a CPUParser</h3></div>
<p>
Writing a CPUParser is not hard. You only need to know
how to name your implementation, and then write the relevant
logic. All CPUParser implementations must be in the
<code>org.apache.excalibur.util.system</code> package and
implement the CPUParser interface. The example below is
taken from the WindowsXP CPUParser included in this project.
</p>
<pre>
package org.apache.excalibur.util.system;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import org.apache.excalibur.util.CPUParser;
/**
* Parses the Windows XP environment
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/09/30 21:01:21 $
*/
public final class WindowsXP implements CPUParser
{
private final int m_processors;
private final String m_cpuInfo;
/**
* Create this instance of CPUParser and gather information from
* the Windows XP system.
*/
public WindowsXP()
{
int procs = 1;
String info = "";
try
{
Runtime rt = Runtime.getRuntime();
Process proc = rt.exec( "cmd.exe /C echo %NUMBER_OF_PROCESSORS%" );
BufferedReader reader = new BufferedReader( new InputStreamReader(
proc.getInputStream() ) );
String numProcs = reader.readLine();
proc = rt.exec( "cmd.exe /C echo %PROCESSOR_IDENTIFIER%" );
reader = new BufferedReader( new InputStreamReader(
proc.getInputStream() ) );
info = reader.readLine();
procs = Integer.parseInt( numProcs );
}
catch( Exception e )
{
}
m_processors = procs;
m_cpuInfo = info;
}
/**
* Return the number of processors available on the machine
*/
public int numProcessors()
{
return m_processors;
}
/**
* Return the cpu info for the processors (assuming symetric multiprocessing
* which means that all CPUs are identical). The format is:
*
* ${arch} family ${family} Model ${model} Stepping ${stepping}, ${identifier}
*/
public String cpuInfo()
{
return m_cpuInfo;
}
}
</pre>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1 jakarta-avalon-site/docs/excalibur/event/event-howto.html
Index: event-howto.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event - How To Use
Event</title></head><body bgcolor="white" class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8" cellspacing="0"
border="0"><tbody><tr><td align="left"><a href="http://jakarta.apache.org/";><img
border="0" src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - How To Use Event</h1><h2></h2></div><div
class="h3">
<div class="h3"><h3>Event is a Framework for Event Processing</h3></div>
<p>
The first thing that you should expect is that Event does not
do anything by itself. It defines all the core interfaces
used with the Event package. We also have a few implementations.
This documentation focuses on how to use the interfaces.
</p>
<p>
An Event Source is where we pull events from. Whether that Source
is a Queue or just some implementation of the Source doesn't
really matter. The Source has a <code>setTimeout()</code> to
make the Source block for the specified number of milliseconds
before responding.
</p>
<p>
An Event Sink is where we send events. Again, the Sink can be
a unique class, or the other end of a Queue. We have several options
for enqueueing events.
</p>
<p>
A Queue is the union of the Sink and the Source. Events enqueued
on to the Sink portion of the Queue will later be dequeued from
the Source side of the Queue. Because a Queue is simply a Sink and
a Source merged together, there is no reason to duplicate usage
docs.
</p>
<p>
The EventHandler is a class that is set up to handle events. Those
events can then be processed and sent to one of several Queues in
the system.
</p>
<div class="h3"><h3>Pulling Events From a Source</h3></div>
<p>
We have three options: pull one event at a time, unload all the
events, or pull a number of events at a time. Each of these
may be preferred one over the other depending on your design needs.
</p>
<pre>
Object oneEvent = m_mySource.dequeue();
Object[] allEvents = m_mySource.dequeueAll();
Object[] someEvents = m_mySource.dequeue( 10 );
</pre>
<p>
If there are no events, and the timeout is set to 0 or less, we
will immediately return with the results. The version that returns
only one event will return <code>null</code> if there are no events.
The versions that return more than one event will return an empty
array.
</p>
<p><i>
The dequeue() operation that accepts a number will return <b>up
to</b> that number of events. If there are fewer events in the
Source, then it will only return that number.
</i></p>
<p>
There are two remaining methods: <code>setTimeout()</code>, and
<code>size()</code>. The <code>size()</code> method returns the
number of elements in the Sink. The <code>setTimeout()</code>
sets the number of milliseconds you are willing to wait for an
event to show up in the Source. If the timeout is set to zero
or less, the dequeue() methods will return immediately.
</p>
<pre>
// Return immediately
m_mySource.setTimeout( 0 );
// Return after the specified timeout (in milliseconds)
m_mySource.setTimeout( 250 );
</pre>
<div class="h3"><h3>Sending Events to a Sink</h3></div>
<p>
We have several options for enqueuing events into a Sink.
We have transactional enqueuing, lossy enqueuing, and
normal enqueuing.
</p>
<pre>
// Enqueue one event at a time:
try
{
Object event = createEvent();
m_mySink.enqueue( event );
}
catch (SinkException se)
{
getLogger().error( "Error enqueuing events", se );
}
// Enqueue several events at one time
try
{
Object[] events = createEvents();
m_mySink.enqueue( events );
}
catch (SinkException se)
{
/* IMPORTANT: This is ALL OR NOTHING. If an exception
* is thrown, none of the events were enqueued
*/
getLogger().error( "Error enqueuing events", se );
}
// Perform lossy enqueuing
Object event = createEvent();
boolean wasSuccessful = m_mySink.tryEnqueue( event );
if ( ! wasSuccessful ) doSomething();
// Perform Transactional enqueuing
try
{
Object[] events = createEvents();
PreparedEnqueue transaction = m_mySink.prepareEnqueue( events );
// perform some conditional logic
if( shouldCommit( events ) )
{
transaction.commit();
}
else
{
transaction.abort();
}
}
catch (SinkException se)
{
/* IMPORTANT: This is ALL OR NOTHING. If an exception
* is thrown, none of the events were enqueued
*/
getLogger().error( "Error enqueuing events", se );
}
</pre>
<p>
The transactional enqueuing allows you to set some
events on the Sink ahead of time, and perform your processing.
If the events are not up to snuff, you can abort() the
enqueue, and they will not be processed.
</p>
<p>
There are some other methods that are utility methods:
<code>maxSize()</code>, <code>isFull()</code>,
<code>canAccept()</code>, <code>size()</code>. They help
yoy in your planning. Use <code>maxSize()</code> to determine
the bounds of the Sink. If the value returned is -1, then
there are no bounds. If the value is positive, then that
is the limit of the number of events the Sink can have at
one time. The <code>canAccept()</code> method is related
in that it only makes sense for bounded Sinks. If there is
a limit the <code>canAccept()</code> method will return the
number of events the Sink will accept, otherwise it will
return -1. The <code>size()</code> method returns the number
of elements still in the Sink. The <code>isFull()</code>
method returns wether the Sink has more room.
</p>
<pre>
// Determining how many events a Sink can handle
int numElements = m_mySink.canAccept();
if ( numElements < 0 )
{
// This is an unbounded Sink
}
</pre>
<div class="h3"><h3>EventHandlers</h3></div>
<p>
Event Handlers are used in automated event routing systems like
SEDA architectures. Basically, it is a way for your object/component
to handle events without having to implement the Sink interface,
which can be kind of tricky. Here is an example:
</p>
<pre>
import org.apache.excalibur.event.EventHandler;
/** Send events to System.out */
public class MyEventHandler implements EventHandler
{
/** Handle several events at one time */
public void handleEvents( Object[] events )
{
for (int i = 0; i < events.length; i++)
{
handleEvent( events[i] );
}
}
/** Handle one event at a time */
public void handleEvent( Object event )
{
System.out.println( event );
}
}
</pre>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1 jakarta-avalon-site/docs/excalibur/event/event.html
Index: event.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event -
Event</title></head><body bgcolor="white" class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8" cellspacing="0"
border="0"><tbody><tr><td align="left"><a href="http://jakarta.apache.org/";><img
border="0" src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - Event</h1><h2></h2></div><div class="h3">
<div class="h3"><h3>Why Event Was Created</h3></div>
<p>
Event was created out of a desire to express the Staged Event
Driven Architecture (SEDA) design in an Avalon way. It has
grown to be a robust event pipelining library. We maintained
the core concepts from the
<a target="_blank" href="http://seda.sourceforge.net/";>SandStorm</a>
server, and cleaned up the API to have Queues operate in a
more transactional way.
</p>
<div class="h3"><h3>When To Use Event</h3></div>
<p>
Most of the time, your use of the Event package is only to
interface to other subsystems. For instance, the
<a href="command.html">Command Manager</a> uses the
Event Queues to receive commands from multiple threads
simultaneously.
</p>
<p>
You can also use Event when you are developing new systems
that have loosely coupled, disjunct pieces. One of the core
benefits of using event pipelines is that we can easily
reroute the Queues while the system is running, and not lose
any events.
</p>
<div class="h3"><h3>Core Concepts</h3></div>
<p>
An Event Pipeline has a set of Sources and Sinks. A Source
is where you get more events, or the "dequeue" side of an
event Queue. A Sink is where you send events on to the next
stage, or the "enqueue" side of an event Queue.
</p>
<div class="h4"><h4>Source</h4></div>
<p>
The Source can be blocking or non-blocking. A blocking
Source will stop the current thread from processing until
there are new events to give to it. A non-blocking Source
will return an empty set of events immediately if there
are no more events.
</p>
<div class="h4"><h4>Sink</h4></div>
<p>
The Sink allows you to add events in a variety of ways.
You can simply add them one at a time, or you can add
a whole group of events at one time. The Sink also supports
a transactional enqueue which means we can push some events
on to the Sink, but wait to commit or cancel the events
at a later time. The Sink will make room for the events,
but it will not let them pass through until they are officially
committed.
</p>
<div class="h4"><h4>Queue</h4></div>
<p>
A Queue is merely the union of a Sink and a Source. A Queue
will manage the throughput of the events from Sink to Source.
</p>
<div class="h4"><h4>Signals and Messages</h4></div>
<p>
Signals and Messages are special events that provide contextual
information. A message will have a string and/or an object
attached to it. They are used mainly for reporting purposes,
or for the begginings of a Messaging Oriented Middleware (MOM)
implementation. A Signal is a control event that the Queue,
and the system react to.
</p>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1 jakarta-avalon-site/docs/excalibur/event/mpool-howto.html
Index: mpool-howto.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event - How To Use
MPool</title></head><body bgcolor="white" class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8" cellspacing="0"
border="0"><tbody><tr><td align="left"><a href="http://jakarta.apache.org/";><img
border="0" src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - How To Use MPool</h1><h2></h2></div><div
class="h3">
<div class="h3"><h3>Setting Up the PoolManager</h3></div>
<p>
In order to set up a CommandManager. For those instructions,
follow <a href="command-howto.html">the Command "How To"</a>.
From there, you want to set up the PoolManager using the following
code:
</p>
<pre>
// Using the CommandManager in the variable "commandManager"
PoolManager poolManager = new DefaultPoolManager( commandManager );
</pre>
<div class="h3"><h3>Creating Your Pool</h3></div>
<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>
<pre>
int initialEntries = 20;
ObjectFactory objectFactory = new MySpecialObjectFactory();
Pool managedPool = poolManager.getManagedPool( objectFactory, initialEntries );
</pre>
<div class="h4"><h4>Writing an ObjectFactory</h4></div>
<p>
Writing an Object Factory is not that difficult. You just need to
implement the ObjectFactory interface. Below is an example
implementation:
</p>
<pre>
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
}
}
</pre>
<div class="h4"><h4>Unmanaged Pools</h4></div>
<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>
<div class="h3"><h3>Using the Pool</h3></div>
<p>
Using the pools are quite simple:
</p>
<pre>
Object pooledResource = managedPool.acquire();
// do whatever I want with the pooled resource
managedPool.release( pooledResource );
</pre>
<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>
<pre>
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...
}
}
</pre>
<pre>
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...
}
}
</pre>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1 jakarta-avalon-site/docs/excalibur/event/mpool.html
Index: mpool.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event - MPool
(Managed Pool)</title></head><body bgcolor="white" class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8" cellspacing="0"
border="0"><tbody><tr><td align="left"><a href="http://jakarta.apache.org/";><img
border="0" src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - MPool (Managed Pool)</h1><h2></h2></div><div
class="h3">
<div class="h3"><h3>Why MPool Was Created</h3></div>
<p>
MPool (Managed Pool) was created as an experiment in dynamic
pool management. The theory is that by determining whether to
shrink or grow a pool can be a costly endeavor. That is
especially true when you want to play with "intelligent" pools.
</p>
<p>
What we observed after we used MPool in practice is that under
load, pool sizing algorithms begin to choke the efficiency of
the pool. In fact, it can get so bad that it would be better
not to have a pool at all. An unbounded pool (one that does
not shrink) is a resource hog, especially during inactive times.
By moving the pool sizing logic into an asyncronous Command,
we were able to achieve the efficiency of an unbounded pool
while keeping an eye on pool size. During times of inactivity
we destroy pooled objects that we don't need. During times of
stress, we create a new object immediately and in a background
process we add new objects.
</p>
<div class="h3"><h3>When To Use MPool</h3></div>
<p>
Use MPool any time you need a pool without hard limits, and you
expect heavy loads. The pool size is checked periodically, so
we don't incur extra overhead of having to check that while the
pool size grows and shrinks.
</p>
<div class="h3"><h3>Core Concepts</h3></div>
<p>
MPool has two pool types: fixed size and variable size. A fixed
size pool is not managed externally. There is a fixed limit to
the number of resources it can manage so we don't have to manage
it. A variable sized pool is a managed pool. A managed pool will
be created by the PoolManager, and that manager will manage all
of its pool sizes in the background.
</p>
<div class="h4"><h4>Object Factory</h4></div>
<p>
An Object Factory is what the pools use to create new objects
or destroy old ones. They are particularly helpful when there
is a complex creation/destruction policy. They are also essential
for ManagablePools.
</p>
<div class="h4"><h4>Pool</h4></div>
<p>
The base Pool interface is how the client code interacts with
the pool. You acquire and release pooled objects from the
pool.
</p>
<div class="h4"><h4>Managable Pool</h4></div>
<p>
A Managable Pool is a special interface that allows a PoolManager
to register itself with a "magic key" so that the managed pool
only responds to the PoolManager responsible for it.
</p>
<div class="h4"><h4>Pool Manager</h4></div>
<p>
The Pool Manager is how you obtain a Managable Pool. It also
takes care of the management functions for that pool.
</p>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1 jakarta-avalon-site/docs/excalibur/event/util-howto.html
Index: util-howto.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event - How To Use
Util</title></head><body bgcolor="white" class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8" cellspacing="0"
border="0"><tbody><tr><td align="left"><a href="http://jakarta.apache.org/";><img
border="0" src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - How To Use Util</h1><h2></h2></div><div
class="h3">
<div class="h3"><h3>Getting the System Info</h3></div>
<p>
Util has one utility: SystemUtil. SystemUtil is a static
class that performs its magic when the class is loaded.
It stores the information because it is unlikely that you
will ever go from one to two processors while your machine
is running. The code snippet below demonstrates how to
get any and all the relavant information:
</p>
<pre>
public void dumpInfo()
{
System.out.println( "Number of Processors: " + SystemUtil.numProcessors() );
System.out.println( "CPU Info: " + SystemUtil.cpuInfo() );
System.out.println( "Architecture: " + SystemUtil.architecture() );
System.out.println( "Operating System: " + SystemUtil.operatingSystem() );
System.out.println( "OS Version: " + SystemUtil.osVersion() );
}
</pre>
<p>
As you can see there is no real mystery here. The method above
uses every available SystemUtil method, and it is taken directly
from the JUnit TestCase for SystemUtil.
</p>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1 jakarta-avalon-site/docs/excalibur/event/util.html
Index: util.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css" type="text/css"><link
media="print" rel="stylesheet" href="skin/print.css" type="text/css"><meta
value="Avalon Documentation Team" name="author"><meta
value="[EMAIL PROTECTED]" name="email"><title>Excalibur Event -
Util</title></head><body bgcolor="white" class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8" cellspacing="0"
border="0"><tbody><tr><td align="left"><a href="http://jakarta.apache.org/";><img
border="0" src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><table width="100%"
cellpadding="0" cellspacing="0" border="0" id="breadcrumbs"><td><a
href="http://jakarta.apache.org/";>Jakarta Main</a> |
<a href="http://jakarta.apache.org/avalon";>Avalon Main</a> |
<a href="../index.html">Up</a></td><td style="text-align: right"
align="right"><a href="http://jakarta.apache.org/avalon/framework/";>Framework</a> |
<a href="http://jakarta.apache.org/avalon/excalibur/";>Excalibur</a> |
<a href="http://jakarta.apache.org/avalon/cornerstone/";>Cornerstone</a>
|
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">About Event</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api/index.html">API Docs</a></div></div><div><strong>Overview</strong><div><a
href="event.html">Event</a></div><div><a href="command.html">Command</a></div><div><a
href="mpool.html">MPool</a></div><div><a
href="util.html">Util</a></div></div><div><strong>How To</strong><div><a
href="event-howto.html">Use Event Queues</a></div><div><a
href="command-howto.html">Use the Command Manager</a></div><div><a
href="mpool-howto.html">Use MPool</a></div><div><a href="util-howto.html">Use System
Util</a></div><div><a href="cpuparser-howto.html">Extend System
Util</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Excalibur Event - Util</h1><h2></h2></div><div class="h3">
<div class="h3"><h3>Why Util Was Created</h3></div>
<p>
Util was created to enable us to find out how many processors are
on a system programmatically. Unfortunately Sun does not think
it is important to know these details through Java. The Thread
Manager uses this to automatically determine how many background
threads it wants in the backing ThreadPool.
</p>
<div class="h3"><h3>When To Use Util</h3></div>
<p>
Usually you won't use this package directly, unless you want to
know how many processors a system has. You might need to add a
new CPU Parser that will find out the necessary information from
environment variables or the /proc/ filesystem for a platform
that is not currently supported.
</p>
<div class="h3"><h3>Core Concepts</h3></div>
<p>
Util has a SystemUtil which will load the correct CPU Parser for your
platform. If there is no maching CPU Parser will assume that there is
only one processor for your system.
</p>
<div class="h4"><h4>System Util</h4></div>
<p>
The System Util will allow you to gather any platform specific
information. Some of the methods are simpler ways of accessing
the System properties, and others are derived from the CPU Parser.
</p>
<div class="h4"><h4>CPU Parser</h4></div>
<p>
The CPU Parser will allow you to gather essential information from
your platform. Unfortunately we cannot assume there is only one
way to gather information for each platform. If your platform is
not supported directly, please send an email to
the Avalon Users
mailing list with the new CPU Parser attached. We should be able
to include it in the next release. We currently support the entire
Microsoft Windows suite that supports Java, and Linux. Since we
don't currently have access to other machines, we can't support them
yet.
</p>
<div id="authors" align="right">by Berin
Loritsch</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1
jakarta-avalon-site/docs/excalibur/event/api/allclasses-noframe.html
Index: allclasses-noframe.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0
Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd";>
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc on Mon Sep 30 17:02:51 EDT 2002 -->
<TITLE>
All Classes (Excalibur Event API)
</TITLE>
<LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
</HEAD>
<SCRIPT>
function asd()
{
parent.document.title="All Classes (Excalibur Event API)";
}
</SCRIPT>
<BODY BGCOLOR="white" onload="asd();">
<FONT size="+1" CLASS="FrameHeadingFont">
<B>All Classes</B></FONT>
<BR>
<TABLE BORDER="0" WIDTH="100%">
<TR>
<TD NOWRAP><FONT CLASS="FrameItemFont"><A
HREF="org/apache/excalibur/event/impl/AbstractQueue.html" TARGET="">AbstractQueue</A>
<BR>
<A HREF="org/apache/excalibur/event/command/AbstractThreadManager.html"
TARGET="">AbstractThreadManager</A>
<BR>
<A
HREF="org/apache/excalibur/event/command/AbstractThreadManager.PipelineRunner.html"
TARGET="">AbstractThreadManager.PipelineRunner</A>
<BR>
<A HREF="org/apache/excalibur/mpool/BlockingFixedSizePool.html"
TARGET="">BlockingFixedSizePool</A>
<BR>
<A HREF="org/apache/excalibur/event/command/Command.html"
TARGET=""><I>Command</I></A>
<BR>
<A HREF="org/apache/excalibur/event/command/CommandManager.html"
TARGET="">CommandManager</A>
<BR>
<A HREF="org/apache/excalibur/util/CPUParser.html" TARGET=""><I>CPUParser</I></A>
<BR>
<A HREF="org/apache/excalibur/mpool/DefaultPoolManager.html"
TARGET="">DefaultPoolManager</A>
<BR>
<A HREF="org/apache/excalibur/event/impl/DefaultQueue.html"
TARGET="">DefaultQueue</A>
<BR>
<A HREF="org/apache/excalibur/event/command/DefaultThreadManager.html"
TARGET="">DefaultThreadManager</A>
<BR>
<A HREF="org/apache/excalibur/event/command/DelayedCommand.html"
TARGET=""><I>DelayedCommand</I></A>
<BR>
<A HREF="org/apache/excalibur/event/EventHandler.html"
TARGET=""><I>EventHandler</I></A>
<BR>
<A HREF="org/apache/excalibur/event/command/EventPipeline.html"
TARGET=""><I>EventPipeline</I></A>
<BR>
<A HREF="org/apache/excalibur/event/command/EventThreadPool.html"
TARGET="">EventThreadPool</A>
<BR>
<A HREF="org/apache/excalibur/mpool/FixedSizePool.html" TARGET="">FixedSizePool</A>
<BR>
<A HREF="org/apache/excalibur/event/impl/FixedSizeQueue.html"
TARGET="">FixedSizeQueue</A>
<BR>
<A HREF="org/apache/excalibur/util/system/Linux.html" TARGET="">Linux</A>
<BR>
<A HREF="org/apache/excalibur/mpool/ManagablePool.html"
TARGET=""><I>ManagablePool</I></A>
<BR>
<A HREF="org/apache/excalibur/event/Message.html" TARGET=""><I>Message</I></A>
<BR>
<A HREF="org/apache/excalibur/mpool/ObjectFactory.html"
TARGET=""><I>ObjectFactory</I></A>
<BR>
<A HREF="org/apache/excalibur/mpool/Pool.html" TARGET=""><I>Pool</I></A>
<BR>
<A HREF="org/apache/excalibur/mpool/PoolManager.html"
TARGET=""><I>PoolManager</I></A>
<BR>
<A HREF="org/apache/excalibur/mpool/PoolUtil.html" TARGET="">PoolUtil</A>
<BR>
<A HREF="org/apache/excalibur/event/PreparedEnqueue.html"
TARGET=""><I>PreparedEnqueue</I></A>
<BR>
<A HREF="org/apache/excalibur/event/Queue.html" TARGET=""><I>Queue</I></A>
<BR>
<A HREF="org/apache/excalibur/event/command/RepeatedCommand.html"
TARGET=""><I>RepeatedCommand</I></A>
<BR>
<A HREF="org/apache/excalibur/mpool/Resettable.html" TARGET=""><I>Resettable</I></A>
<BR>
<A HREF="org/apache/excalibur/event/Signal.html" TARGET=""><I>Signal</I></A>
<BR>
<A HREF="org/apache/excalibur/event/Sink.html" TARGET=""><I>Sink</I></A>
<BR>
<A HREF="org/apache/excalibur/event/SinkClosedException.html"
TARGET="">SinkClosedException</A>
<BR>
<A HREF="org/apache/excalibur/event/SinkException.html" TARGET="">SinkException</A>
<BR>
<A HREF="org/apache/excalibur/event/SinkFullException.html"
TARGET="">SinkFullException</A>
<BR>
<A HREF="org/apache/excalibur/event/Source.html" TARGET=""><I>Source</I></A>
<BR>
<A HREF="org/apache/excalibur/util/SystemUtil.html" TARGET="">SystemUtil</A>
<BR>
<A HREF="org/apache/excalibur/event/command/ThreadManager.html"
TARGET=""><I>ThreadManager</I></A>
<BR>
<A HREF="org/apache/excalibur/event/command/TPCThreadManager.html"
TARGET="">TPCThreadManager</A>
<BR>
<A HREF="org/apache/excalibur/event/command/TPSPThreadManager.html"
TARGET="">TPSPThreadManager</A>
<BR>
<A HREF="org/apache/excalibur/event/command/TPSPThreadManager.PipelineRunner.html"
TARGET="">TPSPThreadManager.PipelineRunner</A>
<BR>
<A HREF="org/apache/excalibur/mpool/VariableSizePool.html"
TARGET="">VariableSizePool</A>
<BR>
<A HREF="org/apache/excalibur/util/system/Windows2000.html"
TARGET="">Windows2000</A>
<BR>
<A HREF="org/apache/excalibur/util/system/Windows95.html" TARGET="">Windows95</A>
<BR>
<A HREF="org/apache/excalibur/util/system/Windows98.html" TARGET="">Windows98</A>
<BR>
<A HREF="org/apache/excalibur/util/system/WindowsNT.html" TARGET="">WindowsNT</A>
<BR>
<A HREF="org/apache/excalibur/util/system/WindowsXP.html" TARGET="">WindowsXP</A>
<BR>
</FONT></TD>
</TR>
</TABLE>
</BODY>
</HTML>
1.1
jakarta-avalon-site/docs/excalibur/event/api/constant-values.html
Index: constant-values.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0
Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd";>
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc on Mon Sep 30 17:02:50 EDT 2002 -->
<TITLE>
Constant Field Values (Excalibur Event API)
</TITLE>
<LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
</HEAD>
<SCRIPT>
function asd()
{
parent.document.title="Constant Field Values (Excalibur Event API)";
}
</SCRIPT>
<BODY BGCOLOR="white" onload="asd();">
<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_top"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A
HREF="overview-summary.html"><FONT
CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT
CLASS="NavBarFont1">Package</FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT
CLASS="NavBarFont1">Class</FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="overview-tree.html"><FONT
CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="deprecated-list.html"><FONT
CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="index-all.html"><FONT
CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="help-doc.html"><FONT
CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
PREV
NEXT</FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="index.html" TARGET="_top"><B>FRAMES</B></A>
<A HREF="constant-values.html" TARGET="_top"><B>NO FRAMES</B></A>
<SCRIPT>
<!--
if(window==top) {
document.writeln('<A HREF="allclasses-noframe.html" TARGET=""><B>All
Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->
<HR>
<CENTER>
<H1>
Constant Field Values</H1>
</CENTER>
<HR SIZE="4" NOSHADE>
<B>Contents</B><UL>
</UL>
<HR>
<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_bottom"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A
HREF="overview-summary.html"><FONT
CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT
CLASS="NavBarFont1">Package</FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT
CLASS="NavBarFont1">Class</FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="overview-tree.html"><FONT
CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="deprecated-list.html"><FONT
CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="index-all.html"><FONT
CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="help-doc.html"><FONT
CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
PREV
NEXT</FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="index.html" TARGET="_top"><B>FRAMES</B></A>
<A HREF="constant-values.html" TARGET="_top"><B>NO FRAMES</B></A>
<SCRIPT>
<!--
if(window==top) {
document.writeln('<A HREF="allclasses-noframe.html" TARGET=""><B>All
Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->
<HR>
Copyright © 2002 Apache Jakarta Project. All Rights Reserved.
</BODY>
</HTML>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
