bloritsch 2002/09/30 13:43:10
Modified: event/src/xdocs event-howto.xml index.xml menu.xml
Log:
last remaining docs for MPool
Revision Changes Path
1.2 +174 -23 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- event-howto.xml 30 Sep 2002 18:34:43 -0000 1.1
+++ event-howto.xml 30 Sep 2002 20:43:09 -0000 1.2
@@ -2,35 +2,186 @@
<document>
<header>
- <title>Excalibur Event - Overview</title>
+ <title>Excalibur Event - How To Use Event</title>
<authors>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
- <s1 title="Introduction">
+ <s1 title="Event is a Framework for Event Processing">
<p>
- This is the Excalibur Event package which includes event queues,
- asynchronous command processing, and the interfaces to support
- event based programming. Event is heavily influenced by Matt
- Welsh's work with the
- <fork href="http://www.cs.berkeley.edu/~mdw/proj/seda/";>SEDA
architecture</fork>.
- We forked the portion of his SandStorm server that had to do with
- event processing. From there we cleaned up the API and made it as
- generic as we could.
- </p>
- <p>
- The Event package actually has five related sub packages inside
- of it. Event is the basic interfaces for the Queues, Sinks,
- Sources, etc. Command houses code for the CommandManager so that
- your code can safely process Commands (a type of event) in the
- background. MPool, short for Managed Pool, houses code for a
- pool implementation that manages its size asynchronously so you
- don't have to worry about it. Thread is the thread pool code
- which uses MPool to keep track of the threads. Lastly, Util
- provides some basic utilities so that we can programatically
- determine the number of processors your hardware has.
+ 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>
</body>
<footer>
1.6 +4 -5 jakarta-avalon-excalibur/event/src/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/index.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- index.xml 25 Sep 2002 18:03:47 -0000 1.5
+++ index.xml 30 Sep 2002 20:43:10 -0000 1.6
@@ -26,10 +26,9 @@
your code can safely process Commands (a type of event) in the
background. MPool, short for Managed Pool, houses code for a
pool implementation that manages its size asynchronously so you
- don't have to worry about it. Thread is the thread pool code
- which uses MPool to keep track of the threads. Lastly, Util
- provides some basic utilities so that we can programatically
- determine the number of processors your hardware has.
+ don't have to worry about it. Lastly, Util provides some basic
+ utilities so that we can programatically determine the number
+ of processors your hardware has.
</p>
</s1>
</body>
1.12 +0 -2 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.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- menu.xml 30 Sep 2002 18:34:43 -0000 1.11
+++ menu.xml 30 Sep 2002 20:43:10 -0000 1.12
@@ -18,9 +18,7 @@
</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"/>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
