[jboss-cvs] jboss-seam/doc/reference/en/modules ...

[Gavin King]

  User: gavin   
  Date: 07/06/02 21:37:34

  Modified:    doc/reference/en/modules  jms.xml
  Log:
  JBSEAM-1376
  
  Revision  Changes    Path
  1.15      +42 -22    jboss-seam/doc/reference/en/modules/jms.xml
  
  (In the diff below, changes in quantity of whitespace are not shown.)
  
  Index: jms.xml
  ===================================================================
  RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/jms.xml,v
  retrieving revision 1.14
  retrieving revision 1.15
  diff -u -b -r1.14 -r1.15
  --- jms.xml	29 May 2007 19:52:05 -0000	1.14
  +++ jms.xml	3 Jun 2007 01:37:34 -0000	1.15
  @@ -10,28 +10,47 @@
       
       <para>
           But for many usecases, JMS is overkill. Seam layers a simple asynchronous method and event
  -        facility over the EJB 3.0 timer service.
  +        facility over your choice of <emphasis>dispatchers</emphasis>:
       </para>
           
  -    <sect1>
  -        <title>Asynchronicity</title>
  -
  +    <itemizedlist>
  +        <listitem>
           <para>
  -            Asynchronous events and method calls have the same quality of service expectations as the 
  -            container's EJB timer service. If you're not familiar with the Timer service, don't worry,
  -            you don't need to interact with it directly if you want to use asynchronous methods in
  -            Seam.
  +                <literal>java.util.concurrent.ScheduledThreadPoolExecutor</literal> (by default)
           </para>
  -        
  +        </listitem>
  +        <listitem>
           <para>
  -            To use asynchronous methods and events, you need to add the following line to
  -            <literal>components.xml</literal>:
  +                the EJB timer service (for EJB 3.0 environments)
           </para>
  +        </listitem>
  +        <listitem>
  +            <para>
  +                Quartz
  +            </para>
  +        </listitem>
  +    </itemizedlist>
           
  -        <programlisting><![CDATA[<core:dispatcher/>]]></programlisting>
  +    <sect1>
  +        <title>Asynchronicity</title>
           
           <para>
  -            Note that this functionality is not available in environments which do not support EJB 3.0.
  +            Asynchronous events and method calls have the same quality of service expectations as  
  +            the underlying dispatcher mechanism. The default dispatcher, based upon a 
  +            <literal>ScheduledThreadPoolExecutor</literal> performs efficiently but provides no
  +            support for persistent asynchronous tasks, and hence no guarantee that a task
  +            will ever actually be executed. If you're working in an environment that supports
  +            EJB 3.0, and add the following line to <literal>components.xml</literal>:
  +        </para>
  +        
  +        <programlisting><![CDATA[<core:timer-service-dispatcher/>]]></programlisting>
  +        
  +        <para>
  +            then your asynchronous tasks will be processed by the container's EJB timer service. If 
  +            you're not familiar with the Timer service, don't worry, you don't need to interact with 
  +            it directly if you want to use asynchronous methods in Seam. The important thing to know
  +            is that any good EJB 3.0 implementation will have the option of using persistent timers, 
  +            which gives some guarantee that the tasks will eventually be processed.
           </para>
           
           <sect2>
  @@ -190,11 +209,12 @@
               <title>Asynchronous events</title>
               <para>
                   Component-driven events may also be asynchronous. To raise an event for asynchronous
  -                processing, simply call the <literal>raiseAsynchronousEvent()</literal> methods of 
  -                the <literal>Events</literal> class. To schedule a timed event, call one of the 
  -                <literal>raiseTimedEvent()</literal> methods. Components may observe asynchronous
  -                events in the usual way, but remember that only the business process context is
  -                propagated to the asynchronous thread.
  +                processing, simply call the <literal>raiseAsynchronousEvent()</literal> method of 
  +                the <literal>Events</literal> class. To schedule a timed event, call the
  +                <literal>raiseTimedEvent()</literal> method, passing a <emphasis>schedule</emphasis>
  +                object (for the default dispatcher or timer service dispatcher, use <literal>TimerSchedule</literal>). 
  +                Components may observe asynchronous events in the usual way, but remember that only the 
  +                business process context is propagated to the asynchronous thread.
               </para>
           </sect2>