avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From blorit...@apache.org
Subject cvs commit: jakarta-avalon-excalibur/event/src/xdocs event-howto.xml index.xml menu.xml
Date Mon, 30 Sep 2002 20:43:10 GMT
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="bloritsch@apache.org"/>
       </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:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message