9:07 p.m.
Author: koen.aers(a)jboss.com
Date: 2009-12-20 22:07:53 -0500 (Sun, 20 Dec 2009)
New Revision: 6003
Added:
jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.jms.png
jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.rules.decision.png
jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.rules.png
Modified:
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
Log:
- jms activity documentation
- rules activity image
- rules decision image
Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.jms.png
===================================================================
(Binary files differ)
Property changes on:
jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.jms.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.rules.decision.png
===================================================================
(Binary files differ)
Property changes on:
jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.rules.decision.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.rules.png
===================================================================
(Binary files differ)
Property changes on:
jbpm4/trunk/modules/devguide/src/main/docbook/en/images/process.rules.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
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-20
21:27:27 UTC (rev 6002)
+++
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml 2009-12-21
03:07:53 UTC (rev 6003)
@@ -851,6 +851,268 @@
</para>
</section>
+ <!-- ### JMS ####################################################### -->
+ <section id="jms">
+
+ <title><literal>jms</literal> activity</title>
+ <para>
+ The <literal>jms</literal> activity provides users with convenience for
sending JMS messages.
+ At this moment the sending of three different types of JMS messages is possible:
text, object
+ and map. Specifying message properties is not yet supported.
+ In the future the functionality may be elaborated to cover this and more of the JMS
specification.
+ </para>
+
+ <table><title><literal>jms</literal>
attributes:</title>
+ <tgroup cols="5" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Type</entry>
+ <entry>Default</entry>
+ <entry>Required?</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>connection-factory</entry>
+ <entry>jndi name</entry>
+ <entry></entry>
+ <entry>true</entry>
+ <entry>the jndi name of the jms connection factory.
+ </entry>
+ </row>
+ <row>
+ <entry>destination</entry>
+ <entry>jndi name</entry>
+ <entry></entry>
+ <entry>true</entry>
+ <entry>the jndi name of the jms queue or topic.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ 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.
+ </para>
+
+ <table><title><literal>jms</literal> elements:</title>
+ <tgroup cols="3" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Multiplicity</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>text</literal></entry>
+ <entry>0..1</entry>
+ <entry>A string of text that will be used as payload for the JMS
message.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>object</literal></entry>
+ <entry>0..1</entry>
+ <entry>A serializable object that will be used as payload for the JMS
message.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>map</literal></entry>
+ <entry>0..1</entry>
+ <entry>A map of which the key-value entries will be used as payload for
the JMS message.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Exactly one of the elements <literal>text</literal>,
<literal>object</literal> or <literal>map</literal>
+ is mandatory. The presence of this element will determine the kind of message that
will be sent to the
+ queue obtained in the lookup mentioned above. This message will be a
<literal>TextMessage</literal>,
+ <literal>ObjectMessage</literal> or
<literal>MapMessage</literal> respectively.
+ </para>
+
+ <para>
+ In the following subsections the different types of supported messages will be
explained. The used process
+ is in the three cases similar. The graphical representation of the process is shown
below.
+ </para>
+
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/process.jms.png"/></imageobject></mediaobject>
+
+ <section id="jms.text">
+ <title>Text messages</title>
+
+ <para>
+ The first possibility of sending JMS messages is to use text as its payload. In
this case a JMS
+ <literal>TextMessage</literal> will be created and sent to the
specified destination.
+ Consider the following process definition:
+ </para>
+
+ <programlisting><process
name="JMS_text_queue">
+
+ <start>
+ <transition to="send message"/>
+ </start>
+
+ <emphasis role="bold"><jms name="send
message"
+ connection-factory="ConnectionFactory"
+ destination="queue/jbpm-test-queue">
+ <text>This is the body</text>
+ <transition to="wait"/>
+ </jms></emphasis>
+
+ <state name="wait"/>
+
+</process></programlisting>
+
+ <para>
+ As you may expect and as is shown in the following test case starting this
process will cause
+ the JMS node to send a message to the queue with the name
"queue/jbpm-test-queue".
+ The factory used to create a connection to connect to this queue is named
"ConnectionFactory".
+ The payload of the message is the text string "This is the
body".
+ </para>
+
+ <programlisting>public void testTextMessage() throws Exception
+{
+ Context context = new InitialContext();
+ Connection connection =
(Connection)context.lookup("ConnectionFactory");
+ connection.start();
+ Session session = connection.createSession(false, QueueSession.AUTO_ACKNOWLEDGE);
+ Queue queue = (Queue)context.lookup("queue/jbpm-test-queue");
+ MessageConsumer messageConsumer = session.createConsumer(queue);
+
+ <emphasis
role="bold">executionService.startProcessInstanceByKey("JMS_text_queue");
+ TextMessage textMessage = (TextMessage)messageConsumer.receive();
+ assertEquals("This is the body",
textMessage.getText());</emphasis>
+
+ connection.stop();
+ session.close();
+ connection.close();
+}</programlisting>
+
+ <para>
+ The relevant code is shown above in boldface. The rest of the method is
boilerplate code needed to
+ setup a message consumer. We will omit this code in the subsequent examples.
+ </para>
+
+ </section>
+
+ <section id="jms.object">
+
+ <title>Object messages</title>
+
+ <para>
+ The second possibility is to use a serializable object as the payload of the
message. In this case a
+ JMS <literal>ObjectMessage</literal> will be created and sent to the
specified destination.
+ Consider the following process definition:
+ </para>
+
+ <programlisting><process
name="JMS_object_queue">
+
+ <start>
+ <transition to="send message"/>
+ </start>
+
+ <emphasis role="bold"><jms name="send
message"
+ connection-factory="ConnectionFactory"
+ destination="queue/jbpm-test-queue">
+ <object expr="${object}"/>
+ <transition to="wait"/>
+ </jms></emphasis>
+
+ <state name="wait"/>
+
+</process></programlisting>
+
+ <para>
+ As in the previous case a message will be sent to the queue with the name
"queue/jbpm-test-queue".
+ Also again a factory used to create a connection to connect to this queue is
named "ConnectionFactory".
+ But in this case the payload of the message is the serializable object that is
obtained by
+ evaluating the expression specified by the <literal>expr</literal>
attribute. This is illustrated in the test case below.
+ </para>
+
+ <programlisting>public void testQueueMessage() throws Exception
+{
+ // as before
+ ...
+ <emphasis role="bold">Map<String, Object> variables = new
HashMap<String, Object>();
+ variables.put("object", "this is the object");
+ executionService.startProcessInstanceByKey("JMS_object_queue",
variables);
+ ObjectMessage objectMessage = (ObjectMessage)messageConsumer.receive();
+ assertEquals("this is the object",
objectMessage.getObject());</emphasis>
+
+ // as before
+ ...
+}</programlisting>
+
+ </section>
+
+ <section id="jms.map">
+
+ <title>Map messages</title>
+
+ <para>
+ In this third possibility the payload is constituted by the key-value entries of
a map. This time a
+ JMS <literal>MapMessage</literal> will be created and sent to the
specified destination.
+ Consider the following process definition:
+ </para>
+
+ <programlisting><process
name="JMS_map_queue">
+
+ <start>
+ <transition to="send message"/>
+ </start>
+
+ <emphasis role="bold"><jms name="send
message"
+ connection-factory="ConnectionFactory"
+ destination="queue/jbpm-test-queue">
+ <map>
+ <entry>
+ <key><string
value="x"/></key>
+ <value><string
value="foo"/></value>
+ </entry>
+ </map>
+ <transition to="wait"/>
+ </jms></emphasis>
+
+ <state name="wait"/>
+
+</process></programlisting>
+
+ <para>
+ Again a message will be sent to the queue with the name
"queue/jbpm-test-queue" and the
+ factory used to create a connection to connect to this queue is named
"ConnectionFactory".
+ In this case the payload of the message are the specified key-value pairs of the
map.
+ It is illustrated in the test case below.
+ </para>
+
+ <programlisting>public void testMapMessage() throws Exception
+{
+ // as before
+ ...
+ <emphasis
role="bold">executionService.startProcessInstanceByKey("JMS_map_queue");
+ MapMessage mapMessage = (MapMessage)messageConsumer.receive();
+ assertTrue(mapMessage.itemExists("x"));
+ assertEquals("foo",
mapMessage.getObject("x"));</emphasis>
+
+ // as before
+ ...
+}</programlisting>
+
+ </section>
+
+ </section>
+
+
+
<section>
<title>History session chain</title>
<para>