[jbpm-commits] JBoss JBPM SVN: r6020 - jbpm4/trunk/modules/devguide/src/main/docbook/en/modules.

[do-not-reply at jboss.org]

Author: tom.baeyens at jboss.com
Date: 2009-12-22 10:38:01 -0500 (Tue, 22 Dec 2009)
New Revision: 6020

Modified:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
Log:
JBPM-2695 added jms testing docs

Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml	2009-12-22 15:10:53 UTC (rev 6019)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml	2009-12-22 15:38:01 UTC (rev 6020)
@@ -894,12 +894,24 @@
       </tgroup>
     </table>
     
-    <para>
-      The <literal>connection-factory</literal> and <literal>destination</literal> attributes are 
+    <para>There are 3 types of JMS messages that you can send to to the destination: text, object 
+      and map.  The <literal>connection-factory</literal> and <literal>destination</literal> attributes are 
       mandatory and respectively contain the names of the connection factory and destination (queue or topic) 
-      that will be used to lookup the corresponding objects in jndi. The specified message will be sent
-      to the destination that was obtained by this lookup.
+      that will be used to lookup the corresponding objects in JNDI.   The lookup is done like this:
     </para>
+    <programlisting>InitialContext initialContext = new InitialContext();
+Destination destination = (Destination) initialContext.lookup(destinationName);</programlisting>
+    <para>So if you're running inside an appserver, then the <literal>new InitialContext()</literal> 
+    will see the queue's and topics configured in the appserver.</para>
+    <para>When your're using the JMS mocking 
+    in standalone test mode, then the queues and topics that you created with <literal>JbpmTestCase.jmsCreateQueue</literal>  
+    and <literal>JbpmTestCase.jmsCreateTopic</literal> will be available.</para>
+    <para>When you're running as a remote application client, then you have to 
+    <ulink url="http://java.sun.com/products/jndi/tutorial/beyond/env/source.html">specify 
+    the jndi environment with system properties</ulink>.</para>
+    <para>The <literal>jms</literal> activity will use the JMS queue apis if the destination 
+    is an <literal>instanceof</literal> Queue.  Analogue for topics. 
+    </para>
 
     <table><title><literal>jms</literal> elements:</title>
       <tgroup cols="3" rowsep="1" colsep="1">
@@ -947,6 +959,43 @@
 
     <mediaobject><imageobject><imagedata align="center" fileref="images/process.jms.png"/></imageobject></mediaobject>
     
+    <section id="mockjmsproviderforeasytesting">
+      <title>Mock JMS provider for easy testing</title>
+      <para>Apart from configuring a real JMS and making sure it is available in JNDI, 
+      a <literal>jms</literal> activity can also be tested with a mock JMS provider.
+      That might be easier to perform scenario testing of your process.</para>
+      <para>Following test helper methods are based solely on plain JMS apis and hence they work in 
+      a standalone environment as well as in an appserver environment:</para>
+      <itemizedlist>
+        <listitem>Object jmsConsumeMessageFromQueue(String connectionFactoryJndiName, String queueJndiName)</listitem>
+        <listitem>TODO jmsStartTopicListener(String connectionFactoryJndiName, String topicJndiName)</listitem>
+        <listitem>void jmsStopTopicListener(String connectionFactoryJndiName, String topicJndiName)</listitem>
+      </itemizedlist>
+      <para>For example, after the process execution has executed the <literal>jms</literal> activity, 
+      messages can be asserted like this:</para>
+      <programlisting>MapMessage mapMessage = (MapMessage) jmsConsumeMessageFromQueue(&quot;jms/ConnectionFactory&quot;, &quot;queue/ProductQueue&quot;);
+assertEquals(&quot;shampoo&quot;, mapMessage.getString(&quot;product&quot;));</programlisting>
+      <para>The following jms helper methods are based on mockrunner and hence they only work in a standalone 
+      environment:</para>
+      <para>(we're collaborating with mockrunner people to have these methods also work in an appserver environment)</para>
+      <itemizedlist>
+        <listitem>void jmsCreateQueue(String connectionFactoryJndiName, String queueJndiName)</listitem>
+        <listitem>void jmsRemoveQueue(String connectionFactoryJndiName, String queueJndiName)</listitem>
+        <listitem>void jmsCreateTopic(String connectionFactoryJndiName, String topicJndiName)</listitem>
+        <listitem>void jmsRemoveTopic(String connectionFactoryJndiName, String topicJndiName)</listitem>
+      </itemizedlist>
+      <para>For example, a queue can be created and removed in the setup and tearDown methods of a test like this:</para>
+      <programlisting>protected void setUp() throws Exception {
+  super.setUp();
+  jmsCreateQueue(&quot;jms/ConnectionFactory&quot;, &quot;queue/ProductQueue&quot;);
+}
+
+protected void tearDown() throws Exception {
+  jmsRemoveQueue(&quot;jms/ConnectionFactory&quot;, &quot;queue/ProductQueue&quot;);
+  super.tearDown();
+}</programlisting>
+    </section>
+      
     <section id="jms.text">
       <title>Text messages</title>
       
@@ -980,8 +1029,7 @@
         The payload of the message is the text string &quot;This is the body&quot;.
       </para>
       
-      <programlisting>public void testTextMessage() throws Exception 
-{  
+      <programlisting>public void testTextMessage() throws Exception {  
   Context context = new InitialContext();
   Connection connection = (Connection)context.lookup(&quot;ConnectionFactory&quot;);
   connection.start();