[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>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
+
+&lt;jbpm-configuration xmlns=&quot;http://jbpm.org/xsd/cfg&quot;&gt;
+
+  &lt;process-engine-context&gt;
+      
+      &lt;business-calendar&gt;
+        &lt;monday    hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
+        &lt;tuesday   hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
+        &lt;wednesday hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
+        &lt;thursday  hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
+        &lt;friday    hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
+        &lt;holiday period=&quot;01/07/2008 - 31/08/2008&quot;/&gt;
+      &lt;/business-calendar&gt;
+
+  &lt;/process-engine-context&gt;
+
+&lt;/jbpm-configuration&gt;</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>&lt;process name=&quot;TimerTransition&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+
+  &lt;start&gt;
+    &lt;transition to=&quot;guardedWait&quot; /&gt;
+  &lt;/start&gt;
+
+  &lt;state name=&quot;guardedWait&quot;&gt;
+    &lt;transition name=&quot;go on&quot; to=&quot;next step&quot; /&gt;
+    &lt;transition name=&quot;timeout&quot; to=&quot;escalation&quot;&gt;
+      <emphasis role="bold">&lt;timer duedate=&quot;10 minutes&quot; /&gt;</emphasis>
+    &lt;/transition&gt;
+  &lt;/state&gt;
+  
+  &lt;state name=&quot;next step&quot; /&gt;
+  &lt;state name=&quot;escalation&quot; /&gt;
+
+&lt;/process&gt;</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(&quot;TimerTransition&quot;);</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(&quot;escalation&quot;, 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>&lt;process name=&quot;TimerEvent&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+
+  &lt;start&gt;
+    &lt;transition to=&quot;guardedWait&quot; /&gt;
+  &lt;/start&gt;
+
+  &lt;state name=&quot;guardedWait&quot; &gt;
+    <emphasis role="bold">&lt;on event=&quot;timeout&quot;&gt;
+      &lt;timer duedate=&quot;10 minutes&quot;/&gt;
+      &lt;event-listener class=&quot;org.jbpm.examples.timer.event.Escalate&quot; /&gt;
+    &lt;/on&gt;</emphasis>
+    &lt;transition name=&quot;go on&quot; to=&quot;next step&quot; /&gt;
+  &lt;/state&gt;
+  
+  &lt;state name=&quot;next step&quot; /&gt;
+
+&lt;/process&gt;</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>&lt;process name=&quot;TimerBusinessTime&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+
+  &lt;start&gt;
+    &lt;transition to=&quot;guardedWait&quot; /&gt;
+  &lt;/start&gt;
+
+  &lt;state name=&quot;guardedWait&quot; &gt;
+    &lt;transition name=&quot;go on&quot; to=&quot;next step&quot; /&gt;
+    &lt;transition name=&quot;timeout&quot; to=&quot;escalation&quot; &gt;
+      &lt;timer <emphasis role="bold">duedate=&quot;9 business hours&quot;</emphasis> /&gt; 
+    &lt;/transition&gt;
+  &lt;/state&gt;
+  
+  &lt;state name=&quot;next step&quot; /&gt;
+  &lt;state name=&quot;escalation&quot; /&gt;
+
+&lt;/process&gt;</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>&lt;process name=&quot;TimerRepeat&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+
+  &lt;start&gt;
+    &lt;transition to=&quot;guardedWait&quot; /&gt;
+  &lt;/start&gt;
+
+  &lt;state name=&quot;guardedWait&quot;&gt;
+    &lt;on event=&quot;timeout&quot;&gt;
+      &lt;timer duedate=&quot;20 minutes&quot; <emphasis role="bold">repeat=&quot;10 seconds&quot;</emphasis> /&gt;
+      &lt;event-listener class=&quot;org.jbpm.examples.timer.repeat.Escalate&quot; /&gt;
+    &lt;/on&gt;
+    &lt;transition name=&quot;go on&quot; to=&quot;next step&quot;/&gt;
+  &lt;/state&gt;
+  
+  &lt;state name=&quot;next step&quot;/&gt;
+
+&lt;/process&gt;</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>&lt;process name=&quot;GroupSimple&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+
+  &lt;start&gt;
+    &lt;transition to=&quot;evaluate document&quot; /&gt;
+  &lt;/start&gt;
+  
+  <emphasis role="bold">&lt;group name=&quot;evaluate document&quot;&gt;</emphasis>
+    &lt;start&gt;
+      &lt;transition to=&quot;distribute document&quot; /&gt;
+    &lt;/start&gt;
+    &lt;state name=&quot;distribute document&quot;&gt;
+      &lt;transition to=&quot;collect feedback&quot; /&gt;
+    &lt;/state&gt;
+    &lt;state name=&quot;collect feedback&quot;&gt;
+      &lt;transition name=&quot;approved&quot; to=&quot;done&quot; /&gt;
+      &lt;transition name=&quot;rejected&quot; to=&quot;update document&quot; /&gt;
+    &lt;/state&gt;
+    &lt;state name=&quot;update document&quot;&gt;
+      &lt;transition to=&quot;distribute document&quot; /&gt;
+    &lt;/state&gt;
+    &lt;end name=&quot;done&quot; /&gt;
+    &lt;transition to=&quot;publish document&quot; /&gt;
+  <emphasis role="bold">&lt;/group&gt;</emphasis>
+  
+  &lt;state name=&quot;publish document&quot; /&gt;
+
+&lt;/process&gt;</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(&quot;GroupSimple&quot;);
+String pid = processInstance.getId();
+assertEquals(&quot;distribute document&quot;, processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid);
+assertEquals(&quot;collect feedback&quot;, processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid, &quot;rejected&quot;);
+assertEquals(&quot;update document&quot;, processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid);
+assertEquals(&quot;distribute document&quot;, processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid);
+assertEquals(&quot;collect feedback&quot;, processInstance.getActivityName());
+
+processInstance = executionService.signalExecutionById(pid, &quot;approved&quot;);
+assertEquals(&quot;publish document&quot;, 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>&lt;process name=&quot;GroupTimer&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+
+  &lt;start&gt;
+    &lt;transition to=&quot;evaluate document&quot; /&gt;
+  &lt;/start&gt;
+  
+  <emphasis role="bold">&lt;group name=&quot;evaluate document&quot;&gt;</emphasis>
+    &lt;start&gt;
+      &lt;transition to=&quot;approve&quot; /&gt;
+    &lt;/start&gt;
+    &lt;state name=&quot;approve&quot;&gt;
+      &lt;transition to=&quot;done&quot; /&gt;
+    &lt;/state&gt;
+    &lt;end name=&quot;done&quot; /&gt;
+    
+    &lt;transition to=&quot;publish document&quot; /&gt;
+    <emphasis role="bold">&lt;transition name=&quot;timeout&quot; to=&quot;escalate&quot;&gt;
+      &lt;timer duedate=&quot;2 business hours&quot; /&gt;
+    &lt;/transition&gt;</emphasis>
+    
+  <emphasis role="bold">&lt;/group&gt;</emphasis>
+  
+  &lt;state name=&quot;escalate&quot; /&gt;
+  &lt;state name=&quot;publish document&quot; /&gt;
+
+&lt;/process&gt;</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(&quot;GroupTimer&quot;);
+Execution approveExecution = processInstance
+       .findActiveExecutionIn(&quot;approve&quot;);
+assertNotNull(approveExecution);
+
+List&lt;Job&gt; 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(&quot;escalate&quot;) );</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>&lt;process name=&quot;GroupMultipleEntries&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+
+  &lt;start&gt;
+    &lt;transition to=&quot;choose strategy&quot; /&gt;
+  &lt;/start&gt;
+  
+  &lt;decision name=&quot;choose strategy&quot; expr=&quot;#{time}&quot;&gt;
+    <emphasis role="bold">&lt;transition name=&quot;plenty&quot; to=&quot;play&quot; /&gt;
+    &lt;transition name=&quot;running out&quot; to=&quot;plan&quot; /&gt;</emphasis>
+  &lt;/decision&gt;
+  
+  &lt;group name=&quot;evaluate project&quot;&gt;
+    <emphasis role="bold">&lt;start name=&quot;play&quot;&gt;
+      &lt;transition to=&quot;distribute document&quot; /&gt;
+    &lt;/start&gt;</emphasis>
+    &lt;state name=&quot;distribute document&quot; /&gt;
+
+    <emphasis role="bold">&lt;start name=&quot;plan&quot;&gt;
+      &lt;transition to=&quot;make planning&quot; /&gt;
+    &lt;/start&gt;</emphasis>
+    &lt;state name=&quot;make planning&quot; /&gt;
+  &lt;/group&gt;
+  
+&lt;/process&gt;</programlisting>
+      <para>The following scenario will be when there is plenty of time: 
+      </para>
+      <programlisting>Map&lt;String, Object&gt; variables = new HashMap&lt;String, Object&gt;();
+variables.put(&quot;time&quot;, &quot;plenty&quot;);
+
+ProcessInstance pi = executionService
+    .startProcessInstanceByKey(&quot;GroupMultipleEntries&quot;, variables);
+
+assertNotNull(pi.findActiveExecutionIn(&quot;distribute document&quot;));</programlisting>
+      <para>The following scenario will be when there is time is running out: 
+      </para>
+      <programlisting>Map&lt;String, Object&gt; variables = new HashMap&lt;String, Object&gt;();
+variables.put(&quot;time&quot;, &quot;running out&quot;);
+
+ProcessInstance pi = executionService
+    .startProcessInstanceByKey(&quot;GroupMultipleEntries&quot;, variables);
+
+assertNotNull(pi.findActiveExecutionIn(&quot;make planning&quot;));</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>
+
+&lt;process name=&quot;GroupConcurrency&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
+
+  &lt;start&gt;
+    &lt;transition to=&quot;evaluate project&quot; /&gt;
+  &lt;/start&gt;
+  
+  &lt;group name=&quot;evaluate project&quot;&gt;
+    <emphasis role="bold">&lt;start&gt;
+      &lt;transition to=&quot;distribute document&quot; /&gt;
+    &lt;/start&gt;</emphasis>
+    &lt;state name=&quot;distribute document&quot;&gt;
+      &lt;transition to=&quot;collect feedback&quot; /&gt;
+    &lt;/state&gt;
+    &lt;state name=&quot;collect feedback&quot;&gt;
+      &lt;transition to=&quot;document finished&quot; /&gt;
+    &lt;/state&gt;
+    &lt;end name=&quot;document finished&quot; /&gt;
+
+    <emphasis role="bold">&lt;start&gt;
+      &lt;transition to=&quot;make planning&quot; /&gt;
+    &lt;/start&gt;</emphasis>
+    &lt;state name=&quot;make planning&quot;&gt;
+      &lt;transition to=&quot;estimate budget&quot; /&gt;
+    &lt;/state&gt;
+    &lt;state name=&quot;estimate budget&quot;&gt;
+      &lt;transition to=&quot;planning finished&quot; /&gt;
+    &lt;/state&gt;
+    &lt;end name=&quot;planning finished&quot; /&gt;
+
+    &lt;transition to=&quot;public project announcement&quot; /&gt;
+  &lt;/group&gt;
+  
+  &lt;state name=&quot;public project announcement&quot; /&gt;
+
+&lt;/process&gt;</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(&quot;GroupConcurrency&quot;);
+
+String documentExecutionId = pi
+    .findActiveExecutionIn(&quot;distribute document&quot;).getId();
+
+String planningExecutionId = pi
+    .findActiveExecutionIn(&quot;make planning&quot;).getId();
+
+pi = executionService.signalExecutionById(documentExecutionId);
+assertNotNull(pi.findActiveExecutionIn(&quot;collect feedback&quot;));
+assertNotNull(pi.findActiveExecutionIn(&quot;make planning&quot;));
+
+pi = executionService.signalExecutionById(planningExecutionId);
+assertNotNull(pi.findActiveExecutionIn(&quot;collect feedback&quot;));
+assertNotNull(pi.findActiveExecutionIn(&quot;estimate budget&quot;));
+
+pi = executionService.signalExecutionById(planningExecutionId);
+assertNotNull(pi.findActiveExecutionIn(&quot;collect feedback&quot;));
+
+pi = executionService.signalExecutionById(documentExecutionId);
+assertNotNull(pi.findActiveExecutionIn(&quot;public project announcement&quot;));</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>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
-  
-  &lt;jbpm-configuration&gt;
-  
-    &lt;import resource=&quot;jbpm.default.cfg.xml&quot; /&gt;
-    &lt;import resource=&quot;jbpm.tx.hibernate.cfg.xml&quot; /&gt;
-    &lt;import resource=&quot;jbpm.jpdl.cfg.xml&quot; /&gt;
-    &lt;import resource=&quot;jbpm.identity.cfg.xml&quot; /&gt;
-    &lt;import resource=&quot;jbpm.jobexecutor.cfg.xml&quot; /&gt;
-  
-  &lt;/jbpm-configuration&gt;</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>&lt;import resource=&quot;jbpm.identity.cfg.xml&quot; /&gt;</programlisting>
-    <para>And in the same file, add following section</para>
-    <programlisting>&lt;transaction-context&gt;
-  &lt;object class=&quot;your.package.YourIdentitySessionImpl&quot; /&gt;
-&lt;/transaction-context&gt;</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>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
-
-&lt;jbpm-configuration xmlns=&quot;http://jbpm.org/xsd/cfg&quot;&gt;
-
-  &lt;process-engine-context&gt;
-      
-      &lt;business-calendar&gt;
-			  &lt;monday    hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
-			  &lt;tuesday   hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
-			  &lt;wednesday hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
-			  &lt;thursday  hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
-			  &lt;friday    hours=&quot;9:00-12:00 and 12:30-17:00&quot;/&gt;
-			  &lt;holiday period=&quot;01/07/2008 - 31/08/2008&quot;/&gt;
-			&lt;/business-calendar&gt;
-
-  &lt;/process-engine-context&gt;
-
-&lt;/jbpm-configuration&gt;</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>&lt;process name=&quot;TimerTransition&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
-
-  &lt;start&gt;
-    &lt;transition to=&quot;guardedWait&quot; /&gt;
-  &lt;/start&gt;
-
-  &lt;state name=&quot;guardedWait&quot;&gt;
-    &lt;transition name=&quot;go on&quot; to=&quot;next step&quot; /&gt;
-    &lt;transition name=&quot;timeout&quot; to=&quot;escalation&quot;&gt;
-      <emphasis role="bold">&lt;timer duedate=&quot;10 minutes&quot; /&gt;</emphasis>
-    &lt;/transition&gt;
-  &lt;/state&gt;
-  
-  &lt;state name=&quot;next step&quot; /&gt;
-  &lt;state name=&quot;escalation&quot; /&gt;
-
-&lt;/process&gt;</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(&quot;TimerTransition&quot;);</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(&quot;escalation&quot;, 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>&lt;process name=&quot;TimerEvent&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
-
-  &lt;start&gt;
-    &lt;transition to=&quot;guardedWait&quot; /&gt;
-  &lt;/start&gt;
-
-  &lt;state name=&quot;guardedWait&quot; &gt;
-    <emphasis role="bold">&lt;on event=&quot;timeout&quot;&gt;
-      &lt;timer duedate=&quot;10 minutes&quot;/&gt;
-      &lt;event-listener class=&quot;org.jbpm.examples.timer.event.Escalate&quot; /&gt;
-    &lt;/on&gt;</emphasis>
-    &lt;transition name=&quot;go on&quot; to=&quot;next step&quot; /&gt;
-  &lt;/state&gt;
-  
-  &lt;state name=&quot;next step&quot; /&gt;
-
-&lt;/process&gt;</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>&lt;process name=&quot;TimerBusinessTime&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
-
-  &lt;start&gt;
-    &lt;transition to=&quot;guardedWait&quot; /&gt;
-  &lt;/start&gt;
-
-  &lt;state name=&quot;guardedWait&quot; &gt;
-    &lt;transition name=&quot;go on&quot; to=&quot;next step&quot; /&gt;
-    &lt;transition name=&quot;timeout&quot; to=&quot;escalation&quot; &gt;
-      &lt;timer <emphasis role="bold">duedate=&quot;9 business hours&quot;</emphasis> /&gt; 
-    &lt;/transition&gt;
-  &lt;/state&gt;
-  
-  &lt;state name=&quot;next step&quot; /&gt;
-  &lt;state name=&quot;escalation&quot; /&gt;
-
-&lt;/process&gt;</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>&lt;process name=&quot;TimerRepeat&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
-
-  &lt;start&gt;
-    &lt;transition to=&quot;guardedWait&quot; /&gt;
-  &lt;/start&gt;
-
-  &lt;state name=&quot;guardedWait&quot;&gt;
-    &lt;on event=&quot;timeout&quot;&gt;
-      &lt;timer duedate=&quot;20 minutes&quot; <emphasis role="bold">repeat=&quot;10 seconds&quot;</emphasis> /&gt;
-      &lt;event-listener class=&quot;org.jbpm.examples.timer.repeat.Escalate&quot; /&gt;
-    &lt;/on&gt;
-    &lt;transition name=&quot;go on&quot; to=&quot;next step&quot;/&gt;
-  &lt;/state&gt;
-  
-  &lt;state name=&quot;next step&quot;/&gt;
-
-&lt;/process&gt;</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>&lt;process name=&quot;GroupSimple&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
-
-  &lt;start&gt;
-    &lt;transition to=&quot;evaluate document&quot; /&gt;
-  &lt;/start&gt;
-  
-  <emphasis role="bold">&lt;group name=&quot;evaluate document&quot;&gt;</emphasis>
-    &lt;start&gt;
-      &lt;transition to=&quot;distribute document&quot; /&gt;
-    &lt;/start&gt;
-    &lt;state name=&quot;distribute document&quot;&gt;
-      &lt;transition to=&quot;collect feedback&quot; /&gt;
-    &lt;/state&gt;
-    &lt;state name=&quot;collect feedback&quot;&gt;
-      &lt;transition name=&quot;approved&quot; to=&quot;done&quot; /&gt;
-      &lt;transition name=&quot;rejected&quot; to=&quot;update document&quot; /&gt;
-    &lt;/state&gt;
-    &lt;state name=&quot;update document&quot;&gt;
-      &lt;transition to=&quot;distribute document&quot; /&gt;
-    &lt;/state&gt;
-    &lt;end name=&quot;done&quot; /&gt;
-    &lt;transition to=&quot;publish document&quot; /&gt;
-  <emphasis role="bold">&lt;/group&gt;</emphasis>
-  
-  &lt;state name=&quot;publish document&quot; /&gt;
-
-&lt;/process&gt;</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(&quot;GroupSimple&quot;);
-String pid = processInstance.getId();
-assertEquals(&quot;distribute document&quot;, processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid);
-assertEquals(&quot;collect feedback&quot;, processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid, &quot;rejected&quot;);
-assertEquals(&quot;update document&quot;, processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid);
-assertEquals(&quot;distribute document&quot;, processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid);
-assertEquals(&quot;collect feedback&quot;, processInstance.getActivityName());
-
-processInstance = executionService.signalExecutionById(pid, &quot;approved&quot;);
-assertEquals(&quot;publish document&quot;, 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>&lt;process name=&quot;GroupTimer&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
-
-  &lt;start&gt;
-    &lt;transition to=&quot;evaluate document&quot; /&gt;
-  &lt;/start&gt;
-  
-  <emphasis role="bold">&lt;group name=&quot;evaluate document&quot;&gt;</emphasis>
-    &lt;start&gt;
-      &lt;transition to=&quot;approve&quot; /&gt;
-    &lt;/start&gt;
-    &lt;state name=&quot;approve&quot;&gt;
-      &lt;transition to=&quot;done&quot; /&gt;
-    &lt;/state&gt;
-    &lt;end name=&quot;done&quot; /&gt;
-    
-    &lt;transition to=&quot;publish document&quot; /&gt;
-    <emphasis role="bold">&lt;transition name=&quot;timeout&quot; to=&quot;escalate&quot;&gt;
-      &lt;timer duedate=&quot;2 business hours&quot; /&gt;
-    &lt;/transition&gt;</emphasis>
-    
-  <emphasis role="bold">&lt;/group&gt;</emphasis>
-  
-  &lt;state name=&quot;escalate&quot; /&gt;
-  &lt;state name=&quot;publish document&quot; /&gt;
-
-&lt;/process&gt;</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(&quot;GroupTimer&quot;);
-Execution approveExecution = processInstance
-       .findActiveExecutionIn(&quot;approve&quot;);
-assertNotNull(approveExecution);
-
-List&lt;Job&gt; 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(&quot;escalate&quot;) );</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>&lt;process name=&quot;GroupMultipleEntries&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
-
-  &lt;start&gt;
-    &lt;transition to=&quot;choose strategy&quot; /&gt;
-  &lt;/start&gt;
-  
-  &lt;decision name=&quot;choose strategy&quot; expr=&quot;#{time}&quot;&gt;
-    <emphasis role="bold">&lt;transition name=&quot;plenty&quot; to=&quot;play&quot; /&gt;
-    &lt;transition name=&quot;running out&quot; to=&quot;plan&quot; /&gt;</emphasis>
-  &lt;/decision&gt;
-  
-  &lt;group name=&quot;evaluate project&quot;&gt;
-    <emphasis role="bold">&lt;start name=&quot;play&quot;&gt;
-      &lt;transition to=&quot;distribute document&quot; /&gt;
-    &lt;/start&gt;</emphasis>
-    &lt;state name=&quot;distribute document&quot; /&gt;
-
-    <emphasis role="bold">&lt;start name=&quot;plan&quot;&gt;
-      &lt;transition to=&quot;make planning&quot; /&gt;
-    &lt;/start&gt;</emphasis>
-    &lt;state name=&quot;make planning&quot; /&gt;
-  &lt;/group&gt;
-  
-&lt;/process&gt;</programlisting>
-      <para>The following scenario will be when there is plenty of time: 
-      </para>
-      <programlisting>Map&lt;String, Object&gt; variables = new HashMap&lt;String, Object&gt;();
-variables.put(&quot;time&quot;, &quot;plenty&quot;);
-
-ProcessInstance pi = executionService
-    .startProcessInstanceByKey(&quot;GroupMultipleEntries&quot;, variables);
-
-assertNotNull(pi.findActiveExecutionIn(&quot;distribute document&quot;));</programlisting>
-      <para>The following scenario will be when there is time is running out: 
-      </para>
-      <programlisting>Map&lt;String, Object&gt; variables = new HashMap&lt;String, Object&gt;();
-variables.put(&quot;time&quot;, &quot;running out&quot;);
-
-ProcessInstance pi = executionService
-    .startProcessInstanceByKey(&quot;GroupMultipleEntries&quot;, variables);
-
-assertNotNull(pi.findActiveExecutionIn(&quot;make planning&quot;));</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>
-
-&lt;process name=&quot;GroupConcurrency&quot; xmlns=&quot;http://jbpm.org/4.0/jpdl&quot;&gt;
-
-  &lt;start&gt;
-    &lt;transition to=&quot;evaluate project&quot; /&gt;
-  &lt;/start&gt;
-  
-  &lt;group name=&quot;evaluate project&quot;&gt;
-    <emphasis role="bold">&lt;start&gt;
-      &lt;transition to=&quot;distribute document&quot; /&gt;
-    &lt;/start&gt;</emphasis>
-    &lt;state name=&quot;distribute document&quot;&gt;
-      &lt;transition to=&quot;collect feedback&quot; /&gt;
-    &lt;/state&gt;
-    &lt;state name=&quot;collect feedback&quot;&gt;
-      &lt;transition to=&quot;document finished&quot; /&gt;
-    &lt;/state&gt;
-    &lt;end name=&quot;document finished&quot; /&gt;
-
-    <emphasis role="bold">&lt;start&gt;
-      &lt;transition to=&quot;make planning&quot; /&gt;
-    &lt;/start&gt;</emphasis>
-    &lt;state name=&quot;make planning&quot;&gt;
-      &lt;transition to=&quot;estimate budget&quot; /&gt;
-    &lt;/state&gt;
-    &lt;state name=&quot;estimate budget&quot;&gt;
-      &lt;transition to=&quot;planning finished&quot; /&gt;
-    &lt;/state&gt;
-    &lt;end name=&quot;planning finished&quot; /&gt;
-
-    &lt;transition to=&quot;public project announcement&quot; /&gt;
-  &lt;/group&gt;
-  
-  &lt;state name=&quot;public project announcement&quot; /&gt;
-
-&lt;/process&gt;</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(&quot;GroupConcurrency&quot;);
-
-String documentExecutionId = pi
-    .findActiveExecutionIn(&quot;distribute document&quot;).getId();
-
-String planningExecutionId = pi
-    .findActiveExecutionIn(&quot;make planning&quot;).getId();
-
-pi = executionService.signalExecutionById(documentExecutionId);
-assertNotNull(pi.findActiveExecutionIn(&quot;collect feedback&quot;));
-assertNotNull(pi.findActiveExecutionIn(&quot;make planning&quot;));
-
-pi = executionService.signalExecutionById(planningExecutionId);
-assertNotNull(pi.findActiveExecutionIn(&quot;collect feedback&quot;));
-assertNotNull(pi.findActiveExecutionIn(&quot;estimate budget&quot;));
-
-pi = executionService.signalExecutionById(planningExecutionId);
-assertNotNull(pi.findActiveExecutionIn(&quot;collect feedback&quot;));
-
-pi = executionService.signalExecutionById(documentExecutionId);
-assertNotNull(pi.findActiveExecutionIn(&quot;public project announcement&quot;));</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>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
+  
+  &lt;jbpm-configuration&gt;
+  
+    &lt;import resource=&quot;jbpm.default.cfg.xml&quot; /&gt;
+    &lt;import resource=&quot;jbpm.tx.hibernate.cfg.xml&quot; /&gt;
+    &lt;import resource=&quot;jbpm.jpdl.cfg.xml&quot; /&gt;
+    &lt;import resource=&quot;jbpm.identity.cfg.xml&quot; /&gt;
+    &lt;import resource=&quot;jbpm.jobexecutor.cfg.xml&quot; /&gt;
+  
+  &lt;/jbpm-configuration&gt;</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>&lt;import resource=&quot;jbpm.identity.cfg.xml&quot; /&gt;</programlisting>
+    <para>And in the same file, add following section</para>
+    <programlisting>&lt;transaction-context&gt;
+  &lt;object class=&quot;your.package.YourIdentitySessionImpl&quot; /&gt;
+&lt;/transaction-context&gt;</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