crafterm 2002/10/23 06:50:01
Modified: event/src/xdocs command-howto.xml command.xml
cpuparser-howto.xml event-howto.xml event.xml
menu.xml mpool-howto.xml mpool.xml util-howto.xml
util.xml
Log:
Removed ^M's
Revision Changes Path
1.3 +182 -182 jakarta-avalon-excalibur/event/src/xdocs/command-howto.xml
Index: command-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/command-howto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- command-howto.xml 27 Sep 2002 20:29:18 -0000 1.2
+++ command-howto.xml 23 Oct 2002 13:50:00 -0000 1.3
@@ -1,182 +1,182 @@
-<?xml version="1.0"?>
-
-<document>
- <header>
- <title>Excalibur Event - How To Use Command</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="Setting Up The Command Manager">
- <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>
- <source>
-<![CDATA[
-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();
-]]>
- </source>
- <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>
- <tr>
- <th>Name</th> <th>Description</th> <th>Default Value</th>
- </tr>
- <tr>
- <td>processors</td>
- <td>Number of processors (autodetected if less than one)</td>
- <td>Results from SystemUtil.numProcessors()</td>
- </tr>
- <tr>
- <td>threads-per-processor</td>
- <td>Threads per processor to use (Rewritten to 1 if less than one)</td>
- <td>1</td>
- </tr>
- <tr>
- <td>sleep-time</td>
- <td>Time (in milliseconds) to wait between queue pipeline processing
runs</td>
- <td>1000</td>
- </tr>
- <tr>
- <td>block-timeout</td>
- <td>Time (in milliseconds) to wait for a thread to process a
pipeline</td>
- <td>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>
- <source>
- <![CDATA[
-// Create the CommandManager
-CommandManager commandManager = new CommandManager();
-
-// Register it with the ThreadManager
-threadManager.register( commandManager );
- ]]>
- </source>
- </s1>
- <s1 title="Running Commands">
- <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>
- <source>
- <![CDATA[
-Sink commandSink = commandManager.getCommandSink();
-commandSink.enqueu( new MySpecialCommand() );
- ]]>
- </source>
- <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>
- <source>
- <![CDATA[
- /**
- * 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 );
- }
- }
- }
- }
- ]]>
- </source>
- </s1>
- </body>
- <footer>
- <legal>
- Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision$ $Date$
- </legal>
- </footer>
-</document>
+<?xml version="1.0"?>
+
+<document>
+ <header>
+ <title>Excalibur Event - How To Use Command</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="Setting Up The Command Manager">
+ <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>
+ <source>
+<![CDATA[
+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();
+]]>
+ </source>
+ <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>
+ <tr>
+ <th>Name</th> <th>Description</th> <th>Default Value</th>
+ </tr>
+ <tr>
+ <td>processors</td>
+ <td>Number of processors (autodetected if less than one)</td>
+ <td>Results from SystemUtil.numProcessors()</td>
+ </tr>
+ <tr>
+ <td>threads-per-processor</td>
+ <td>Threads per processor to use (Rewritten to 1 if less than one)</td>
+ <td>1</td>
+ </tr>
+ <tr>
+ <td>sleep-time</td>
+ <td>Time (in milliseconds) to wait between queue pipeline processing
runs</td>
+ <td>1000</td>
+ </tr>
+ <tr>
+ <td>block-timeout</td>
+ <td>Time (in milliseconds) to wait for a thread to process a pipeline</td>
+ <td>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>
+ <source>
+ <![CDATA[
+// Create the CommandManager
+CommandManager commandManager = new CommandManager();
+
+// Register it with the ThreadManager
+threadManager.register( commandManager );
+ ]]>
+ </source>
+ </s1>
+ <s1 title="Running Commands">
+ <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>
+ <source>
+ <![CDATA[
+Sink commandSink = commandManager.getCommandSink();
+commandSink.enqueu( new MySpecialCommand() );
+ ]]>
+ </source>
+ <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>
+ <source>
+ <![CDATA[
+ /**
+ * 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 );
+ }
+ }
+ }
+ }
+ ]]>
+ </source>
+ </s1>
+ </body>
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
+ $Revision$ $Date$
+ </legal>
+ </footer>
+</document>
1.2 +80 -80 jakarta-avalon-excalibur/event/src/xdocs/command.xml
Index: command.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/command.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- command.xml 25 Sep 2002 20:03:56 -0000 1.1
+++ command.xml 23 Oct 2002 13:50:00 -0000 1.2
@@ -1,80 +1,80 @@
-<?xml version="1.0"?>
-
-<document>
- <header>
- <title>Excalibur Event - Command</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="Why Command Was Created">
- <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>
- </s1>
- <s1 title="When To Use Command">
- <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>
- </s1>
- <s1 title="Core Concepts">
- <p>
- Command is built on top of <link href="event.html">Event</link>.
- 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>
- <s2 title="Command">
- <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>
- </s2>
- <s2 title="Command Manager">
- <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>
- </s2>
- <s2 title="Thread Manager">
- <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>
- </s2>
- </s1>
- </body>
- <footer>
- <legal>
- Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision$ $Date$
- </legal>
- </footer>
-</document>
+<?xml version="1.0"?>
+
+<document>
+ <header>
+ <title>Excalibur Event - Command</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="Why Command Was Created">
+ <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>
+ </s1>
+ <s1 title="When To Use Command">
+ <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>
+ </s1>
+ <s1 title="Core Concepts">
+ <p>
+ Command is built on top of <link href="event.html">Event</link>.
+ 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>
+ <s2 title="Command">
+ <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>
+ </s2>
+ <s2 title="Command Manager">
+ <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>
+ </s2>
+ <s2 title="Thread Manager">
+ <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>
+ </s2>
+ </s1>
+ </body>
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
+ $Revision$ $Date$
+ </legal>
+ </footer>
+</document>
1.2 +111 -111 jakarta-avalon-excalibur/event/src/xdocs/cpuparser-howto.xml
Index: cpuparser-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/cpuparser-howto.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- cpuparser-howto.xml 26 Sep 2002 18:34:55 -0000 1.1
+++ cpuparser-howto.xml 23 Oct 2002 13:50:00 -0000 1.2
@@ -1,111 +1,111 @@
-<?xml version="1.0"?>
-
-<document>
- <header>
- <title>Excalibur Event - How To Extend System Util</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="System Util Design">
- <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>
- </s1>
- <s1 title="Writing a CPUParser">
- <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>
- <source>
-<![CDATA[
-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:bloritsch@;apache.org">Berin Loritsch</a>
- * @version CVS $Revision$ $Date$
- */
-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;
- }
-}
-
-]]>
- </source>
- </s1>
- </body>
- <footer>
- <legal>
- Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision$ $Date$
- </legal>
- </footer>
-</document>
+<?xml version="1.0"?>
+
+<document>
+ <header>
+ <title>Excalibur Event - How To Extend System Util</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="System Util Design">
+ <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>
+ </s1>
+ <s1 title="Writing a CPUParser">
+ <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>
+ <source>
+<![CDATA[
+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:bloritsch@;apache.org">Berin Loritsch</a>
+ * @version CVS $Revision$ $Date$
+ */
+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;
+ }
+}
+
+]]>
+ </source>
+ </s1>
+ </body>
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
+ $Revision$ $Date$
+ </legal>
+ </footer>
+</document>
1.4 +225 -225 jakarta-avalon-excalibur/event/src/xdocs/event-howto.xml
Index: event-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/event-howto.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- event-howto.xml 30 Sep 2002 20:49:07 -0000 1.3
+++ event-howto.xml 23 Oct 2002 13:50:00 -0000 1.4
@@ -1,225 +1,225 @@
-<?xml version="1.0"?>
-
-<document>
- <header>
- <title>Excalibur Event - How To Use Event</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="Event is a Framework for Event Processing">
- <p>
- The first thing that you should expect is that Event does not
- <b>do</b> 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>
- </s1>
- <s1 title="Pulling Events From a Source">
- <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>
- <source>
- <![CDATA[
-Object oneEvent = m_mySource.dequeue();
-
-Object[] allEvents = m_mySource.dequeueAll();
-
-Object[] someEvents = m_mySource.dequeue( 10 );
- ]]>
- </source>
- <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>
- <note>
- The dequeue() operation that accepts a number will return <strong>up
- to</strong> that number of events. If there are fewer events in the
- Source, then it will only return that number.
- </note>
- <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>
- <source>
- <![CDATA[
-// Return immediately
-m_mySource.setTimeout( 0 );
-
-// Return after the specified timeout (in milliseconds)
-m_mySource.setTimeout( 250 );
- ]]>
- </source>
- </s1>
- <s1 title="Sending Events to a Sink">
- <p>
- We have several options for enqueuing events into a Sink.
- We have transactional enqueuing, lossy enqueuing, and
- normal enqueuing.
- </p>
- <source>
- <![CDATA[
-// 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 );
-}
- ]]>
- </source>
- <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>
- <source>
- <![CDATA[
-// Determining how many events a Sink can handle
-int numElements = m_mySink.canAccept();
-
-if ( numElements < 0 )
-{
- // This is an unbounded Sink
-}
- ]]>
- </source>
- </s1>
- <s1 title="EventHandlers">
- <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>
- <source>
- <![CDATA[
-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 );
- }
-}
- ]]>
- </source>
- </s1>
- </body>
- <footer>
- <legal>
- Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision$ $Date$
- </legal>
- </footer>
-</document>
+<?xml version="1.0"?>
+
+<document>
+ <header>
+ <title>Excalibur Event - How To Use Event</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="Event is a Framework for Event Processing">
+ <p>
+ The first thing that you should expect is that Event does not
+ <b>do</b> 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>
+ </s1>
+ <s1 title="Pulling Events From a Source">
+ <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>
+ <source>
+ <![CDATA[
+Object oneEvent = m_mySource.dequeue();
+
+Object[] allEvents = m_mySource.dequeueAll();
+
+Object[] someEvents = m_mySource.dequeue( 10 );
+ ]]>
+ </source>
+ <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>
+ <note>
+ The dequeue() operation that accepts a number will return <strong>up
+ to</strong> that number of events. If there are fewer events in the
+ Source, then it will only return that number.
+ </note>
+ <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>
+ <source>
+ <![CDATA[
+// Return immediately
+m_mySource.setTimeout( 0 );
+
+// Return after the specified timeout (in milliseconds)
+m_mySource.setTimeout( 250 );
+ ]]>
+ </source>
+ </s1>
+ <s1 title="Sending Events to a Sink">
+ <p>
+ We have several options for enqueuing events into a Sink.
+ We have transactional enqueuing, lossy enqueuing, and
+ normal enqueuing.
+ </p>
+ <source>
+ <![CDATA[
+// 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 );
+}
+ ]]>
+ </source>
+ <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>
+ <source>
+ <![CDATA[
+// Determining how many events a Sink can handle
+int numElements = m_mySink.canAccept();
+
+if ( numElements < 0 )
+{
+ // This is an unbounded Sink
+}
+ ]]>
+ </source>
+ </s1>
+ <s1 title="EventHandlers">
+ <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>
+ <source>
+ <![CDATA[
+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 );
+ }
+}
+ ]]>
+ </source>
+ </s1>
+ </body>
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
+ $Revision$ $Date$
+ </legal>
+ </footer>
+</document>
1.2 +90 -90 jakarta-avalon-excalibur/event/src/xdocs/event.xml
Index: event.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/event.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- event.xml 25 Sep 2002 18:03:47 -0000 1.1
+++ event.xml 23 Oct 2002 13:50:00 -0000 1.2
@@ -1,90 +1,90 @@
-<?xml version="1.0"?>
-
-<document>
- <header>
- <title>Excalibur Event - Event</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="Why Event Was Created">
- <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
- <fork href="http://seda.sourceforge.net/";>SandStorm</fork>
- server, and cleaned up the API to have Queues operate in a
- more transactional way.
- </p>
- </s1>
- <s1 title="When To Use Event">
- <p>
- Most of the time, your use of the Event package is only to
- interface to other subsystems. For instance, the
- <link href="command.html">Command Manager</link> 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>
- </s1>
- <s1 title="Core Concepts">
- <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>
- <s2 title="Source">
- <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>
- </s2>
- <s2 title="Sink">
- <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>
- </s2>
- <s2 title="Queue">
- <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>
- </s2>
- <s2 title="Signals and Messages">
- <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>
- </s2>
- </s1>
- </body>
- <footer>
- <legal>
- Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision$ $Date$
- </legal>
- </footer>
-</document>
+<?xml version="1.0"?>
+
+<document>
+ <header>
+ <title>Excalibur Event - Event</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="Why Event Was Created">
+ <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
+ <fork href="http://seda.sourceforge.net/";>SandStorm</fork>
+ server, and cleaned up the API to have Queues operate in a
+ more transactional way.
+ </p>
+ </s1>
+ <s1 title="When To Use Event">
+ <p>
+ Most of the time, your use of the Event package is only to
+ interface to other subsystems. For instance, the
+ <link href="command.html">Command Manager</link> 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>
+ </s1>
+ <s1 title="Core Concepts">
+ <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>
+ <s2 title="Source">
+ <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>
+ </s2>
+ <s2 title="Sink">
+ <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>
+ </s2>
+ <s2 title="Queue">
+ <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>
+ </s2>
+ <s2 title="Signals and Messages">
+ <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>
+ </s2>
+ </s1>
+ </body>
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
+ $Revision$ $Date$
+ </legal>
+ </footer>
+</document>
1.13 +28 -28 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.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- menu.xml 30 Sep 2002 20:43:10 -0000 1.12
+++ menu.xml 23 Oct 2002 13:50:00 -0000 1.13
@@ -1,28 +1,28 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project href="http://jakarta.apache.org/avalon/excalibur/event/"; name="Excalibur
Event">
- <title>Excalibur Event</title>
- <body>
-
- <menu name="About">
- <item href="index.html" name="About Event"/>
- <item href="http://jakarta.apache.org/avalon/excalibur/index.html";
name="Excalibur Home"/>
- <item
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";
name="Download"/>
- <item href="api/" name="API Docs"/>
- </menu>
-
- <menu name="Overview">
- <item href="event.html" name="Event"/>
- <item href="command.html" name="Command"/>
- <item href="mpool.html" name="MPool"/>
- <item href="util.html" name="Util"/>
- </menu>
-
- <menu name="How To">
- <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="util-howto.html" name="Use System Util"/>
- <item href="cpuparser-howto.html" name="Extend System Util"/>
- </menu>
- </body>
-</project>
+<?xml version="1.0" encoding="UTF-8"?>
+<project href="http://jakarta.apache.org/avalon/excalibur/event/"; name="Excalibur
Event">
+ <title>Excalibur Event</title>
+ <body>
+
+ <menu name="About">
+ <item href="index.html" name="About Event"/>
+ <item href="http://jakarta.apache.org/avalon/excalibur/index.html";
name="Excalibur Home"/>
+ <item
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";
name="Download"/>
+ <item href="api/" name="API Docs"/>
+ </menu>
+
+ <menu name="Overview">
+ <item href="event.html" name="Event"/>
+ <item href="command.html" name="Command"/>
+ <item href="mpool.html" name="MPool"/>
+ <item href="util.html" name="Util"/>
+ </menu>
+
+ <menu name="How To">
+ <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="util-howto.html" name="Use System Util"/>
+ <item href="cpuparser-howto.html" name="Extend System Util"/>
+ </menu>
+ </body>
+</project>
1.2 +172 -172 jakarta-avalon-excalibur/event/src/xdocs/mpool-howto.xml
Index: mpool-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/mpool-howto.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- mpool-howto.xml 30 Sep 2002 18:34:43 -0000 1.1
+++ mpool-howto.xml 23 Oct 2002 13:50:00 -0000 1.2
@@ -1,172 +1,172 @@
-<?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$ $Date$
- </legal>
- </footer>
-</document>
+<?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$ $Date$
+ </legal>
+ </footer>
+</document>
1.2 +85 -85 jakarta-avalon-excalibur/event/src/xdocs/mpool.xml
Index: mpool.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/mpool.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- mpool.xml 25 Sep 2002 21:20:38 -0000 1.1
+++ mpool.xml 23 Oct 2002 13:50:00 -0000 1.2
@@ -1,85 +1,85 @@
-<?xml version="1.0"?>
-
-<document>
- <header>
- <title>Excalibur Event - MPool (Managed Pool)</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="Why MPool Was Created">
- <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>
- </s1>
- <s1 title="When To Use MPool">
- <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>
- </s1>
- <s1 title="Core Concepts">
- <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>
- <s2 title="Object Factory">
- <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>
- </s2>
- <s2 title="Pool">
- <p>
- The base Pool interface is how the client code interacts with
- the pool. You acquire and release pooled objects from the
- pool.
- </p>
- </s2>
- <s2 title="Managable Pool">
- <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>
- </s2>
- <s2 title="Pool Manager">
- <p>
- The Pool Manager is how you obtain a Managable Pool. It also
- takes care of the management functions for that pool.
- </p>
- </s2>
- </s1>
- </body>
- <footer>
- <legal>
- Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision$ $Date$
- </legal>
- </footer>
-</document>
+<?xml version="1.0"?>
+
+<document>
+ <header>
+ <title>Excalibur Event - MPool (Managed Pool)</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="Why MPool Was Created">
+ <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>
+ </s1>
+ <s1 title="When To Use MPool">
+ <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>
+ </s1>
+ <s1 title="Core Concepts">
+ <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>
+ <s2 title="Object Factory">
+ <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>
+ </s2>
+ <s2 title="Pool">
+ <p>
+ The base Pool interface is how the client code interacts with
+ the pool. You acquire and release pooled objects from the
+ pool.
+ </p>
+ </s2>
+ <s2 title="Managable Pool">
+ <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>
+ </s2>
+ <s2 title="Pool Manager">
+ <p>
+ The Pool Manager is how you obtain a Managable Pool. It also
+ takes care of the management functions for that pool.
+ </p>
+ </s2>
+ </s1>
+ </body>
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
+ $Revision$ $Date$
+ </legal>
+ </footer>
+</document>
1.2 +45 -45 jakarta-avalon-excalibur/event/src/xdocs/util-howto.xml
Index: util-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/util-howto.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- util-howto.xml 26 Sep 2002 18:22:06 -0000 1.1
+++ util-howto.xml 23 Oct 2002 13:50:00 -0000 1.2
@@ -1,45 +1,45 @@
-<?xml version="1.0"?>
-
-<document>
- <header>
- <title>Excalibur Event - How To Use Util</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="Getting the System Info">
- <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>
- <source>
-<![CDATA[
-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() );
-}
-]]>
- </source>
- <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>
- </s1>
- </body>
- <footer>
- <legal>
- Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision$ $Date$
- </legal>
- </footer>
-</document>
+<?xml version="1.0"?>
+
+<document>
+ <header>
+ <title>Excalibur Event - How To Use Util</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="Getting the System Info">
+ <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>
+ <source>
+<![CDATA[
+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() );
+}
+]]>
+ </source>
+ <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>
+ </s1>
+ </body>
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
+ $Revision$ $Date$
+ </legal>
+ </footer>
+</document>
1.2 +64 -64 jakarta-avalon-excalibur/event/src/xdocs/util.xml
Index: util.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/util.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- util.xml 26 Sep 2002 01:01:45 -0000 1.1
+++ util.xml 23 Oct 2002 13:50:00 -0000 1.2
@@ -1,64 +1,64 @@
-<?xml version="1.0"?>
-
-<document>
- <header>
- <title>Excalibur Event - Util</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="Why Util Was Created">
- <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>
- </s1>
- <s1 title="When To Use Util">
- <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>
- </s1>
- <s1 title="Core Concepts">
- <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>
- <s2 title="System Util">
- <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>
- </s2>
- <s2 title="CPU Parser">
- <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
- <a href="mailto:avalon-users@;jakarta.apache.org">the Avalon Users</a>
- 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>
- </s2>
- </s1>
- </body>
- <footer>
- <legal>
- Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision$ $Date$
- </legal>
- </footer>
-</document>
+<?xml version="1.0"?>
+
+<document>
+ <header>
+ <title>Excalibur Event - Util</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="Why Util Was Created">
+ <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>
+ </s1>
+ <s1 title="When To Use Util">
+ <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>
+ </s1>
+ <s1 title="Core Concepts">
+ <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>
+ <s2 title="System Util">
+ <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>
+ </s2>
+ <s2 title="CPU Parser">
+ <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
+ <a href="mailto:avalon-users@;jakarta.apache.org">the Avalon Users</a>
+ 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>
+ </s2>
+ </s1>
+ </body>
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
+ $Revision$ $Date$
+ </legal>
+ </footer>
+</document>
--
To unsubscribe, e-mail: <mailto:avalon-cvs-unsubscribe@;jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@;jakarta.apache.org>
