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

do-not-reply at jboss.org do-not-reply at jboss.org
Fri Oct 23 17:21:22 EDT 2009


Author: koen.aers at jboss.com
Date: 2009-10-23 17:21:22 -0400 (Fri, 23 Oct 2009)
New Revision: 5782

Modified:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
Log:
added more migration handler documentation

Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml	2009-10-23 21:20:45 UTC (rev 5781)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml	2009-10-23 21:21:22 UTC (rev 5782)
@@ -703,7 +703,9 @@
    	to the newly deployed definition. jBPM contains a tool that exactly supports these use cases.</para>
    	<para>Before delving into the details of the instance migration tool, we have to warn the reader. Though we did a 
    	reasonable attempt at trying to understand the different use cases, there are certainly a number of situations that 
-   	are not yet covered. We welcome any feedback around these use cases very eagerly.</para>
+   	are not yet covered. For now we have concentrated on the limited case where the nodes that are involved in the 
+   	migration are states. The goal is to expand this support to other nodes (e.g. human tasks) in the future.
+   	We welcome any feedback around these use cases very eagerly.</para>
    	<para>For all the examples that follow, we will start from the same original process definition:
    	  <programlisting>
 &lt;process name=&quot;foobar&quot;&gt;
@@ -729,7 +731,7 @@
       <para>The first obvious use case that we wanted to cover is where a new version of a process is deployed for
       which one of the following statements is true:
         <itemizedlist>
-          <listitem>the structure of the process is completely the same</listitem>
+          <listitem>the structure of the process is completely the same and all the nodes have the same name</listitem>
           <listitem>only new nodes have been added but all the nodes from the previous definition still exist</listitem>
         </itemizedlist>
       This use case might be useful if for instance event handler names change between versions, if new processing
@@ -878,10 +880,101 @@
    	
    	<section>
    	  <title>Activity Mappings</title>
+   	  <para>In some cases users will want to map nodes from the previously deployed process definition to
+   	  nodes of the newly deployed process definition. This could be the case when in the newly deployed process
+   	  definition some nodes are deleted or have been replaced by nodes with a different name. To support
+   	  this use case it is possible to specify so-called activity-mapping elements. These elements have
+   	  two attributes: the activity name in the old process definition and the activity name in the new
+   	  process definition. Consider the following process definition:
+   	  <programlisting>
+&lt;process name=&quot;foobar&quot;&gt;
+  &lt;start&gt;
+    &lt;transition to=&quot;a&quot;/&gt;
+  &lt;/start&gt;
+  &lt;state name=&quot;a&quot;&gt;
+    &lt;transition to=&quot;b&quot;&gt;
+  &lt;/state&gt;
+  &lt;state name=&quot;b&quot;&gt;
+    &lt;transition to=&quot;c&quot;/&gt;
+  &lt;/state&gt;
+  &lt;state name=&quot;c&quot;&gt;
+    &lt;transition to=&quot;d&quot;/&gt;
+  &lt;/state&gt;
+  &lt;state name=&quot;d&quot;&gt;
+    &lt;transition to=&quot;end&quot;/&gt;
+  &lt;/state&gt;
+  &lt;end name=&quot;end&quot;/&gt;
+  &lt;migrate-instances&gt;
+    &lt;activity-mapping old-name=&quot;b&quot; new-name=&quot;a&quot;/&gt;
+    &lt;activity-mapping old-name=&quot;c&quot; new-name=&quot;d&quot;/&gt;
+  &lt;/migrate-instances&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	  Deploying this process will put all the instances of the previously deployed process that are waiting
+   	  in the state &quot;b&quot; into the state &quot;a&quot; of the newly deployed process. Likewise all 
+   	  instances of the previously deployed process definition that are waiting in state &quot;c&quot; will be 
+   	  placed in the state &quot;d&quot;. The following piece of code illustrates this:
+   	  <programlisting>
+    ProcessDefinition pd1 = deployProcessDefinition(&quot;foobar&quot;, originalVersion);
+    ProcessInstance pi1 = startAndSignal(pd1, &quot;a&quot;);
+    ProcessInstance pi2 = startAndSignal(pd1, &quot;b&quot;);
+    ProcessInstance pi3 = startAndSignal(pd1, &quot;c&quot;);
+    ProcessDefinition pd2 = deployProcessDefinition(&quot;foobar&quot;, versionWithCorrectMappings);
+    pi1 = executionService.findProcessInstanceById(pi1.getId());
+    pi2 = executionService.findProcessInstanceById(pi2.getId());
+    pi3 = executionService.findProcessInstanceById(pi3.getId());
+    assertEquals(pd2.getId(), pi1.getProcessDefinitionId());
+    assertEquals(pd2.getId(), pi2.getProcessDefinitionId());
+    assertEquals(pd2.getId(), pi3.getProcessDefinitionId());
+    assertEquals(pi1, pi1.findActiveExecutionIn(&quot;a&quot;));
+    assertEquals(pi2, pi2.findActiveExecutionIn(&quot;a&quot;));
+    assertEquals(pi3, pi3.findActiveExecutionIn(&quot;d&quot;));
+    pi1 = executionService.signalExecutionById(pi1.getId());
+    pi2 = executionService.signalExecutionById(pi2.getId());
+    pi2 = executionService.signalExecutionById(pi2.getId());
+    pi3 = executionService.signalExecutionById(pi3.getId());
+    assertEquals(pi1, pi1.findActiveExecutionIn(&quot;b&quot;));
+    assertEquals(pi2, pi2.findActiveExecutionIn(&quot;c&quot;));
+    assertTrue(pi3.isEnded());
+   	  </programlisting>
+   	  </para>
    	</section>
    	
    	<section>
    	  <title>Migration Handlers</title>
+   	  <para>We already mentioned that there are a lot of use cases that we probably didn't think of or for
+   	  which there was not enough time to build support. Exactly for this reason we provide the concept of 
+   	  a migration handler. This is a user defined piece of code that implements the interface 
+   	  &quot;org.jbpm.pvm.internal.migration.MigrationHandler&quot;:
+   	  <programlisting>
+public interface MigrationHandler {  
+
+  void migrateInstance(
+          ProcessDefinition newProcessDefinition, 
+          ProcessInstance processInstance,
+          MigrationDescriptor migrationDescriptor);
+
+}
+   	  </programlisting>
+   	  This migration handler can be specified in the process definition xml and will be executed for each 
+   	  process instance that has to be migrated. Experienced users can use this to do all kinds of bookkeeping
+   	  they need to do when migrating (or ending) process instances. To perform this bookkeeping, it gets 
+   	  of course a handle to the process instance that needs to be migrated, but also to the new process 
+   	  definition and to a so called migration descriptor that contains among others the migration mapping.
+   	  Take e.g. the following example:
+   	  <programlisting>
+&lt;process name=&quot;foobar&quot;&gt;
+  ...
+  &lt;migrate-instances&gt;
+    &lt;migration-handler class=&quot;org.jbpm.test.migration.TestHandler&quot;/&gt;
+  &lt;/migrate-instances&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	  In this case the specified migration handler will be executed for each process instance that needs to
+   	  be migrated AFTER the default migration has been done. If the attribute action is set to &quot;end&quot;
+   	  the migration handler will be called BEFORE the process instance is ended. If more than one migration
+   	  handler is specified, they will be executed one after another.
+   	  </para>
    	</section>
    	
   </section>



More information about the jbpm-commits mailing list