From seam-commits at lists.jboss.org Fri Jun 12 18:11:37 2009
Content-Type: multipart/mixed; boundary="===============3034174288367280446=="
MIME-Version: 1.0
From: seam-commits at lists.jboss.org
To: seam-commits at lists.jboss.org
Subject: [seam-commits] Seam SVN: r11146 -
 branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US.
Date: Fri, 12 Jun 2009 18:00:27 -0400
Message-ID: <E1MFEnT-0004QZ-NM@committer01.frg.pub.inap.atl.jboss.com>

--===============3034174288367280446==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: dan.j.allen
Date: 2009-06-12 18:00:27 -0400 (Fri, 12 Jun 2009)
New Revision: 11146

Modified:
   branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Jms.xml
Log:
clarify section on JMS with regard to using Seam components


Modified: branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Jms.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Jms.xml	2009=
-06-12 21:59:41 UTC (rev 11145)
+++ branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Jms.xml	2009=
-06-12 22:00:27 UTC (rev 11146)
@@ -9,8 +9,8 @@
     </para>
     =

     <para>
-        But for many use cases, JMS is overkill. Seam layers a simple asyn=
chronous method and event
-        facility over your choice of <emphasis>dispatchers</emphasis>:
+        But for cases when you are simply want to use a worker thread, JMS=
 is overkill. Seam layers a simple
+        asynchronous method and event facility over your choice of <emphas=
is>dispatchers</emphasis>:
     </para>
     =

     <itemizedlist>
@@ -30,6 +30,198 @@
             </para>
         </listitem>
     </itemizedlist>
+
+    <para>
+        This chapter first covers how to leverage Seam to simplify JMS and=
 then explains how to use the
+        simpler asynchronous method and event facility.
+    </para>
+    =

+    <sect1>
+    <title>Messaging in Seam</title>
+    =

+    <para>
+        Seam makes it easy to send and receive JMS messages to and from
+        Seam components. Both the message publisher and the message receiv=
er
+        can be Seam components.
+    </para>
+
+    <para>
+        You'll first learn to setup a queue and topic message publisher an=
d then =

+        look at an example that illustrates how to perform the message exc=
hange.
+    </para>
+    =

+    <sect2>
+        <title>Configuration</title>
+        <para>
+            To configure Seam's infrastructure for sending JMS messages,
+            you need to tell Seam about any topics and queues you want to
+            send messages to, and also tell Seam where to find the
+            <literal>QueueConnectionFactory</literal> and/or
+            <literal>TopicConnectionFactory</literal>.
+        </para>
+        =

+        <para>
+            Seam defaults to using <literal>UIL2ConnectionFactory</literal>
+            which is the usual connection factory for use with JBossMQ. If
+            you are using some other JMS provider, you need to set one or
+            both of <literal>queueConnection.queueConnectionFactoryJndiNam=
e</literal>
+            and <literal>topicConnection.topicConnectionFactoryJndiName</l=
iteral>
+            in <literal>seam.properties</literal>, <literal>web.xml</liter=
al>
+            or <literal>components.xml</literal>.
+        </para>
+        =

+        <para>
+            You also need to list topics and queues in <literal>components=
.xml</literal>
+            to install Seam managed <literal>TopicPublisher</literal>s and
+            <literal>QueueSender</literal>s:
+        </para>
+        =

+        <programlisting role=3D"XML"><![CDATA[<jms:managed-topic-publisher=
 name=3D"stockTickerPublisher" =

+                             auto-create=3D"true" =

+                             topic-jndi-name=3D"topic/stockTickerTopic"/>
+
+<jms:managed-queue-sender name=3D"paymentQueueSender" =

+                          auto-create=3D"true" =

+                          queue-jndi-name=3D"queue/paymentQueue"/>]]></pro=
gramlisting>
+
+    </sect2>
+
+    <sect2>
+        <title>Sending messages</title>
+        <para>
+            Now, you can inject a JMS <literal>TopicPublisher</literal> and
+            <literal>TopicSession</literal> into any Seam component to pub=
lish
+            an object to a topic:
+        </para>
+        =

+        <programlisting role=3D"JAVA"><![CDATA[@Name("stockPriceChangeNoti=
fier")
+public class StockPriceChangeNotifier
+{
+   @In private TopicPublisher stockTickerPublisher;   =

+
+   @In private TopicSession topicSession;
+
+   public void publish(StockPrice price)
+   {
+        try
+        {
+           stockTickerPublisher.publish(topicSession.createObjectMessage(p=
rice));
+        } =

+        catch (Exception ex)
+        {
+           throw new RuntimeException(ex);
+        } =

+   }
+}]]></programlisting>
+
+        <para>or to a queue:</para>
+
+        <programlisting role=3D"JAVA"><![CDATA[@Name("paymentDispatcher")
+public class PaymentDispatcher
+{
+   @In private QueueSender paymentQueueSender;   =

+    =

+   @In private QueueSession queueSession;
+    =

+   public void publish(Payment payment)
+   {
+      try
+      {
+         paymentQueueSender.send(queueSession.createObjectMessage(payment)=
);
+      } =

+      catch (Exception ex)
+      {
+         throw new RuntimeException(ex);
+      } =

+   }
+}]]></programlisting>
+
+    </sect2>
+    =

+    <sect2>
+        <title>Receiving messages using a message-driven bean</title>
+        <para>
+            You can process messages using any EJB 3 message-driven bean. =
The MDB
+            can even be a Seam component, in which case it's possible to i=
nject
+            other event- and application- scoped Seam components. Here's a=
n example
+            of the payment receiver, which delegates to a payment processo=
r.
+        </para>    =

+        <note>
+            <para>
+                You'll likely need to set the create attribute on the <lit=
eral>@In</literal> annotation to true (i.e.
+                create =3D true) to have Seam create an instance of the co=
mponent being injected. This isn't necessary if
+                the component supports auto-creation (e.g., it's annotated=
 with <literal>@Autocreate</literal>).
+            </para>
+        </note>
+
+        <para>
+            First, create an MDB to receive the message.
+        </para>
+
+        <programlisting role=3D"JAVA"><![CDATA[@MessageDriven(activationCo=
nfig =3D {
+    @ActivationConfigProperty(
+        propertyName =3D "destinationType",
+        propertyValue =3D "javax.jms.Queue"
+    ),
+    @ActivationConfigProperty(
+        propertyName =3D "destination",
+        propertyValue =3D "queue/paymentQueue"
+    )
+})
+(a)Name("paymentReceiver")
+public class PaymentReceiver implements MessageListener
+{
+   @Logger private Log log;
+
+   @In(create =3D true) private PaymentProcessor paymentProcessor;
+    =

+   @Override
+   public void onMessage(Message message)
+   {
+      try
+      {
+         paymentProcessor.processPayment((Payment) ((ObjectMessage) messag=
e).getObject());
+      } =

+      catch (JMSException ex)
+      {
+         log.error("Message payload did not contain a Payment object", ex);
+      } =

+   }
+}]]></programlisting>
+
+        <para>
+            Then, implement the Seam component to which the receiver deleg=
ates processing of the payment.
+        </para>
+
+        <programlisting role=3D"JAVA"><![CDATA[@Name("paymentProcessor")
+public class PaymentProcessor
+{
+   @In private EntityManager entityManager;
+
+   public void processPayment(Payment payment)
+   {
+      // perhaps do something more fancy
+      entityManager.persist(payment);
+   }
+}]]></programlisting>
+
+        <para>
+            If you are going to be performing transaction operations in yo=
ur MDB, you should ensure that you
+            are working with an XA datasource. Otherwise, it won't be poss=
ible to rollback database changes
+            if the database transaction commits and a subsequent operation=
 being performed by the message
+            fails.
+        </para>
+    </sect2>
+    =

+    <sect2>
+        <title>Receiving messages in the client</title>
+        <para>
+            Seam Remoting lets you subscribe to a JMS topic from client-si=
de JavaScript. This is
+            described in <xref linkend=3D"remoting"/>.
+        </para>
+    </sect2>
+    =

+    </sect1>
             =

     <sect1>
         <title>Asynchronicity</title>
@@ -412,110 +604,4 @@
         </sect2>
 =

     </sect1>
-    =

-    <sect1>
-    <title>Messaging in Seam</title>
-    =

-    <para>
-        Seam makes it easy to send and receive JMS messages to and from
-        Seam components.
-    </para>
-    =

-    <sect2>
-        <title>Configuration</title>
-        <para>
-            To configure Seam's infrastructure for sending JMS messages,
-            you need to tell Seam about any topics and queues you want to
-            send messages to, and also tell Seam where to find the
-            <literal>QueueConnectionFactory</literal> and/or
-            <literal>TopicConnectionFactory</literal>.
-        </para>
-        =

-        <para>
-            Seam defaults to using <literal>UIL2ConnectionFactory</literal>
-            which is the usual connection factory for use with JBossMQ. If
-            you are using some other JMS provider, you need to set one or
-            both of <literal>queueConnection.queueConnectionFactoryJndiNam=
e</literal>
-            and <literal>topicConnection.topicConnectionFactoryJndiName</l=
iteral>
-            in <literal>seam.properties</literal>, <literal>web.xml</liter=
al>
-            or <literal>components.xml</literal>.
-        </para>
-        =

-        <para>
-            You also need to list topics and queues in <literal>components=
.xml</literal>
-            to install Seam managed <literal>TopicPublisher</literal>s and
-            <literal>QueueSender</literal>s:
-        </para>
-        =

-        <programlisting role=3D"XML"><![CDATA[<jms:managed-topic-publisher=
 name=3D"stockTickerPublisher" =

-                             auto-create=3D"true" =

-                             topic-jndi-name=3D"topic/stockTickerTopic"/>
-
-<jms:managed-queue-sender name=3D"paymentQueueSender" =

-                          auto-create=3D"true" =

-                          queue-jndi-name=3D"queue/paymentQueue"/>]]></pro=
gramlisting>
-
-    </sect2>
-
-    <sect2>
-        <title>Sending messages</title>
-        <para>
-            Now, you can inject a JMS <literal>TopicPublisher</literal> and
-            <literal>TopicSession</literal> into any component:
-        </para>
-        =

-        <programlisting role=3D"JAVA"><![CDATA[@In =

-private TopicPublisher stockTickerPublisher;   =

-(a)In =

-private TopicSession topicSession;
-
-public void publish(StockPrice price) {
-      try
-      {
-         stockTickerPublisher.publish( topicSession.createObjectMessage(pr=
ice) );
-      } =

-      catch (Exception ex)
-      {
-         throw new RuntimeException(ex);
-      } =

-}]]></programlisting>
-
-        <para>Or, for working with a queue:</para>
-
-        <programlisting role=3D"JAVA"><![CDATA[@In
-private QueueSender paymentQueueSender;   =

-(a)In
-private QueueSession queueSession;
-
-public void publish(Payment payment) {
-      try
-      {
-         paymentQueueSender.send( queueSession.createObjectMessage(payment=
) );
-      } =

-      catch (Exception ex)
-      {
-         throw new RuntimeException(ex);
-      } =

-}]]></programlisting>
-
-    </sect2>
-    =

-    <sect2>
-        <title>Receiving messages using a message-driven bean</title>
-        <para>
-            You can process messages using any EJB3 message driven bean. M=
essage-driven
-            beans may even be Seam components, in which case it is possibl=
e to inject
-            other event and application scoped Seam components.
-        </para>
-    </sect2>
-    =

-    <sect2>
-        <title>Receiving messages in the client</title>
-        <para>
-            Seam Remoting lets you subscribe to a JMS topic from client-si=
de JavaScript. This is
-            described in <xref linkend=3D"remoting"/>.
-        </para>
-    </sect2>
-    =

-    </sect1>
 </chapter>


--===============3034174288367280446==--