[jboss-cvs] JBossAS SVN: r105604 - projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Jun 2 18:44:21 EDT 2010
Author: misty at redhat.com
Date: 2010-06-02 18:44:21 -0400 (Wed, 02 Jun 2010)
New Revision: 105604
Modified:
projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Jms.xml
Log:
JBPAPP-4387
Modified: projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Jms.xml
===================================================================
--- projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Jms.xml 2010-06-02 22:41:19 UTC (rev 105603)
+++ projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Jms.xml 2010-06-02 22:44:21 UTC (rev 105604)
@@ -34,7 +34,7 @@
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 are working in an environment that supports EJB 3.0, add the following line to <filename>components.xml</filename> to ensure that your asynchronous tasks are processed by the container's EJB timer service:
</para>
-<programlisting role="XML"><![CDATA[<async:timer-service-dispatcher/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<async:timer-service-dispatcher/>]]>
</programlisting>
<para>
If you want to use asynchronous methods in Seam, you do not need to interact directly with the Timer service. However, it is important that your EJB3 implementation has the option of using persistent timers, which give some guarantee that the task will eventually be processed.
@@ -43,7 +43,7 @@
Alternatively, you can use the open source Quartz library to manage asynchronous method. To do so, bundle the Quartz library <filename>JAR</filename> (found in the <literal>lib</literal> directory) in your <filename>EAR</filename>, and declare it as a Java module in <filename>application.xml</filename>. You can configure the Quartz dispatcher by adding a Quartz property file to the classpath —this file must be named <filename>seam.quartz.properties</filename>. To install the Quartz dispatcher, you will also need to add the following line to <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<async:quartz-dispatcher/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<async:quartz-dispatcher/>]]>
</programlisting>
<para>
Since the Seam API for the default <literal>ScheduledThreadPoolExecutor</literal>, the EJB3 <literal>Timer</literal>, and the Quartz <literal>Scheduler</literal> are very similar, you can "plug and play" by adding a line to <filename>components.xml</filename>. <!-- #modify: What line can you add? -->
@@ -57,7 +57,7 @@
For EJB components, annotate the implementation of the bean to specify that a method be processed asynchronously. For JavaBean components, annotate the component implementation class:
</para>
-<programlisting role="JAVA"><![CDATA[@Stateless
+<programlisting language="Java" role="JAVA">@Stateless
@Name("paymentHandler")
public class PaymentHandlerBean implements PaymentHandler
{
@@ -65,13 +65,13 @@
public void processPayment(Payment payment) {
//do some work!
}
-}]]>
+}
</programlisting>
<para>
Asynchronicity is transparent to the bean class. It is also transparent to the client:
</para>
-<programlisting role="JAVA"><![CDATA[@Stateful
+<programlisting language="Java" role="JAVA">@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
@@ -82,7 +82,7 @@
paymentHandler.processPayment( new Payment(bill) );
return "success";
}
-}]]>
+}
</programlisting>
<para>
The asynchronous method is processed in a fresh event context, and has no access to the session or conversation context state of the caller. However, the business process context <emphasis>is</emphasis> propagated.
@@ -91,7 +91,7 @@
You can schedule asynchronous method calls for delayed execution with the <literal>@Duration</literal>, <literal>@Expiration</literal> and <literal>@IntervalDuration</literal> annotations.
</para>
-<programlisting role="JAVA"><![CDATA[@Local
+<programlisting language="Java" role="JAVA">@Local
public interface PaymentHandler {
@Asynchronous
public void processScheduledPayment(Payment payment,
@@ -101,10 +101,10 @@
public void processRecurringPayment(Payment payment,
@Expiration Date date,
@IntervalDuration Long interval);
-}]]>
+}
</programlisting>
-<programlisting role="JAVA"><![CDATA[@Stateful
+<programlisting language="Java" role="JAVA">@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
@@ -122,22 +122,22 @@
bill.getDueDate(), ONE_MONTH );
return "success";
}
-}]]>
+}
</programlisting>
<para>
Both client and server can access the <literal>Timer</literal> object associated with the invocation. The <literal>Timer</literal> shown below is the EJB3 timer used with the EJB3 dispatcher. For the default <literal>ScheduledThreadPoolExecutor</literal>, the timer returns <literal>Future</literal> from the JDK. For the Quartz dispatcher, it returns <literal>QuartzTriggerHandle</literal>, which will be discussed in the next section.
</para>
-<programlisting role="JAVA"><![CDATA[@Local
+<programlisting language="Java" role="JAVA">@Local
public interface PaymentHandler
{
@Asynchronous
public Timer processScheduledPayment(Payment payment,
@Expiration Date date);
-}]]>
+}
</programlisting>
-<programlisting role="JAVA"><![CDATA[@Stateless
+<programlisting language="Java" role="JAVA">@Stateless
@Name("paymentHandler")
public class PaymentHandlerBean implements PaymentHandler {
@In Timer timer;
@@ -147,10 +147,10 @@
//do some work!
return timer; //note that return value is completely ignored
}
-}]]>
+}
</programlisting>
-<programlisting role="JAVA"><![CDATA[@Stateful
+<programlisting language="Java" role="JAVA">@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
@@ -163,7 +163,7 @@
bill.getDueDate());
return "success";
}
-}]]>
+}
</programlisting>
<para>
Asynchronous methods cannot return any other value to the caller.
@@ -179,7 +179,7 @@
The <literal>@FinalExpiration</literal> annotation specifies an end date for a recurring task. Note that you can inject the <code>QuartzTriggerHandle</code>.
</para>
-<programlisting role="JAVA"><![CDATA[@In QuartzTriggerHandle timer;
+<programlisting language="Java" role="JAVA">@In QuartzTriggerHandle timer;
// Defines the method in the "processor" component
@Asynchronous
@@ -196,13 +196,13 @@
// Starts now, repeats every hour, and ends on May 10th, 2010
Calendar cal = Calendar.getInstance ();
cal.set (2010, Calendar.MAY, 10);
-processor.schedulePayment(new Date(), 60*60*1000, cal.getTime(), payment);]]>
+processor.schedulePayment(new Date(), 60*60*1000, cal.getTime(), payment);
</programlisting>
<para>
Note that this method returns the <literal>QuartzTriggerHandle</literal> object, which can be used to stop, pause, and resume the scheduler. The <literal>QuartzTriggerHandle</literal> object is serializable, so it can be saved into the database if required for an extended period of time.
</para>
-<programlisting role="JAVA"><![CDATA[QuartzTriggerHandle handle=
+<programlisting language="Java" role="JAVA">QuartzTriggerHandle handle=
processor.schedulePayment(payment.getPaymentDate(),
payment.getPaymentCron(),
payment);
@@ -213,13 +213,13 @@
// Retrieve payment from DB
// Cancel the remaining scheduled tasks
-payment.getQuartzTriggerHandle().cancel();]]>
+payment.getQuartzTriggerHandle().cancel();
</programlisting>
<para>
The <literal>@IntervalCron</literal> annotation supports Unix cron job syntax for task scheduling. For example, the following asynchronous method runs at 2:10pm and at 2:44pm every Wednesday in the month of March.
</para>
-<programlisting role="JAVA"><![CDATA[// Define the method
+<programlisting language="Java" role="JAVA">// Define the method
@Asynchronous
public QuartzTriggerHandle schedulePayment(@Expiration Date when,
@IntervalCron String cron,
@@ -232,13 +232,12 @@
// Schedule the task in the business logic processing code
QuartzTriggerHandle handle =
processor.schedulePayment(new Date(), "0 10,44 14 ? 3 WED", payment);
-]]>
</programlisting>
<para>
The <literal>@IntervalBusinessDay</literal> annotation supports invocation in the "nth Business Day" scenario. For instance, the following asynchronous method runs at 14:00 on the 2nd business day of each month. All weekends and US Federal holidays are excluded from the business days by default.
</para>
-<programlisting role="JAVA"><![CDATA[// Define the method
+<programlisting language="Java" role="JAVA">// Define the method
@Asynchronous
public QuartzTriggerHandle schedulePayment(@Expiration Date when,
@IntervalBusinessDay NthBusinessDay nth,
@@ -253,16 +252,15 @@
processor.schedulePayment(new Date(),
new NthBusinessDay(2, "14:00", WEEKLY),
payment);
-]]>
</programlisting>
<para>
The <literal>NthBusinessDay</literal> object contains the configuration of the invocation trigger. You can specify more holidays (company holidays and non-US holidays, for example) in the <literal>additionalHolidays</literal> property.
</para>
-<programlisting role="JAVA"><![CDATA[public class NthBusinessDay implements Serializable {
+<programlisting language="Java" role="JAVA">public class NthBusinessDay implements Serializable {
int n;
String fireAtTime;
- List<Date> additionalHolidays;
+ List<Date> additionalHolidays;
BusinessDayIntervalType interval;
boolean excludeWeekends;
boolean excludeUsFederalHolidays;
@@ -272,14 +270,13 @@
public NthBusinessDay () {
n = 1;
fireAtTime = "12:00";
- additionalHolidays = new ArrayList<Date> ();
+ additionalHolidays = new ArrayList<Date> ();
interval = BusinessDayIntervalType.WEEKLY;
excludeWeekends = true;
excludeUsFederalHolidays = true;
}
... ...
}
-]]>
</programlisting>
<para>
The <literal>@IntervalDuration</literal>, <literal>@IntervalCron</literal>, and <literal>@IntervalNthBusinessDay</literal> annotations are mutually exclusive. Attempting to use them in the same method will cause a <exceptionname>RuntimeException</exceptionname> error.
@@ -302,7 +299,7 @@
By default, any exception that propagates from an asynchronous execution will be caught and logged at error level. You can customize this behavior globally by overriding the <literal>org.jboss.seam.async.asynchronousExceptionHandler</literal> component:
</para>
-<programlisting role="JAVA"><![CDATA[@Scope(ScopeType.STATELESS)
+<programlisting language="Java" role="JAVA">@Scope(ScopeType.STATELESS)
@Name("org.jboss.seam.async.asynchronousExceptionHandler")
public class MyAsynchronousExceptionHandler
extends AsynchronousExceptionHandler {
@@ -316,7 +313,7 @@
timer.cancel(false);
}
-}]]>
+}
</programlisting>
<para>
Here, with <literal>java.util.concurrent</literal> dispatcher, we inject its control object and cancel all future invocations when an exception is encountered.
@@ -325,10 +322,10 @@
You can alter this behavior for an individual component by implementing the <literal>public void handleAsynchronousException(Exception exception);</literal> method on that component, like so:
</para>
-<programlisting role="JAVA"><![CDATA[
+<programlisting language="Java" role="JAVA">
public void handleAsynchronousException(Exception exception) {
log.fatal(exception);
-}]]>
+}
</programlisting>
</section>
@@ -351,7 +348,7 @@
To install Seam-managed <literal>TopicPublisher</literal>s and <literal>QueueSender</literal>s, you must also list topics and queues in <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<jms:managed-topic-publisher name="stockTickerPublisher"
+<programlisting language="XML" role="XML"><![CDATA[<jms:managed-topic-publisher name="stockTickerPublisher"
auto-create="true" topic-jndi-name="topic/stockTickerTopic"/>
<jms:managed-queue-sender name="paymentQueueSender"
@@ -365,7 +362,7 @@
Once configuration is complete, you can inject a JMS <literal>TopicPublisher</literal> and <literal>TopicSession</literal> into any component:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("stockPriceChangeNotifier")
+<programlisting language="Java" role="JAVA">@Name("stockPriceChangeNotifier")
public class StockPriceChangeNotifier {
@In private TopicPublisher stockTickerPublisher;
@@ -379,13 +376,13 @@
throw new RuntimeException(ex);
}
}
-}]]>
+}
</programlisting>
<para>
Or, to work with a queue:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("paymentDispatcher")
+<programlisting language="Java" role="JAVA">@Name("paymentDispatcher")
public class PaymentDispatcher {
@In private QueueSender paymentQueueSender;
@@ -398,7 +395,7 @@
throw new RuntimeException(ex);
}
}
-}]]>
+}
</programlisting>
</section>
@@ -416,7 +413,7 @@
First, create a message-driven bean to receive the message:
</para>
- <programlisting role="JAVA"><![CDATA[@MessageDriven(activationConfig =
+ <programlisting language="Java" role="JAVA">@MessageDriven(activationConfig =
{@ActivationConfigProperty(propertyName = "destinationType",
propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination",
@@ -440,13 +437,13 @@
log.error("Message payload did not contain a Payment object", ex);
}
}
-}]]></programlisting>
+}</programlisting>
<para>
Next, implement the Seam component to which the receiver will delegate payment processing:
</para>
- <programlisting role="JAVA"><![CDATA[@Name("paymentProcessor")
+ <programlisting language="Java" role="JAVA">@Name("paymentProcessor")
public class PaymentProcessor {
@In private EntityManager entityManager;
@@ -454,7 +451,7 @@
// perhaps do something more fancy
entityManager.persist(payment);
}
-}]]></programlisting>
+}</programlisting>
<para>
If you want to perform transaction operations in your message-driven bean, ensure that you are working with an XA datasource, or you will not be able to roll back database changes in the event that a database transaction commits, but a subsequent message operation fails.
More information about the jboss-cvs-commits
mailing list