[jbpm-commits] JBoss JBPM SVN: r5210 - jbpm4/trunk/modules/devguide/src/main/docbook/en/modules.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Jul 3 05:32:55 EDT 2009
Author: tom.baeyens at jboss.com
Date: 2009-07-03 05:32:54 -0400 (Fri, 03 Jul 2009)
New Revision: 5210
Added:
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-ProcessVirtualMachine.xml
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Configuration.xml
Removed:
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Configuration.xml
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-AdvancedJpdl.xml
Modified:
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml
jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml
Log:
introducing incubation chapter in the devguide
Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml 2009-07-03 09:28:20 UTC (rev 5209)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch01-Introduction.xml 2009-07-03 09:32:54 UTC (rev 5210)
@@ -10,6 +10,21 @@
</section>
<section>
+ <title>Overview</title>
+ <para><xref linkend="incubation" /> explains the features that are intended to
+ move to the userguide eventually and become part of the supported offering. But
+ incubation features are not yet considered stable.
+ </para>
+ <para><xref linkend="processvirtualmachine" /> through <xref linkend="advancedgraphexecution" />
+ explain the process virtual machine and how activity and event listener can be build
+ for it.
+ </para>
+ <para><xref linkend="configuration" /> through <xref linkend="jbossintegration" />
+ explain internal developer topics.
+ </para>
+ </section>
+
+ <section>
<title>Sources and WIKI</title>
<para>The source code for jBPM can be found in our <ulink url="http://subversion.tigris.org/">SVN</ulink> repository:</para>
<ulink url="https://anonsvn.jboss.org/repos/jbpm/jbpm4/">https://anonsvn.jboss.org/repos/jbpm/jbpm4/</ulink>
Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml 2009-07-03 09:32:54 UTC (rev 5210)
@@ -0,0 +1,585 @@
+<chapter id="incubation">
+ <title>Incubation</title>
+
+ <para>This section documents some of the more advanced activities and
+ features of jPDL that are still in incubation. Meaning these features
+ and activities are not supported yet. But they are available for you
+ to try and use. We don't give any stability guarantees on these
+ activities and features. So use at your own risk.
+ </para>
+
+ <!-- ### Timer ########################################################## -->
+ <section id="timer">
+ <title><literal>timer</literal> </title>
+ <para>IMPORTANT NOTE : Timers will be changed before they are moved to the
+ Userguide. See also
+ <ulink url="https://jira.jboss.org/jira/browse/JBPM-2329">https://jira.jboss.org/jira/browse/JBPM-2329</ulink>
+ </para>
+ <para>A timer can be specified in the <literal>transition</literal>
+ element in wait state activities such as <literal>state</literal>s,
+ <literal>task</literal>s, <literal>sub-process</literal>es and
+ <literal>group</literal>s.
+ When such a timer fires, that transition is taken.
+ </para>
+ <para>A timer can also be specified in custom events in wait state
+ activities such as <literal>state</literal>s,
+ <literal>task</literal>s, <literal>sub-process</literal>es and
+ <literal>group</literal>s. The <literal>timer</literal> element
+ should then be the first element in the <literal>on</literal> element representing
+ the event. In that case the event fires upon the duedate of the timer.
+ </para>
+ <para>Timers are created when the activity is entered. The timer can fire
+ when the execution remains in the activity until the <literal>duedate</literal>.
+ When the execution leaves the activity, the timer is cancelled.
+ </para>
+ <table><title><literal>timer</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>duedate</literal></entry>
+ <entry><link linkend="duedateexpressions">duedate expression</link></entry>
+ <entry></entry>
+ <entry><emphasis role="bold">required</emphasis></entry>
+ <entry>Specifies when the timer needs to fire. For
+ example: <literal>20 minutes</literal> or
+ <literal>3 business days</literal>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>repeat</literal></entry>
+ <entry><link linkend="duedateexpressions">duedate expression</link></entry>
+ <entry></entry>
+ <entry>optional</entry>
+ <entry>When a timer fires, this attribute specifies when the timer
+ needs to fire again. For example: <literal>20 minutes</literal> or
+ <literal>3 business days</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <section id="duedateexpressions">
+ <title>Duedate expressions</title>
+ <para>A duedate expression has the following syntax:</para>
+ <programlisting>quantity [business] {second | seconds | minute | minutes |
+ hour | hours | day | days | week |
+ weeks | month | months | year | years}</programlisting>
+ <para>where <literal>quantity</literal> is a positive integer.
+ </para>
+ <para>And adding the optional indication <literal>business</literal> means
+ that only business hours should be taken into account for this duration. Without
+ the indication business, the duration will be interpreted as an absolute time period.
+ How to configure business hours is explained in <xref linkend="businesscalendar"/>
+ </para>
+ </section>
+
+ <section id="businesscalendar">
+ <title>Business calendar</title>
+ <para>The default configuration will contain a reference to the file
+ <literal>jbpm.business.calendar.xml</literal>. That contains a
+ configuration of business hours in the following format:
+ </para>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+
+<jbpm-configuration xmlns="http://jbpm.org/xsd/cfg">
+
+ <process-engine-context>
+
+ <business-calendar>
+ <monday hours="9:00-12:00 and 12:30-17:00"/>
+ <tuesday hours="9:00-12:00 and 12:30-17:00"/>
+ <wednesday hours="9:00-12:00 and 12:30-17:00"/>
+ <thursday hours="9:00-12:00 and 12:30-17:00"/>
+ <friday hours="9:00-12:00 and 12:30-17:00"/>
+ <holiday period="01/07/2008 - 31/08/2008"/>
+ </business-calendar>
+
+ </process-engine-context>
+
+</jbpm-configuration></programlisting>
+ <para>For an example of where the business calendar is used, see
+ <xref linkedn="timerbusinesstime" />
+ </para>
+ </section>
+
+ <section id="timertransition">
+ <title>Timer transition</title>
+ <para>Example TimerTransitionTest shows how to put a timer on a transition.</para>
+ <figure id="process.timer.transition">
+ <title>The timer transition example process</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.timer.transition.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="TimerTransition" xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="guardedWait" />
+ </start>
+
+ <state name="guardedWait">
+ <transition name="go on" to="next step" />
+ <transition name="timeout" to="escalation">
+ <emphasis role="bold"><timer duedate="10 minutes" /></emphasis>
+ </transition>
+ </state>
+
+ <state name="next step" />
+ <state name="escalation" />
+
+</process></programlisting>
+ <para>When an process instance for this process is started, it arrives immediately
+ in the <literal>guardedWait</literal> state. At that time, a timer is created that will fire
+ after 10 minutes.
+ </para>
+ <programlisting>Execution processInstance = executionService
+ .startProcessInstanceByKey("TimerTransition");</programlisting>
+ <para>With the following query, we can query for the timers related to the newly created
+ processInstance. We know that there should be exactly one such timer.
+ </para>
+ <programlisting>Job job = managementService.createJobQuery()
+ .timers()
+ .processInstanceId(processInstance.getId())
+ .uniqueResult();
+ </programlisting>
+ <para>In a unit test, we won't use the JobExecutor to execute the timer. Instead,
+ we execute timers directly in the thread of the unit test. That way it is easy to
+ simulate one scenario though an execution.
+ </para>
+ <para>So as the next step, we assume that the timer will fire. We simulate this
+ by executing the timer programmatically:
+ </para>
+ <programlisting>managementService.executeJob(job.getDbid());</programlisting>
+ <para>After that the process instance will have taken the
+ <literal>timeout</literal> transition and moved to the escalation state.
+ </para>
+ <programlisting>processInstance = executionService.findExecutionById(processInstance.getId());
+assertEquals("escalation", processInstance.getActivityName());</programlisting>
+ <para>The second scenario in TimerTransitionTest shows that the
+ timer is cancelled in case the signal <literal>go on</literal> is given
+ before the timer fires. In that case the execution ends up in the
+ <literal>next step</literal>.
+ </para>
+ </section>
+
+ <section id="timerevent">
+ <title>Timer event</title>
+ <para>Example TimerEventTest shows how to put a timer on a custom event.</para>
+ <figure id="process.timer.event">
+ <title>The timer event example process</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.timer.event.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="TimerEvent" xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="guardedWait" />
+ </start>
+
+ <state name="guardedWait" >
+ <emphasis role="bold"><on event="timeout">
+ <timer duedate="10 minutes"/>
+ <event-listener class="org.jbpm.examples.timer.event.Escalate" />
+ </on></emphasis>
+ <transition name="go on" to="next step" />
+ </state>
+
+ <state name="next step" />
+
+</process></programlisting>
+ <para>In this case, if the execution is not signalled within 10 minutes after the
+ activity is started, the event <literal>timeout</literal> is fired
+ and the event listener <literal>org.jbpm.examples.timer.event.Escalate</literal>
+ will be notified.
+ </para>
+ <para>Again, if the <literal>guardedWait</literal> activity is ended within
+ 10 minutes, then the timer is cancelled and the <literal>Escalate</literal>
+ event listener will not be notified.
+ </para>
+ </section>
+
+ <section id="timerbusinesstime">
+ <title>Timer business time</title>
+ <para>Example TimerBusinessTimeTest shows how business time works.</para>
+ <figure id="process.timer.event">
+ <title>The timer businesstime example process</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.timer.transition.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="TimerBusinessTime" xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="guardedWait" />
+ </start>
+
+ <state name="guardedWait" >
+ <transition name="go on" to="next step" />
+ <transition name="timeout" to="escalation" >
+ <timer <emphasis role="bold">duedate="9 business hours"</emphasis> />
+ </transition>
+ </state>
+
+ <state name="next step" />
+ <state name="escalation" />
+
+</process></programlisting>
+ <para>Suppose that a new <literal>TimerBusinessTime</literal> process instance is started
+ at 11:30am on a tuesday. The default configured business calendar specifies working hours
+ between 9:00-12:00 and 12:30-17:00. So 9 business hours later results in an actual duedate
+ for the timer of wednesday 13:00 (1pm).
+ </para>
+ <para>Since we do not know when the TimerBusinessTimeTest will be ran, we only assert
+ in the test that the actual duedate of the scheduled timer at least 24 hours ahead.
+ </para>
+ </section>
+
+ <section id="timerrepeat">
+ <title>Timer repeat</title>
+ <para>Example TimerRepeatTest shows how to put a timer with a repeat. The attribute
+ <literal>repeat</literal> on a timer will cause the timer to be rescheduled automatically
+ after it is executed.
+ </para>
+ <figure id="process.timer.repeat">
+ <title>The timer repeat example process</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.timer.event.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="TimerRepeat" xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="guardedWait" />
+ </start>
+
+ <state name="guardedWait">
+ <on event="timeout">
+ <timer duedate="20 minutes" <emphasis role="bold">repeat="10 seconds"</emphasis> />
+ <event-listener class="org.jbpm.examples.timer.repeat.Escalate" />
+ </on>
+ <transition name="go on" to="next step"/>
+ </state>
+
+ <state name="next step"/>
+
+</process></programlisting>
+ <para>When a new process is started, a timer is created and the duedate
+ will be 20 minutes ahead. When the timer fires, a new timer will be created
+ with a duedate of 10 seconds ahead. When that timer fires, a new timer will
+ be created again 10 seconds ahead. And so on.
+ </para>
+ <para>New timers will be created each time the timer fires until the
+ <literal>guardedWait</literal> state activity is ended with a signal.
+ When the <literal>guardedWait</literal> state activity is ended, the
+ existing timer will be cancelled.
+ </para>
+ </section>
+ </section>
+
+ <!-- ### GROUP ########################################################## -->
+ <section id="group">
+ <title><literal>group</literal></title>
+
+ <para>A group groups a set of activities in a process. Contained groups must
+ be hierarchically nested. A group corresponds to a BPMN expanded sub process.
+ </para>
+
+ <table><title><literal>group</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>any activity</entry>
+ <entry>0..*</entry>
+ <entry>Contained activities.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>transition</literal></entry>
+ <entry>0..*</entry>
+ <entry>Outgoing transitions for the group activity.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <!-- ~~~ GROUP SIMPLE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <section id="groupsimple">
+ <title><literal>group</literal> simple</title>
+ <para>This example scenario shows the basic operations of a <literal>group</literal>.
+ </para>
+ <figure id="process.group.simple">
+ <title>The simple group example process</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.group.simple.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="GroupSimple" xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="evaluate document" />
+ </start>
+
+ <emphasis role="bold"><group name="evaluate document"></emphasis>
+ <start>
+ <transition to="distribute document" />
+ </start>
+ <state name="distribute document">
+ <transition to="collect feedback" />
+ </state>
+ <state name="collect feedback">
+ <transition name="approved" to="done" />
+ <transition name="rejected" to="update document" />
+ </state>
+ <state name="update document">
+ <transition to="distribute document" />
+ </state>
+ <end name="done" />
+ <transition to="publish document" />
+ <emphasis role="bold"></group></emphasis>
+
+ <state name="publish document" />
+
+</process></programlisting>
+ <para>The next code snippet shows a test scenario that rejects a document
+ when it comes in the <literal>collect feedback</literal> first time round.
+ Then it goes through <literal>update document</literal>, <literal>distribute document</literal>
+ and back to <literal>collect feedback</literal>. The second time,
+ it will be approved. All activities involved are wait <literal>state</literal>s.
+ </para>
+ <programlisting>ProcessInstance processInstance = executionService
+ .startProcessInstanceByKey("GroupSimple");
+String pid = processInstance.getId();
+assertEquals("distribute document", processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid);
+assertEquals("collect feedback", processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid, "rejected");
+assertEquals("update document", processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid);
+assertEquals("distribute document", processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid);
+assertEquals("collect feedback", processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid, "approved");
+assertEquals("publish document", processInstance.getActivityName());</programlisting>
+ </section>
+
+ <!-- ~~~ GROUP TIMER ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <section id="grouptimer">
+ <title><literal>group</literal> timer</title>
+ <figure id="process.group.timer">
+ <title>The group timer example process</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.group.timer.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="GroupTimer" xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="evaluate document" />
+ </start>
+
+ <emphasis role="bold"><group name="evaluate document"></emphasis>
+ <start>
+ <transition to="approve" />
+ </start>
+ <state name="approve">
+ <transition to="done" />
+ </state>
+ <end name="done" />
+
+ <transition to="publish document" />
+ <emphasis role="bold"><transition name="timeout" to="escalate">
+ <timer duedate="2 business hours" />
+ </transition></emphasis>
+
+ <emphasis role="bold"></group></emphasis>
+
+ <state name="escalate" />
+ <state name="publish document" />
+
+</process></programlisting>
+ <para>The next code snippet shows a test scenario in which the timer will
+ fire before the group activity <literal>evaluate document</literal> completes.
+ </para>
+ <programlisting>ProcessInstance processInstance = executionService
+ .startProcessInstanceByKey("GroupTimer");
+Execution approveExecution = processInstance
+ .findActiveExecutionIn("approve");
+assertNotNull(approveExecution);
+
+List<Job> jobs = managementService
+ .createJobQuery()
+ .processInstanceId(processInstance.getId())
+ .list();
+
+assertEquals(1, jobs.size());
+
+Timer timer = (Timer) jobs.get(0);
+
+managementService.executeJob(timer.getDbid());
+
+processInstance = executionService
+ .findProcessInstanceById(processInstance.getId());
+assertNotNull(processInstance.findActiveExecutionIn("escalate") );</programlisting>
+ </section>
+
+ <!-- ~~~ GROUP MULTIPLE ENTRIES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <section id="groupmultipleentries">
+ <title><literal>group</literal> multiple entries</title>
+ <para>This shows how a group can have multiple exclusive entry points.</para>
+ <para>Analogue to multiple entry points, a group can also have
+ multiple exit points.</para>
+ <figure id="process.group.multipleentries">
+ <title>The group multiple entries example process</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.group.multipleentries.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting><process name="GroupMultipleEntries" xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="choose strategy" />
+ </start>
+
+ <decision name="choose strategy" expr="#{time}">
+ <emphasis role="bold"><transition name="plenty" to="play" />
+ <transition name="running out" to="plan" /></emphasis>
+ </decision>
+
+ <group name="evaluate project">
+ <emphasis role="bold"><start name="play">
+ <transition to="distribute document" />
+ </start></emphasis>
+ <state name="distribute document" />
+
+ <emphasis role="bold"><start name="plan">
+ <transition to="make planning" />
+ </start></emphasis>
+ <state name="make planning" />
+ </group>
+
+</process></programlisting>
+ <para>The following scenario will be when there is plenty of time:
+ </para>
+ <programlisting>Map<String, Object> variables = new HashMap<String, Object>();
+variables.put("time", "plenty");
+
+ProcessInstance pi = executionService
+ .startProcessInstanceByKey("GroupMultipleEntries", variables);
+
+assertNotNull(pi.findActiveExecutionIn("distribute document"));</programlisting>
+ <para>The following scenario will be when there is time is running out:
+ </para>
+ <programlisting>Map<String, Object> variables = new HashMap<String, Object>();
+variables.put("time", "running out");
+
+ProcessInstance pi = executionService
+ .startProcessInstanceByKey("GroupMultipleEntries", variables);
+
+assertNotNull(pi.findActiveExecutionIn("make planning"));</programlisting>
+ </section>
+
+ <!-- ~~~ GROUP CONCURRENCY ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <section id="groupconcurrency">
+ <title><literal>group</literal> concurrency</title>
+ <para>This scenario shows how a group can be used to create concurrent paths
+ of execution. When an execution arrives in a group, each activity that doesn't
+ have incoming transitions is started. So the first activities don't have to be
+ start activities. The group takes the default transition out when all contained
+ work is done.
+ </para>
+ <figure id="process.group.concurrency">
+ <title>The group concurrency example process</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.group.concurrency.png"/></imageobject></mediaobject>
+ </figure>
+ <programlisting>
+
+<process name="GroupConcurrency" xmlns="http://jbpm.org/4.0/jpdl">
+
+ <start>
+ <transition to="evaluate project" />
+ </start>
+
+ <group name="evaluate project">
+ <emphasis role="bold"><start>
+ <transition to="distribute document" />
+ </start></emphasis>
+ <state name="distribute document">
+ <transition to="collect feedback" />
+ </state>
+ <state name="collect feedback">
+ <transition to="document finished" />
+ </state>
+ <end name="document finished" />
+
+ <emphasis role="bold"><start>
+ <transition to="make planning" />
+ </start></emphasis>
+ <state name="make planning">
+ <transition to="estimate budget" />
+ </state>
+ <state name="estimate budget">
+ <transition to="planning finished" />
+ </state>
+ <end name="planning finished" />
+
+ <transition to="public project announcement" />
+ </group>
+
+ <state name="public project announcement" />
+
+</process></programlisting>
+ <para>The following scenario will show a scenario in which all
+ wait <literal>state</literal> acitivities are signalled in some random
+ order till all work is done:
+ </para>
+ <programlisting>ProcessInstance pi = executionService
+ .startProcessInstanceByKey("GroupConcurrency");
+
+String documentExecutionId = pi
+ .findActiveExecutionIn("distribute document").getId();
+
+String planningExecutionId = pi
+ .findActiveExecutionIn("make planning").getId();
+
+pi = executionService.signalExecutionById(documentExecutionId);
+assertNotNull(pi.findActiveExecutionIn("collect feedback"));
+assertNotNull(pi.findActiveExecutionIn("make planning"));
+
+pi = executionService.signalExecutionById(planningExecutionId);
+assertNotNull(pi.findActiveExecutionIn("collect feedback"));
+assertNotNull(pi.findActiveExecutionIn("estimate budget"));
+
+pi = executionService.signalExecutionById(planningExecutionId);
+assertNotNull(pi.findActiveExecutionIn("collect feedback"));
+
+pi = executionService.signalExecutionById(documentExecutionId);
+assertNotNull(pi.findActiveExecutionIn("public project announcement"));</programlisting>
+
+ </section>
+
+ <!-- ~~~ GROUP SECRET ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <section id="groupsecret">
+ <title><literal>group</literal> secret</title>
+ <para>Groups also support that you create transitions over group
+ boundaries. So it's possible to have a tranition from an activity
+ outside the group directly to an activity inside the group without
+ modelling a start activity on the border of the group. Similarly
+ with transitions from activities inside the group to activities
+ outside the group. But shhhhhhhhh!
+ Don't tell anyone cause this is not BPMN compliant.
+ </para>
+ </section>
+
+ </section>
+
+</chapter>
Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml 2009-07-03 09:28:20 UTC (rev 5209)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml 2009-07-03 09:32:54 UTC (rev 5210)
@@ -1,50 +0,0 @@
-<chapter id="processvirtualmachine">
- <title>The Process Virtual Machine</title>
- <para>To accomodate multiple process languages and activity pluggability, jBPM is based on
- the Process Virtual Machine. In essence, the Process Virtual Machine is a framework specifying
- executable graphs. A process definition represents an execution flow
- and has a structure that be represented graphically as a diagram.
- </para>
- <para>The Process Virtual Machine separates the structure from a process definition from
- the activity behaviours. The Process Virtual Machine takes the execution of a process from
- one activity to the next and delegates the behaviour of the activities to pluggable Java classes.
- There is an API (<literal>ActivityBehaviour</literal>) that serves as the interface between
- the Process Virtual Machine and the activity behaviour code. Languages like jPDL are
- merely a set of ActivityBehaviour implementations and a parser.
- </para>
- <figure id="example.process.graph">
- <title>Example process definition</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.loan.png"/></imageobject></mediaobject>
- </figure>
- <para>Typically, process definitions are static. A process definition is composed of
- activities and transitions. The runtime behaviour of a activity is encapsulated in a so called
- Activity and it's decoupled from the process graph structure.
- </para>
- <figure id="class.diagram.process.definition">
- <title>Process structure class diagram</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.definition.png"/></imageobject></mediaobject>
- </figure>
- <para>The Process Virtual
- Machine doesn't contain any such activity implementations. It only provides the
- execution environment and an activity API to write <literal>ActivityBehaviour</literal>
- implementations as Java components. Activities can also be wait states. This means
- that the activity control flow goes outside the process system. For example a human task
- or invoking an service asynchronously. While the execution is waiting, the runtime state
- of that execution can be persisted in a DB.
- </para>
- <para>Many executions can be started for one process definition. An execution is a pointer
- that keeps track of the current activity.
- </para>
- <figure id="example.execution">
- <title>Example execution</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/loan.execution.png"/></imageobject></mediaobject>
- </figure>
- <para>To represent concurrent paths of execution, there is
- a hierarchical parent-child relation between so that one process instance can cope with concurrent
- paths of execution.
- </para>
- <figure id="class.diagram.process.execution">
- <title>Execution class diagram</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.execution.png"/></imageobject></mediaobject>
- </figure>
-</chapter>
Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Configuration.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Configuration.xml 2009-07-03 09:28:20 UTC (rev 5209)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Configuration.xml 2009-07-03 09:32:54 UTC (rev 5210)
@@ -1,118 +0,0 @@
-<chapter id="configuration">
- <title>Configuration</title>
-
- <section>
- <title>Configuration basics</title>
-
- <para>The userguide explains how to install jBPM into the most
- common runtime environments. That is the most simple and convenient
- way to get started with jBPM. Please use those instructions.
- These docs provide some background information for developers
- that want to understand more about the way how configurations are
- handled. Use at your own risk :-)
- </para>
- <para>The jbpm.jar contains a number of default configuration
- files that can be imported by the user configuration file.
- </para>
- <para>This way, it's easy to include
- or exclude features for users. And also the configuration details are kept in
- the implementation so users that only import those configuration files
- will not be affected when we release changes in those configuration files.
- </para>
- <para>Configuration files that can be imported by the user's <literal>jbpm.cfg.xml</literal>:</para>
- <itemizedlist>
- <listitem>jbpm.default.cfg.xml</listitem>
- <listitem>jbpm.identity.cfg.xml</listitem>
- <listitem>jbpm.jbossremote.cfg.xml</listitem>
- <listitem>jbpm.jobexecutor.cfg.xml</listitem>
- <listitem>jbpm.tx.hibernate.cfg.xml</listitem>
- <listitem>jbpm.tx.jta.cfg.xml</listitem>
- </itemizedlist>
- <para><literal>jbpm.default.cfg.xml</literal>: Contains the default configurations
- like the services, the hibernate configuration (configured from resource jbpm.hibernate.cfg.xml),
- hibernate session factory, business calendar and so on.
- </para>
- <para>A typical configuration for standard java would look like this:
- </para>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-
- <jbpm-configuration>
-
- <import resource="jbpm.default.cfg.xml" />
- <import resource="jbpm.tx.hibernate.cfg.xml" />
- <import resource="jbpm.jpdl.cfg.xml" />
- <import resource="jbpm.identity.cfg.xml" />
- <import resource="jbpm.jobexecutor.cfg.xml" />
-
- </jbpm-configuration></programlisting>
-
- <para>When you want to change the configuration, first consider
- to change an import with one of the other provided importable
- configuration files.
- </para>
-
- <para>For example, in a JTA environment, replace the import of
- <literal>jbpm.tx.hibernate.cfg.xml</literal>
- with <literal>jbpm.tx.jta.cfg.xml</literal>
- </para>
-
- <para>The second way to define a more customized configuration is to
- specify configuration items directly into the <literal>jbpm.cfg.xml</literal>.
- For an example, see <xref linkend="customizingtheidentitycomponent" /> below.
- The more you customize, the more likely you are doing things we didn't
- anticipate.
- </para>
-
- <para>The jbpm.jar contains also following hibernate mapping configuration files:</para>
- <programlisting>jbpm.execution.hbm.xml
- jbpm.history.hbm.xml
- jbpm.identity.hbm.xml
- jbpm.repository.hbm.xml
- jbpm.task.hbm.xml</programlisting>
- <para>These all map the java domain model objects to a relational database.
- </para>
- <para>Other various configuration files that are included in jbpm.jar:</para>
- <programlisting>jbpm.task.lifecycle.xml
- jbpm.variable.types.xml
- jbpm.wire.bindings.xml
- jbpm.jpdl.activities.xml
- jbpm.jpdl.eventlisteners.xml</programlisting>
-
- <para>Normally it is not necessary to dive into the parsing itself. It's most
- a matter of figuring out how to specify the configuration that you want :-)
- But just in case: To get started on the parsing for the configuration files, see
- </para>
- <itemizedlist>
- <listitem>class org.jbpm.pvm.internal.env.JbpmConfigurationParser</listitem>
- <listitem>resource modules/pvm/src/main/resources/jbpm.wire.bindings.xml</listitem>
- <listitem>package modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/binding</listitem>
- </itemizedlist>
- </section>
-
- <section id="customizingtheidentitycomponent">
- <title>Customizing the identity component</title>
- <para>There are 2 identity components that we support out of the box:
- </para>
- <itemizedlist>
- <listitem>jBPM's built-in identity component: ships with the jBPM project distro</listitem>
- <listitem>JBoss IDM: ships in the JBoss product platforms</listitem>
- </itemizedlist>
- <para>The <literal>jboss/build.xml</literal> installation scripts can be used
- to install jBPM in JBoss using the JBoss IDM component. There is some
- property in that build file to overwrite the default built-in identity component
- with the value for the JBoss IDM component.
- </para>
- <para>If you want to plug in your own identity component, remove the
- following line in the <literal>jbpm.cfg.xml</literal>:
- </para>
- <programlisting><import resource="jbpm.identity.cfg.xml" /></programlisting>
- <para>And in the same file, add following section</para>
- <programlisting><transaction-context>
- <object class="your.package.YourIdentitySessionImpl" />
-</transaction-context></programlisting>
- <para>YourIdentitySessionImpl should implement <literal>org.jbpm.pvm.internal.identity.spi.IdentitySession</literal>
- Making this identity pluggable is not our first target, but it was taken into the design. Let us know how it goes.
- </para>
- </section>
-
-</chapter>
\ No newline at end of file
Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-ProcessVirtualMachine.xml (from rev 5192, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-ProcessVirtualMachine.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-ProcessVirtualMachine.xml (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-ProcessVirtualMachine.xml 2009-07-03 09:32:54 UTC (rev 5210)
@@ -0,0 +1,50 @@
+<chapter id="processvirtualmachine">
+ <title>The Process Virtual Machine</title>
+ <para>To accomodate multiple process languages and activity pluggability, jBPM is based on
+ the Process Virtual Machine. In essence, the Process Virtual Machine is a framework specifying
+ executable graphs. A process definition represents an execution flow
+ and has a structure that be represented graphically as a diagram.
+ </para>
+ <para>The Process Virtual Machine separates the structure from a process definition from
+ the activity behaviours. The Process Virtual Machine takes the execution of a process from
+ one activity to the next and delegates the behaviour of the activities to pluggable Java classes.
+ There is an API (<literal>ActivityBehaviour</literal>) that serves as the interface between
+ the Process Virtual Machine and the activity behaviour code. Languages like jPDL are
+ merely a set of ActivityBehaviour implementations and a parser.
+ </para>
+ <figure id="example.process.graph">
+ <title>Example process definition</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/process.loan.png"/></imageobject></mediaobject>
+ </figure>
+ <para>Typically, process definitions are static. A process definition is composed of
+ activities and transitions. The runtime behaviour of a activity is encapsulated in a so called
+ Activity and it's decoupled from the process graph structure.
+ </para>
+ <figure id="class.diagram.process.definition">
+ <title>Process structure class diagram</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.definition.png"/></imageobject></mediaobject>
+ </figure>
+ <para>The Process Virtual
+ Machine doesn't contain any such activity implementations. It only provides the
+ execution environment and an activity API to write <literal>ActivityBehaviour</literal>
+ implementations as Java components. Activities can also be wait states. This means
+ that the activity control flow goes outside the process system. For example a human task
+ or invoking an service asynchronously. While the execution is waiting, the runtime state
+ of that execution can be persisted in a DB.
+ </para>
+ <para>Many executions can be started for one process definition. An execution is a pointer
+ that keeps track of the current activity.
+ </para>
+ <figure id="example.execution">
+ <title>Example execution</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/loan.execution.png"/></imageobject></mediaobject>
+ </figure>
+ <para>To represent concurrent paths of execution, there is
+ a hierarchical parent-child relation between so that one process instance can cope with concurrent
+ paths of execution.
+ </para>
+ <figure id="class.diagram.process.execution">
+ <title>Execution class diagram</title>
+ <mediaobject><imageobject><imagedata align="center" fileref="images/class.diagram.process.execution.png"/></imageobject></mediaobject>
+ </figure>
+</chapter>
Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-ProcessVirtualMachine.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-AdvancedJpdl.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-AdvancedJpdl.xml 2009-07-03 09:28:20 UTC (rev 5209)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-AdvancedJpdl.xml 2009-07-03 09:32:54 UTC (rev 5210)
@@ -1,581 +0,0 @@
-<chapter id="advancedjpdl">
- <title>Advanced jPDL</title>
-
- <para>This section documents some of the more advanced activities and
- features of jPDL that are still in incubation. Meaning these features
- and activities are not supported yet. But they are available for you
- to try and use. We don't give any stability guarantees on these
- activities and features. So use at your own risk.
- </para>
-
- <!-- ### Timer ########################################################## -->
- <section id="timer">
- <title><literal>timer</literal> </title>
- <para>A timer can be specified in the <literal>transition</literal>
- element in wait state activities such as <literal>state</literal>s,
- <literal>task</literal>s, <literal>sub-process</literal>es and
- <literal>group</literal>s.
- When such a timer fires, that transition is taken.
- </para>
- <para>A timer can also be specified in custom events in wait state
- activities such as <literal>state</literal>s,
- <literal>task</literal>s, <literal>sub-process</literal>es and
- <literal>group</literal>s. The <literal>timer</literal> element
- should then be the first element in the <literal>on</literal> element representing
- the event. In that case the event fires upon the duedate of the timer.
- </para>
- <para>Timers are created when the activity is entered. The timer can fire
- when the execution remains in the activity until the <literal>duedate</literal>.
- When the execution leaves the activity, the timer is cancelled.
- </para>
- <table><title><literal>timer</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>duedate</literal></entry>
- <entry><link linkend="duedateexpressions">duedate expression</link></entry>
- <entry></entry>
- <entry><emphasis role="bold">required</emphasis></entry>
- <entry>Specifies when the timer needs to fire. For
- example: <literal>20 minutes</literal> or
- <literal>3 business days</literal>
- </entry>
- </row>
- <row>
- <entry><literal>repeat</literal></entry>
- <entry><link linkend="duedateexpressions">duedate expression</link></entry>
- <entry></entry>
- <entry>optional</entry>
- <entry>When a timer fires, this attribute specifies when the timer
- needs to fire again. For example: <literal>20 minutes</literal> or
- <literal>3 business days</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <section id="duedateexpressions">
- <title>Duedate expressions</title>
- <para>A duedate expression has the following syntax:</para>
- <programlisting>quantity [business] {second | seconds | minute | minutes |
- hour | hours | day | days | week |
- weeks | month | months | year | years}</programlisting>
- <para>where <literal>quantity</literal> is a positive integer.
- </para>
- <para>And adding the optional indication <literal>business</literal> means
- that only business hours should be taken into account for this duration. Without
- the indication business, the duration will be interpreted as an absolute time period.
- How to configure business hours is explained in <xref linkend="businesscalendar"/>
- </para>
- </section>
-
- <section id="businesscalendar">
- <title>Business calendar</title>
- <para>The default configuration will contain a reference to the file
- <literal>jbpm.business.calendar.xml</literal>. That contains a
- configuration of business hours in the following format:
- </para>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-
-<jbpm-configuration xmlns="http://jbpm.org/xsd/cfg">
-
- <process-engine-context>
-
- <business-calendar>
- <monday hours="9:00-12:00 and 12:30-17:00"/>
- <tuesday hours="9:00-12:00 and 12:30-17:00"/>
- <wednesday hours="9:00-12:00 and 12:30-17:00"/>
- <thursday hours="9:00-12:00 and 12:30-17:00"/>
- <friday hours="9:00-12:00 and 12:30-17:00"/>
- <holiday period="01/07/2008 - 31/08/2008"/>
- </business-calendar>
-
- </process-engine-context>
-
-</jbpm-configuration></programlisting>
- <para>For an example of where the business calendar is used, see
- <xref linkedn="timerbusinesstime" />
- </para>
- </section>
-
- <section id="timertransition">
- <title>Timer transition</title>
- <para>Example TimerTransitionTest shows how to put a timer on a transition.</para>
- <figure id="process.timer.transition">
- <title>The timer transition example process</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.timer.transition.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="TimerTransition" xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="guardedWait" />
- </start>
-
- <state name="guardedWait">
- <transition name="go on" to="next step" />
- <transition name="timeout" to="escalation">
- <emphasis role="bold"><timer duedate="10 minutes" /></emphasis>
- </transition>
- </state>
-
- <state name="next step" />
- <state name="escalation" />
-
-</process></programlisting>
- <para>When an process instance for this process is started, it arrives immediately
- in the <literal>guardedWait</literal> state. At that time, a timer is created that will fire
- after 10 minutes.
- </para>
- <programlisting>Execution processInstance = executionService
- .startProcessInstanceByKey("TimerTransition");</programlisting>
- <para>With the following query, we can query for the timers related to the newly created
- processInstance. We know that there should be exactly one such timer.
- </para>
- <programlisting>Job job = managementService.createJobQuery()
- .timers()
- .processInstanceId(processInstance.getId())
- .uniqueResult();
- </programlisting>
- <para>In a unit test, we won't use the JobExecutor to execute the timer. Instead,
- we execute timers directly in the thread of the unit test. That way it is easy to
- simulate one scenario though an execution.
- </para>
- <para>So as the next step, we assume that the timer will fire. We simulate this
- by executing the timer programmatically:
- </para>
- <programlisting>managementService.executeJob(job.getDbid());</programlisting>
- <para>After that the process instance will have taken the
- <literal>timeout</literal> transition and moved to the escalation state.
- </para>
- <programlisting>processInstance = executionService.findExecutionById(processInstance.getId());
-assertEquals("escalation", processInstance.getActivityName());</programlisting>
- <para>The second scenario in TimerTransitionTest shows that the
- timer is cancelled in case the signal <literal>go on</literal> is given
- before the timer fires. In that case the execution ends up in the
- <literal>next step</literal>.
- </para>
- </section>
-
- <section id="timerevent">
- <title>Timer event</title>
- <para>Example TimerEventTest shows how to put a timer on a custom event.</para>
- <figure id="process.timer.event">
- <title>The timer event example process</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.timer.event.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="TimerEvent" xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="guardedWait" />
- </start>
-
- <state name="guardedWait" >
- <emphasis role="bold"><on event="timeout">
- <timer duedate="10 minutes"/>
- <event-listener class="org.jbpm.examples.timer.event.Escalate" />
- </on></emphasis>
- <transition name="go on" to="next step" />
- </state>
-
- <state name="next step" />
-
-</process></programlisting>
- <para>In this case, if the execution is not signalled within 10 minutes after the
- activity is started, the event <literal>timeout</literal> is fired
- and the event listener <literal>org.jbpm.examples.timer.event.Escalate</literal>
- will be notified.
- </para>
- <para>Again, if the <literal>guardedWait</literal> activity is ended within
- 10 minutes, then the timer is cancelled and the <literal>Escalate</literal>
- event listener will not be notified.
- </para>
- </section>
-
- <section id="timerbusinesstime">
- <title>Timer business time</title>
- <para>Example TimerBusinessTimeTest shows how business time works.</para>
- <figure id="process.timer.event">
- <title>The timer businesstime example process</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.timer.transition.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="TimerBusinessTime" xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="guardedWait" />
- </start>
-
- <state name="guardedWait" >
- <transition name="go on" to="next step" />
- <transition name="timeout" to="escalation" >
- <timer <emphasis role="bold">duedate="9 business hours"</emphasis> />
- </transition>
- </state>
-
- <state name="next step" />
- <state name="escalation" />
-
-</process></programlisting>
- <para>Suppose that a new <literal>TimerBusinessTime</literal> process instance is started
- at 11:30am on a tuesday. The default configured business calendar specifies working hours
- between 9:00-12:00 and 12:30-17:00. So 9 business hours later results in an actual duedate
- for the timer of wednesday 13:00 (1pm).
- </para>
- <para>Since we do not know when the TimerBusinessTimeTest will be ran, we only assert
- in the test that the actual duedate of the scheduled timer at least 24 hours ahead.
- </para>
- </section>
-
- <section id="timerrepeat">
- <title>Timer repeat</title>
- <para>Example TimerRepeatTest shows how to put a timer with a repeat. The attribute
- <literal>repeat</literal> on a timer will cause the timer to be rescheduled automatically
- after it is executed.
- </para>
- <figure id="process.timer.repeat">
- <title>The timer repeat example process</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.timer.event.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="TimerRepeat" xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="guardedWait" />
- </start>
-
- <state name="guardedWait">
- <on event="timeout">
- <timer duedate="20 minutes" <emphasis role="bold">repeat="10 seconds"</emphasis> />
- <event-listener class="org.jbpm.examples.timer.repeat.Escalate" />
- </on>
- <transition name="go on" to="next step"/>
- </state>
-
- <state name="next step"/>
-
-</process></programlisting>
- <para>When a new process is started, a timer is created and the duedate
- will be 20 minutes ahead. When the timer fires, a new timer will be created
- with a duedate of 10 seconds ahead. When that timer fires, a new timer will
- be created again 10 seconds ahead. And so on.
- </para>
- <para>New timers will be created each time the timer fires until the
- <literal>guardedWait</literal> state activity is ended with a signal.
- When the <literal>guardedWait</literal> state activity is ended, the
- existing timer will be cancelled.
- </para>
- </section>
- </section>
-
- <!-- ### GROUP ########################################################## -->
- <section id="group">
- <title><literal>group</literal></title>
-
- <para>A group groups a set of activities in a process. Contained groups must
- be hierarchically nested. A group corresponds to a BPMN expanded sub process.
- </para>
-
- <table><title><literal>group</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>any activity</entry>
- <entry>0..*</entry>
- <entry>Contained activities.
- </entry>
- </row>
- <row>
- <entry><literal>transition</literal></entry>
- <entry>0..*</entry>
- <entry>Outgoing transitions for the group activity.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- ~~~ GROUP SIMPLE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
- <section id="groupsimple">
- <title><literal>group</literal> simple</title>
- <para>This example scenario shows the basic operations of a <literal>group</literal>.
- </para>
- <figure id="process.group.simple">
- <title>The simple group example process</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.group.simple.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="GroupSimple" xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="evaluate document" />
- </start>
-
- <emphasis role="bold"><group name="evaluate document"></emphasis>
- <start>
- <transition to="distribute document" />
- </start>
- <state name="distribute document">
- <transition to="collect feedback" />
- </state>
- <state name="collect feedback">
- <transition name="approved" to="done" />
- <transition name="rejected" to="update document" />
- </state>
- <state name="update document">
- <transition to="distribute document" />
- </state>
- <end name="done" />
- <transition to="publish document" />
- <emphasis role="bold"></group></emphasis>
-
- <state name="publish document" />
-
-</process></programlisting>
- <para>The next code snippet shows a test scenario that rejects a document
- when it comes in the <literal>collect feedback</literal> first time round.
- Then it goes through <literal>update document</literal>, <literal>distribute document</literal>
- and back to <literal>collect feedback</literal>. The second time,
- it will be approved. All activities involved are wait <literal>state</literal>s.
- </para>
- <programlisting>ProcessInstance processInstance = executionService
- .startProcessInstanceByKey("GroupSimple");
-String pid = processInstance.getId();
-assertEquals("distribute document", processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid);
-assertEquals("collect feedback", processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid, "rejected");
-assertEquals("update document", processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid);
-assertEquals("distribute document", processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid);
-assertEquals("collect feedback", processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid, "approved");
-assertEquals("publish document", processInstance.getActivityName());</programlisting>
- </section>
-
- <!-- ~~~ GROUP TIMER ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
- <section id="grouptimer">
- <title><literal>group</literal> timer</title>
- <figure id="process.group.timer">
- <title>The group timer example process</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.group.timer.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="GroupTimer" xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="evaluate document" />
- </start>
-
- <emphasis role="bold"><group name="evaluate document"></emphasis>
- <start>
- <transition to="approve" />
- </start>
- <state name="approve">
- <transition to="done" />
- </state>
- <end name="done" />
-
- <transition to="publish document" />
- <emphasis role="bold"><transition name="timeout" to="escalate">
- <timer duedate="2 business hours" />
- </transition></emphasis>
-
- <emphasis role="bold"></group></emphasis>
-
- <state name="escalate" />
- <state name="publish document" />
-
-</process></programlisting>
- <para>The next code snippet shows a test scenario in which the timer will
- fire before the group activity <literal>evaluate document</literal> completes.
- </para>
- <programlisting>ProcessInstance processInstance = executionService
- .startProcessInstanceByKey("GroupTimer");
-Execution approveExecution = processInstance
- .findActiveExecutionIn("approve");
-assertNotNull(approveExecution);
-
-List<Job> jobs = managementService
- .createJobQuery()
- .processInstanceId(processInstance.getId())
- .list();
-
-assertEquals(1, jobs.size());
-
-Timer timer = (Timer) jobs.get(0);
-
-managementService.executeJob(timer.getDbid());
-
-processInstance = executionService
- .findProcessInstanceById(processInstance.getId());
-assertNotNull(processInstance.findActiveExecutionIn("escalate") );</programlisting>
- </section>
-
- <!-- ~~~ GROUP MULTIPLE ENTRIES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
- <section id="groupmultipleentries">
- <title><literal>group</literal> multiple entries</title>
- <para>This shows how a group can have multiple exclusive entry points.</para>
- <para>Analogue to multiple entry points, a group can also have
- multiple exit points.</para>
- <figure id="process.group.multipleentries">
- <title>The group multiple entries example process</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.group.multipleentries.png"/></imageobject></mediaobject>
- </figure>
- <programlisting><process name="GroupMultipleEntries" xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="choose strategy" />
- </start>
-
- <decision name="choose strategy" expr="#{time}">
- <emphasis role="bold"><transition name="plenty" to="play" />
- <transition name="running out" to="plan" /></emphasis>
- </decision>
-
- <group name="evaluate project">
- <emphasis role="bold"><start name="play">
- <transition to="distribute document" />
- </start></emphasis>
- <state name="distribute document" />
-
- <emphasis role="bold"><start name="plan">
- <transition to="make planning" />
- </start></emphasis>
- <state name="make planning" />
- </group>
-
-</process></programlisting>
- <para>The following scenario will be when there is plenty of time:
- </para>
- <programlisting>Map<String, Object> variables = new HashMap<String, Object>();
-variables.put("time", "plenty");
-
-ProcessInstance pi = executionService
- .startProcessInstanceByKey("GroupMultipleEntries", variables);
-
-assertNotNull(pi.findActiveExecutionIn("distribute document"));</programlisting>
- <para>The following scenario will be when there is time is running out:
- </para>
- <programlisting>Map<String, Object> variables = new HashMap<String, Object>();
-variables.put("time", "running out");
-
-ProcessInstance pi = executionService
- .startProcessInstanceByKey("GroupMultipleEntries", variables);
-
-assertNotNull(pi.findActiveExecutionIn("make planning"));</programlisting>
- </section>
-
- <!-- ~~~ GROUP CONCURRENCY ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
- <section id="groupconcurrency">
- <title><literal>group</literal> concurrency</title>
- <para>This scenario shows how a group can be used to create concurrent paths
- of execution. When an execution arrives in a group, each activity that doesn't
- have incoming transitions is started. So the first activities don't have to be
- start activities. The group takes the default transition out when all contained
- work is done.
- </para>
- <figure id="process.group.concurrency">
- <title>The group concurrency example process</title>
- <mediaobject><imageobject><imagedata align="center" fileref="images/process.group.concurrency.png"/></imageobject></mediaobject>
- </figure>
- <programlisting>
-
-<process name="GroupConcurrency" xmlns="http://jbpm.org/4.0/jpdl">
-
- <start>
- <transition to="evaluate project" />
- </start>
-
- <group name="evaluate project">
- <emphasis role="bold"><start>
- <transition to="distribute document" />
- </start></emphasis>
- <state name="distribute document">
- <transition to="collect feedback" />
- </state>
- <state name="collect feedback">
- <transition to="document finished" />
- </state>
- <end name="document finished" />
-
- <emphasis role="bold"><start>
- <transition to="make planning" />
- </start></emphasis>
- <state name="make planning">
- <transition to="estimate budget" />
- </state>
- <state name="estimate budget">
- <transition to="planning finished" />
- </state>
- <end name="planning finished" />
-
- <transition to="public project announcement" />
- </group>
-
- <state name="public project announcement" />
-
-</process></programlisting>
- <para>The following scenario will show a scenario in which all
- wait <literal>state</literal> acitivities are signalled in some random
- order till all work is done:
- </para>
- <programlisting>ProcessInstance pi = executionService
- .startProcessInstanceByKey("GroupConcurrency");
-
-String documentExecutionId = pi
- .findActiveExecutionIn("distribute document").getId();
-
-String planningExecutionId = pi
- .findActiveExecutionIn("make planning").getId();
-
-pi = executionService.signalExecutionById(documentExecutionId);
-assertNotNull(pi.findActiveExecutionIn("collect feedback"));
-assertNotNull(pi.findActiveExecutionIn("make planning"));
-
-pi = executionService.signalExecutionById(planningExecutionId);
-assertNotNull(pi.findActiveExecutionIn("collect feedback"));
-assertNotNull(pi.findActiveExecutionIn("estimate budget"));
-
-pi = executionService.signalExecutionById(planningExecutionId);
-assertNotNull(pi.findActiveExecutionIn("collect feedback"));
-
-pi = executionService.signalExecutionById(documentExecutionId);
-assertNotNull(pi.findActiveExecutionIn("public project announcement"));</programlisting>
-
- </section>
-
- <!-- ~~~ GROUP SECRET ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
- <section id="groupsecret">
- <title><literal>group</literal> secret</title>
- <para>Groups also support that you create transitions over group
- boundaries. So it's possible to have a tranition from an activity
- outside the group directly to an activity inside the group without
- modelling a start activity on the border of the group. Similarly
- with transitions from activities inside the group to activities
- outside the group. But shhhhhhhhh!
- Don't tell anyone cause this is not BPMN compliant.
- </para>
- </section>
-
- </section>
-
-</chapter>
Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Configuration.xml (from rev 5192, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Configuration.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Configuration.xml (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Configuration.xml 2009-07-03 09:32:54 UTC (rev 5210)
@@ -0,0 +1,118 @@
+<chapter id="configuration">
+ <title>Configuration</title>
+
+ <section>
+ <title>Configuration basics</title>
+
+ <para>The userguide explains how to install jBPM into the most
+ common runtime environments. That is the most simple and convenient
+ way to get started with jBPM. Please use those instructions.
+ These docs provide some background information for developers
+ that want to understand more about the way how configurations are
+ handled. Use at your own risk :-)
+ </para>
+ <para>The jbpm.jar contains a number of default configuration
+ files that can be imported by the user configuration file.
+ </para>
+ <para>This way, it's easy to include
+ or exclude features for users. And also the configuration details are kept in
+ the implementation so users that only import those configuration files
+ will not be affected when we release changes in those configuration files.
+ </para>
+ <para>Configuration files that can be imported by the user's <literal>jbpm.cfg.xml</literal>:</para>
+ <itemizedlist>
+ <listitem>jbpm.default.cfg.xml</listitem>
+ <listitem>jbpm.identity.cfg.xml</listitem>
+ <listitem>jbpm.jbossremote.cfg.xml</listitem>
+ <listitem>jbpm.jobexecutor.cfg.xml</listitem>
+ <listitem>jbpm.tx.hibernate.cfg.xml</listitem>
+ <listitem>jbpm.tx.jta.cfg.xml</listitem>
+ </itemizedlist>
+ <para><literal>jbpm.default.cfg.xml</literal>: Contains the default configurations
+ like the services, the hibernate configuration (configured from resource jbpm.hibernate.cfg.xml),
+ hibernate session factory, business calendar and so on.
+ </para>
+ <para>A typical configuration for standard java would look like this:
+ </para>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+
+ <jbpm-configuration>
+
+ <import resource="jbpm.default.cfg.xml" />
+ <import resource="jbpm.tx.hibernate.cfg.xml" />
+ <import resource="jbpm.jpdl.cfg.xml" />
+ <import resource="jbpm.identity.cfg.xml" />
+ <import resource="jbpm.jobexecutor.cfg.xml" />
+
+ </jbpm-configuration></programlisting>
+
+ <para>When you want to change the configuration, first consider
+ to change an import with one of the other provided importable
+ configuration files.
+ </para>
+
+ <para>For example, in a JTA environment, replace the import of
+ <literal>jbpm.tx.hibernate.cfg.xml</literal>
+ with <literal>jbpm.tx.jta.cfg.xml</literal>
+ </para>
+
+ <para>The second way to define a more customized configuration is to
+ specify configuration items directly into the <literal>jbpm.cfg.xml</literal>.
+ For an example, see <xref linkend="customizingtheidentitycomponent" /> below.
+ The more you customize, the more likely you are doing things we didn't
+ anticipate.
+ </para>
+
+ <para>The jbpm.jar contains also following hibernate mapping configuration files:</para>
+ <programlisting>jbpm.execution.hbm.xml
+ jbpm.history.hbm.xml
+ jbpm.identity.hbm.xml
+ jbpm.repository.hbm.xml
+ jbpm.task.hbm.xml</programlisting>
+ <para>These all map the java domain model objects to a relational database.
+ </para>
+ <para>Other various configuration files that are included in jbpm.jar:</para>
+ <programlisting>jbpm.task.lifecycle.xml
+ jbpm.variable.types.xml
+ jbpm.wire.bindings.xml
+ jbpm.jpdl.activities.xml
+ jbpm.jpdl.eventlisteners.xml</programlisting>
+
+ <para>Normally it is not necessary to dive into the parsing itself. It's most
+ a matter of figuring out how to specify the configuration that you want :-)
+ But just in case: To get started on the parsing for the configuration files, see
+ </para>
+ <itemizedlist>
+ <listitem>class org.jbpm.pvm.internal.env.JbpmConfigurationParser</listitem>
+ <listitem>resource modules/pvm/src/main/resources/jbpm.wire.bindings.xml</listitem>
+ <listitem>package modules/pvm/src/main/java/org/jbpm/pvm/internal/wire/binding</listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="customizingtheidentitycomponent">
+ <title>Customizing the identity component</title>
+ <para>There are 2 identity components that we support out of the box:
+ </para>
+ <itemizedlist>
+ <listitem>jBPM's built-in identity component: ships with the jBPM project distro</listitem>
+ <listitem>JBoss IDM: ships in the JBoss product platforms</listitem>
+ </itemizedlist>
+ <para>The <literal>jboss/build.xml</literal> installation scripts can be used
+ to install jBPM in JBoss using the JBoss IDM component. There is some
+ property in that build file to overwrite the default built-in identity component
+ with the value for the JBoss IDM component.
+ </para>
+ <para>If you want to plug in your own identity component, remove the
+ following line in the <literal>jbpm.cfg.xml</literal>:
+ </para>
+ <programlisting><import resource="jbpm.identity.cfg.xml" /></programlisting>
+ <para>And in the same file, add following section</para>
+ <programlisting><transaction-context>
+ <object class="your.package.YourIdentitySessionImpl" />
+</transaction-context></programlisting>
+ <para>YourIdentitySessionImpl should implement <literal>org.jbpm.pvm.internal.identity.spi.IdentitySession</literal>
+ Making this identity pluggable is not our first target, but it was taken into the design. Let us know how it goes.
+ </para>
+ </section>
+
+</chapter>
\ No newline at end of file
Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch08-Configuration.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml 2009-07-03 09:28:20 UTC (rev 5209)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch13-JBossIntegration.xml 2009-07-03 09:32:54 UTC (rev 5210)
@@ -1,4 +1,4 @@
-<chapter id="identity">
+<chapter id="jbossintegration">
<title>JBoss Integration</title>
<para>
More information about the jbpm-commits
mailing list