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

[do-not-reply at jboss.org]

Author: tom.baeyens at jboss.com
Date: 2009-06-11 04:16:50 -0400 (Thu, 11 Jun 2009)
New Revision: 5026

Modified:
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml
Log:
improving docs on async continuations based on joram's feedback

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml	2009-06-10 19:16:22 UTC (rev 5025)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch06-Jpdl.xml	2009-06-11 08:16:50 UTC (rev 5026)
@@ -2522,7 +2522,7 @@
     <title>Asynchronous continuations</title>
     <para>Each invocation of <literal>ExecutionService.startProcessInstanceById(...)</literal>
     or <literal>ExecutionService.signalProcessInstanceById(...)</literal> will cause
-    the process to be executed in the thread of the client.  In other words, those
+    the process to be executed in the thread it was called from (=client).  In other words, those
     methods will only return after the process execution has arrived in a wait state.
     </para>
     <para>This default behaviour has a couple of advantages: user application transactions
@@ -2530,15 +2530,18 @@
     transaction context.  Secondly, it's possible for a client to get an exception in 
     case something goes wrong during execution of the process.  Usually, the automatic 
     work that has to be done as part of the process inbetween two wait states is 
-    relatively small.  E.g. &lt; 1 second, even if multiple automatic activities 
+    relatively small.  Even if multiple automatic activities 
     are executed inbetween 2 wait states.   So in most situations, it's good to 
     do all that work in a single transaction. This explains that the default behaviour 
     of jPDL is to perform all work of the process synchronously in the thread of client.     
     </para>
-    <para>For those cases where it is needed, jPDL allows for very fine grained control over 
+    <para>For those cases where you don't want the call to jBPM to be blocking until
+    all the automatic work is done, jPDL allows for very fine grained control over 
     transaction boundaries.  On various places in the process, asynchronous continuations 
-    can be introduced.  Asynchronous continuations are placed on places where logically 
-    the jBPM engine remains in control for executing a series of automatic steps.
+    can be introduced.  Asynchronous continuations cause the transaction to commit and 
+    the jBPM method invocation will return.  jBPM will then start a new transaction in a 
+    new thread and continue the rest of the automatic process work asynchronously.  jBPM
+    uses asynchronous messaging internally to accomplish this.   
     </para>
     <para>Upon an asynchronous continuation, an asynchronous message will be sent as 
     part of the currently ongoing transaction.  And then the originally invoked method 
@@ -2586,8 +2589,10 @@
       The ongoing transaction is committed and the element is executed in a
       new transaction.  Transactional asynchronous messaging is used by the jBPM 
       implementation to achieve this.  Exclusive messages will not be processed 
-      concurrently.  The JobExecutor(s) will serialize all exclusive job 
-      executions.  This can be used to prevent optimistic locking failures in case 
+      concurrently.  jBPM will make sure that exclusive jobs for the same process instance 
+      are not executed concurrently, even if your jBPM configuration has multiple 
+      asynchronous message processors (like the JobExecutor) running on different 
+      systems.    This can be used to prevent optimistic locking failures in case 
       multiple, potentially conflicting jobs are scheduled in the same transaction.
       </listitem>
     </itemizedlist>
@@ -2647,7 +2652,7 @@
       <para>In a normal configuration, the job executor will automatically pick up 
       the message and execute it.  But for testing scenarios and for these examples we 
       want to control when messages are executed so the job executor is not configured.  
-      Therefor we have to execute the jobs manually like this:
+      Therefore we have to execute the jobs manually like this:
       </para>
       <programlisting>Job job = managementService.createJobQuery()
   .processInstanceId(processInstanceId)