Author: koen.aers(a)jboss.com
Date: 2008-12-30 11:33:27 -0500 (Tue, 30 Dec 2008)
New Revision: 3585
Added:
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-Jpdl.xml
Log:
add the script task documentation
Added: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-Jpdl.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-Jpdl.xml
(rev 0)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-Jpdl.xml 2008-12-30
16:33:27 UTC (rev 3585)
@@ -0,0 +1,896 @@
+<chapter id="jpdl">
+ <title>jPDL</title>
+
+ <para>This chapter will explain the jPDL file format for describing
+ process definitions. The schemadocs can also serve as a quick reference for this
+ information.
+ </para>
+ <para>An example jPDL process file looks like this:
+ </para>
+ <programlisting><?xml version="1.0"
encoding="UTF-8"?>
+
+<process name="Purchase order"
xmlns="http://jbpm.org/4/jpdl">
+
+ <start>
+ <flow to="Verify supplier" />
+ </start>
+
+ <state name="Verify supplier">
+ <flow name="Supplier ok" to="Check supplier
data" />
+ <flow name="Supplier not ok" to="Error"
/>
+ </state>
+
+ <exclusive name="Check supplier data">
+ <flow name="nok" to="Error" />
+ <flow name="ok" to="Completed" />
+ </exclusive>
+
+ <end name="Completed" />
+
+ <end name="Error" />
+
+</process></programlisting>
+
+ <section id="process">
+ <title><literal>process</literal></title>
+ <para>The top level element representing one process definition.
+ </para>
+ <table><title><literal>process</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><literal>name</literal></entry>
+ <entry>any text</entry>
+ <entry></entry>
+ <entry><emphasis
role="bold">required</emphasis></entry>
+ <entry>name or label of the process used to display to the process
+ name in user interactions.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>key</literal></entry>
+ <entry>alpha numeric characters and underscores</entry>
+ <entry>if omitted, the key will be generated based on the name by
replacing
+ all non-alpha-numeric characters with underscores</entry>
+ <entry>optional</entry>
+ <entry>identification to distinct different process definitions.
+ Multiple versions of a process with the same key can be deployed.
+ The key:name combination must remain exactly the same for all
+ deployed versions.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>version</literal></entry>
+ <entry>integer</entry>
+ <entry>one higher then highest version number starting with 1 if no
other process
+ is deployed with the same name/key.
+ </entry>
+ <entry>optional</entry>
+ <entry>version number of this process</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table><title><literal>process</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>description</literal></entry>
+ <entry>0..1</entry>
+ <entry>description text</entry>
+ </row>
+ <row>
+ <entry><link
linkend="activities">activities</link></entry>
+ <entry>1..*</entry>
+ <entry>a list of any activity type can be placed here. At least
+ one <literal>start</literal> activity must be present.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="activities">
+ <title>Activities</title>
+ <para>(BPMN note: when we mention activities here, we are not only refering to
BPMN
+ activities, but also to BPMN events and BPMN gateways.)
+ </para>
+
+ <section id="start">
+ <title><literal>start</literal></title>
+ <para>Indicates where an execution for this process starts. Typically there
is
+ exactly one start activity in a process. A process has to have at least one start
+ activity. A start activity must have exactly one outgoing flow and that flow
+ is taken when a process execution starts.
+ </para>
+ <table><title><literal>start</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><literal>name</literal></entry>
+ <entry>any text</entry>
+ <entry></entry>
+ <entry>optional</entry>
+ <entry>name of the activity. Since a start activity
+ cannot have incoming flows, the name is optional.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table><title><literal>start</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>flow</literal></entry>
+ <entry>1</entry>
+ <entry>the outgoing flow</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="state">
+ <title><literal>state</literal></title>
+ <para>A wait state. Process execution will wait until an external trigger is
+ provided through the API. Apart from the <link
linkend="commonactivitycontent">
+ common activity content</link>, <literal>state</literal>
doesn't have any extra
+ attributes or elements.
+ </para>
+ <section id="statesequence">
+ <title><literal>state</literal> sequence</title>
+ <para>Let's look at an example which shows states connected with flows
+ as a sequence</para>
+ <figure id="state.sequence">
+ <title>A sequence of states</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/state.sequence.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="StateSequence"
xmlns="http://jbpm.org/4/jpdl">
+
+ <start>
+ <flow to="a" />
+ </start>
+
+ <state name="a">
+ <flow to="b" />
+ </state>
+
+ <state name="b">
+ <flow to="c" />
+ </state>
+
+ <state name="c" />
+
+</process></programlisting>
+ <para>After you start an execution like this:</para>
+ <programlisting>Execution execution =
executionService.startExecutionByKey("StateSequence");</programlisting>
+ <para>the created process instance will be positioned in
+ state <literal>a</literal>. Providing an external trigger can
+ be done with the <literal>signalExecution</literal>
methods.</para>
+ <programlisting>String executionId = execution.getId();
+execution = executionService.signalExecutionById(executionId);</programlisting>
+ </section>
+ <section id="statechoice">
+ <title><literal>state</literal> choice</title>
+ <para>In this second example with states, we'll show how you can use a
+ <literal>state</literal> can be used to feed in an external choice of
+ the path to take.
+ </para>
+ <figure id="state.choice">
+ <title>A choice between state</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/state.choice.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="StateChoice"
xmlns="http://jbpm.org/4/jpdl">
+
+ <start>
+ <flow to="wait for response" />
+ </start>
+
+ <state name="wait for response">
+ <flow name="accept" to="submit document"
/>
+ <flow name="reject" to="try again"
/>
+ </state>
+
+ <state name="submit document" />
+
+ <state name="try again" />
+
+</process></programlisting>
+ <para>Let's start a new process instance for this process
definition:</para>
+ <programlisting>Execution execution =
executionService.startExecutionByKey("StateSequence");</programlisting>
+ <para>Now, the execution is arrived in the <literal>wait for
response</literal>.
+ The execution will wait there until an external trigger is given. In case
+ a <literal>state</literal> has multiple outgoing flows, the
signalName given
+ in the external trigger will be matched against the name of the outgoing flow
+ to take. So when we provide signalName <literal>accept</literal>
like this:
+ </para>
+ <programlisting>executionService.signalExecutionById(executionId,
"accept");</programlisting>
+ <para>Then the execution will continue over the outgoing flow named
+ <literal>accept</literal>. Analogue, when signalName
<literal>reject</literal>
+ is given in the signalExecutionXxx methods, the execution will continue over
+ the outgoing flow named reject.
+ </para>
+ </section>
+ </section>
+
+ <section id="java">
+ <title><literal>java</literal></title>
+ <para>The Java task. A process execution will execute the method of the class
that is configured
+ in this task.</para>
+ <table><title><literal>java</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><literal>class</literal></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>method</literal></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>var</literal></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table><title><literal>java</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>field</literal></entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>arg</literal></entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Consider the following example.</para>
+ <figure id="java">
+ <title>A java task</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/java.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="Java"
xmlns="http://jbpm.org/4/jpdl">
+
+ <start>
+ <flow to="invoke java method" />
+ </start>
+
+ <java name="invoke java method"
+ class="org.jbpm.examples.java.JohnDoe"
+ method="hello"
+ var="answer">
+
+ <field name="state"><string
value="fine"/></field>
+ <field name="session"><env
type="org.hibernate.Session"/></field>
+
+ <arg><string value="Hi, how are
you?"/></arg>
+
+ <flow to="wait" />
+ </java>
+
+ <state name="wait">
+
+</process>
+ </programlisting>
+ <para>The java task specifies that during its execution an instance of the
class <literal>org.jbpm.examples.java.JohnDoe</literal>
+ will be instantiated and the method <literal>hello</literal> of this
class will be invoked on the resulting object. The variable named
+ <literal>answer</literal> will contain the result of the invocation.
Let's look at the class <literal>JohnDoe</literal> below.
+ </para>
+ <programlisting>package org.jbpm.examples.java;
+
+import org.hibernate.Session;
+
+public class JohnDoe {
+
+ String state;
+ Session session;
+
+ public String hello(String msg) {
+ if ( (msg.indexOf("how are you?")!=-1)
+ && (session.isOpen())
+ ) {
+ return "I'm "+state+", thank you.";
+ }
+ return null;
+ }
+}
+ </programlisting>
+ <para>The class above reveals that it contains two fields named
<literal>state</literal> and <literal>session</literal>
+ and that the method <literal>hello</literal> accepts one argument. During
the execution the values specified in the
+ <literal>field</literal> and <literal>arg</literal>
configuration elements will be used. The expected result of creating
+ a process instance is that the process variable <literal>answer</literal>
contains the string
+ <literal>I'm fine, thank you.</literal>.
+ </para>
+ </section>
+
+ <section id="script">
+ <title><literal>script</literal></title>
+ <para>The Script task. A process execution will execute a script that is
specified by this task. The script can be
+ specified by either the <literal>expr</literal> attribute or by the
inclusion of the <literal>text</literal> nested
+ element. The result of the evaluation
+ </para>
+ <table><title><literal>script</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><literal>expr</literal></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>var</literal></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table><title><literal>script</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></entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Consider the following example.</para>
+ <figure id="script">
+ <title>A script task</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/script.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="ScriptExpression"
xmlns="http://jbpm.org/4/jpdl">
+
+ <start>
+ <flow to="invoke script" />
+ </start>
+
+ <script name="invoke script"
+ expr="Send packet to #{person.address}"
+ var="text">
+
+ <flow to="wait" />
+ </script>
+
+ <state name="wait"/>
+
+</process></programlisting>
+ </section>
+
+ <section id="esb">
+ <title><literal>esb</literal></title>
+ </section>
+
+ <section id="sql">
+ <title><literal>sql</literal></title>
+ </section>
+
+ <section id="hql">
+ <title><literal>hql</literal></title>
+ </section>
+
+ <section id="task">
+ <title><literal>task</literal></title>
+ </section>
+
+ <section id="exclusive">
+ <title><literal>exclusive</literal></title>
+ <para>Takes one path of many alternatives. Also known as a decision. An
exclusive
+ activity has multiple outgoing flows and when an execution arrives in an exclusive
+ activity, an automatic evaluation will decide which outgoing flow is taken.
+ </para>
+ <para>An exclusive activity should be configured in one of the three
following ways:
+ </para>
+
+ <section id="exclusiveconditions">
+ <title>Exclusive conditions</title>
+ <para>An exclusive with conditions on the flows evaluates the condition in
each flow.
+ The first flow for which the nested condition expression resolves to true or
which does
+ not have a condition is taken.
+ </para>
+ <table><title><literal>exclusive.flow.condition</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><literal>expr</literal></entry>
+ <entry>expression</entry>
+ <entry></entry>
+ <entry><emphasis
role="bold">required</emphasis></entry>
+ <entry>script that will be evaluated in the specified
+ expression language.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>lang</literal></entry>
+ <entry>expression language</entry>
+ <entry>the
<literal>default-expression-language</literal> taken from the <link
linkend="scripting"><literal>script-manager</literal>
configuration</link></entry>
+ <entry>optional</entry>
+ <entry>the language in which <literal>expr</literal> is
+ to be evaluated.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Example:
+ </para>
+ <figure id="exclusive">
+ <title>The exclusive gateway</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/exclusive.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process
name="ExclusiveConditions" >
+
+ <start>
+ <flow to="evaluate document" />
+ </start>
+
+ <exclusive name="evaluate document">
+ <flow to="submit document">
+ <emphasis role="bold"><condition
expr="#{content=="good"}" /></emphasis>
+ </flow>
+ <flow to="try again">
+ <emphasis role="bold"><condition
expr="#{content=="not so good"}"
/></emphasis>
+ </flow>
+ <flow to="give up" />
+ </exclusive>
+
+ <state name="submit document" />
+
+ <state name="try again" />
+
+ <state name="give up" />
+
+</process></programlisting>
+ </section>
+
+ <section id="exclusiveexpression">
+ <title>Exclusive expression</title>
+ <para>An exclusive expression evaluates to a String representing the name
of
+ an outgoing flow.
+ </para>
+ <table><title><literal>exclusive</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><literal>expr</literal></entry>
+ <entry>expression</entry>
+ <entry></entry>
+ <entry><emphasis
role="bold">required</emphasis></entry>
+ <entry>script that will be evaluated in the specified
+ expression language.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>lang</literal></entry>
+ <entry>expression language</entry>
+ <entry>the
<literal>default-expression-language</literal> taken from the <link
linkend="scripting"><literal>script-manager</literal>
configuration</link></entry>
+ <entry>optional</entry>
+ <entry>the language in which <literal>expr</literal> is
+ to be evaluated.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Example:
+ </para>
+ <para>Same picture as <link
linkend="exclusive">above</link>.
+ </para>
+ <programlisting><process name="Poolcar">
+ <start>
+ <flow to="How far?" />
+ </start>
+ <exclusive name="How far?" <emphasis
role="bold">expr="#{distance}"</emphasis>>
+ <flow name="far" to="Big car"
/>
+ <flow name="nearby" to="Small car"
/>
+ </exclusive>
+ <state name="Big car" />
+ <state name="Small car" />
+</process></programlisting>
+ <para>When you start an new process instance like this
+ </para>
+ <programlisting>Map<String, Object> variables = new
HashMap<String, Object>();
+variables.put("distance", "far");
+Execution execution = executionService.startExecutionByKey("Poolcar",
variables);</programlisting>
+ <para>then the new execution will go to node <literal>Big
car</literal>.</para>
+ </section>
+
+ <section id="exclusivehandler">
+ <title>Exclusive handler</title>
+ <para>An exclusive handler is a java class that implements the
+ <literal>ExclusiveHandler</literal> interface. The exclusive handler
+ will be responsible for selecting the name of the outgoing flow.
+ </para>
+ <programlisting>public interface ExclusiveHandler {
+ String select(OpenExecution execution);
+}</programlisting>
+ <para>The handler is specified as a sub element of the
exclusive</para>
+ <table><title><literal>exclusive.handler</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><literal>class</literal></entry>
+ <entry>classname</entry>
+ <entry></entry>
+ <entry><emphasis
role="bold">required</emphasis></entry>
+ <entry>fully qualified classname of the handler implementation
class.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Here's an example process of an exclusive using an
ExclusiveHandler:</para>
+ <para>Same picture as <link
linkend="exclusive">above</link>.
+ </para>
+ <programlisting><process
name="ExclusiveHandler">
+
+ <start>
+ <flow to="evaluate document" />
+ </start>
+
+ <exclusive name="evaluate document">
+ <handler
class="org.jbpm.examples.exclusive.handler.ContentEvaluation" />
+ <flow name="good" to="submit document"
/>
+ <flow name="bad" to="try again" />
+ <flow name="ugly" to="give up" />
+ </exclusive>
+
+ <state name="submit document" />
+
+ <state name="try again" />
+
+ <state name="give up" />
+
+</process></programlisting>
+ <para>The ContentEvaluation class looks like this</para>
+ <programlisting>public class ContentEvaluation implements ExclusiveHandler
{
+
+ public String select(OpenExecution execution) {
+ String content = (String) execution.getVariable("content");
+ if (content.equals("you're great")) {
+ return "good";
+ }
+ if (content.equals("you gotta improve")) {
+ return "bad";
+ }
+ return "ugly";
+ }
+}</programlisting>
+ <para>Now, when we start a process instance and supply value
+ <literal>you're great</literal> for variable content, then the
+ ContentEvaluation will return String <literal>good</literal> and
+ the process instance will arrive in node <literal>Submit
document</literal>.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="end">
+ <title><literal>end</literal></title>
+ <para>Ends the execution.
+ </para>
+ <section id="endprocessinstance">
+ <title><literal>end</literal> process instance</title>
+ <para>By default, an end activity will end the complete
+ process instance. In case multiple concurrent executions
+ are still active within the same process instance, all of
+ them will be ended.
+ </para>
+ <figure id="end.processinstance">
+ <title>The end event</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/end.processinstance.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="EndProcessInstance"
xmlns="http://jbpm.org/4/jpdl">
+
+ <start>
+ <flow to="end" />
+ </start>
+
+ <end name="end" />
+
+</process></programlisting>
+ <para>When a new process instance is created, it immediately
ends.</para>
+ </section>
+ <section id="endexecution">
+ <title><literal>end</literal> execution</title>
+ <para>Only the execution that arrives in the
+ end activity will be ended and other concurrent executions
+ should be left active. To get this behaviour, set
+ attribute <literal>ends="execution"</literal>
+ </para>
+ <table><title><literal>end</literal> execution
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><literal>ends</literal></entry>
+ <entry>{processinstance|execution}</entry>
+ <entry>processinstance</entry>
+ <entry>optional</entry>
+ <entry>specifies if the whole process instance should be ended or
+ just the path of execution that arrives in the end activity.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section id="endmultiple">
+ <title><literal>end</literal> multiple</title>
+ <para>A process can have multiple end events. This can be handy to
indicate
+ different outcomes of a process instance. For example
+ </para>
+ <figure id="end.multiple">
+ <title>Multiple end events</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/end.multiple.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="EndMultiple"
xmlns="http://;jbpm.org/4/jpdl">
+
+ <start>
+ <flow to="get return code" />
+ <start>
+
+ <state name="get return code">
+ <flow name="200" to="ok"/>
+ <flow name="400" to="bad
request"/>
+ <flow name="500" to="internal server
error"/>
+ </state>
+
+ <end name="ok"/>
+ <end name="bad request"/>
+ <end name="internal server error"/>
+
+</process>
+ </programlisting>
+ <para>Now if we would start an execution and signal it to move out of the
<literal>get return code</literal> wait state with the
+ following code, the execution would end with the <literal>bad
request</literal> end event.</para>
+ <programlisting>Execution execution =
executionService.startExecutionByKey("EndMultiple");
+String executionId = execution.getId();
+execution = executionService.signalExecutionById(executionId, "400");
+ </programlisting>
+ <para>Likewise, using the value <literal>200</literal> or
<literal>500</literal> would cause the execution
+ to end with the <literal>ok</literal> or with the
<literal>internal server error</literal> end events
+ respectively.</para>
+ </section>
+
+ <section id="endstate">
+ <title><literal>end</literal> state</title>
+ <para>An execution can also end with different states. It is another way to
specify the outcome of a process.
+ It is indicated by the <literal>state</literal> attribute of the end
event or by the <literal>end-cancel</literal>
+ and <literal>end-error</literal> shortcut notations.
+ </para>
+
+ <table><title><literal>end</literal> execution
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><literal>state</literal></entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>optional</entry>
+ <entry>the state assigned to the execution.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Take for example the following process.
+ </para>
+ <figure id="end.state">
+ <title>Different end states</title>
+ <mediaobject><imageobject><imagedata align="center"
fileref="images/end.state.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="EndState"
xmlns="http://jbpm.org/4/jpdl">
+
+ <start>
+ <flow to="get return code"/>
+ </start>
+
+ <state name="get return code">
+ <flow name="200" to="ok"/>
+ <flow name="400" to="bad request"
/>
+ <flow name="500" to="internal server
error"/>
+ </state>
+
+ <end name="ok" state="completed"/>
+ <end-cancel name="bad request"/>
+ <end-error name="internal server error"/>
+
+</process>
+ </programlisting>
+ <para>This time, if we would start an execution and signal it to move out
of the <literal>get return code</literal> wait state with the
+ following code, the execution would end with the
<literal>cancel</literal> state.</para>
+ <programlisting>Execution execution =
executionService.startExecutionByKey("EndState");
+String executionId = execution.getId();
+execution = executionService.signalExecutionById(executionId, "400");
+ </programlisting>
+ <para>Similarly as above, using the value
<literal>200</literal> or <literal>500</literal> would cause the
execution
+ to end with the <literal>completed</literal> or with the
<literal>error</literal> states
+ respectively.</para>
+
+ </section>
+ </section>
+
+ <section id="commonactivitycontents">
+ <title>Common activity contents</title>
+ <para>Unless specified otherwise above, all activities also include this
+ content model:
+ </para>
+ <table><title>Common activity 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><literal>name</literal></entry>
+ <entry>any text</entry>
+ <entry></entry>
+ <entry><emphasis
role="bold">required</emphasis></entry>
+ <entry>name of the activity</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table><title>Common activity 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>flow</literal></entry>
+ <entry>0..*</entry>
+ <entry>the outgoing flows</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+
+</chapter>