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

[Michael Yuan]

  User: myuan   
  Date: 07/06/12 12:00:53

  Modified:    doc/reference/en/modules  jms.xml
  Log:
  adds a little doc about Quartz
  
  Revision  Changes    Path
  1.16      +51 -1     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.15
  retrieving revision 1.16
  diff -u -b -r1.15 -r1.16
  --- jms.xml	3 Jun 2007 01:37:34 -0000	1.15
  +++ jms.xml	12 Jun 2007 16:00:53 -0000	1.16
  @@ -53,6 +53,17 @@
               which gives some guarantee that the tasks will eventually be processed.
           </para>
           
  +        <para>
  +            Another alternative is to use the open source Quartz library to manage asynchronous method. You need to bundle the Quartz library JAR (found in the <literal>lib</literal> directory) in your EAR and declare it as a Java module in <literal>application.xml</literal>. In addition, you need to add the following line to <literal>components.xml</literal> to install the Quartz dispatcher.
  +        </para>
  +        
  +        <programlisting><![CDATA[<component name="org.jboss.seam.core.dispatcher" 
  +        class="org.jboss.seam.core.QuartzDispatcher"/>]]></programlisting>
  +            
  +        <para>
  +            The Seam API for the default <literal>ScheduledThreadPoolExecutor</literal>, the EJB3 <literal>Timer</literal>, and the Quartz <literal>Scheduler</literal> are largely the same. They can just "plug and play" by adding a line to <literal>components.xml</literal> as we shown above.
  +        </para>
  +        
           <sect2>
           <title>Asynchronous methods</title>
           
  @@ -159,7 +170,7 @@
   
           <para>
               Both client and server may access the <literal>Timer</literal> object associated with
  -            the invocation.
  +            the invocation. The <literal>Timer</literal> object shown below is the EJB3 timer when you use the EJB3 dispatcher. For the default <literal>ScheduledThreadPoolExecutor</literal>, the returned object is <literal>Future</literal> from the JDK. For the Quartz dispatcher, it returns <literal>QuartzTriggerHandle</literal>, which we will discuss in the next section.
           </para>
   
           <programlisting><![CDATA[@Local
  @@ -206,6 +217,45 @@
           </sect2>
           
           <sect2>
  +        <title>Asynchronous methods with the Quartz Dispatcher</title>
  +        
  +        <para>
  +            The Quartz dispatcher (see earlier on how to install it) allows you to use the <literal>@Asynchronous</literal>, <literal>@Duration</literal>, <literal>@Expiration</literal>, and <literal>@IntervalDuration</literal> annotations as above. But it has some powerful additional features. The Quartz dispatcher supports a new <literal>@Cron</literal> annotation that supports Unix cron job syntax for task scheduling. For instance, the following asynchronous method runs at 2:10pm and at 2:44pm every Wednesday in the month of March.
  +        </para>
  +        
  +        <programlisting><![CDATA[String cron = "0 10,44 14 ? 3 WED";
  +    ... ...
  +    
  +    @Asynchronous
  +    public QuartzTriggerHandle schedulePayment(@Expiration Date when, 
  +                                 @Cron String cron, 
  +                                 Payment payment) 
  +    { 
  +        // do the repeating or long running task
  +    }
  +]]></programlisting>
  +
  +        <para>The <literal>@Cron</literal> annotation and the <literal>@IntervalDuration</literal> annotation are mutually exclusive. If they are used in the same method, the <literal>@Cron</literal> annotation will be used, and the <literal>@IntervalDuration</literal> discarded.</para>
  +
  +        <para>Note that the method returns the <literal>QuartzTriggerHandle</literal> object, which you can use later to stop, pause, and resume the scheduler. The <literal>QuartzTriggerHandle</literal> object is serializable, so you can save it into the database if you need to keep it around for extended period of time.</para>
  +        
  +        <programlisting><![CDATA[QuartzTriggerHandle handle =
  +         processor.schedulePayment(payment.getPaymentDate(), 
  +                                   payment.getPaymentCron(), 
  +                                   payment);
  +        payment.setQuartzTriggerHandle( handle );
  +        // Save payment to DB
  +        
  +        // later ...
  +        
  +        // Retrieve payment from DB
  +        // Cancel the remaining scheduled tasks
  +        payment.getQuartzTriggerHandle().cancel();
  +]]></programlisting>
  +        
  +        </sect2>
  +        
  +        <sect2>
               <title>Asynchronous events</title>
               <para>
                   Component-driven events may also be asynchronous. To raise an event for asynchronous