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

do-not-reply at jboss.org do-not-reply at jboss.org
Thu Oct 22 21:59:01 EDT 2009


Author: koen.aers at jboss.com
Date: 2009-10-22 21:59:01 -0400 (Thu, 22 Oct 2009)
New Revision: 5772

Modified:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml
Log:
added a section about instance migration

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-22 12:55:53 UTC (rev 5771)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch02-Incubation.xml	2009-10-23 01:59:01 UTC (rev 5772)
@@ -691,7 +691,201 @@
       </para>
     </section>
   </section>
+  
+  <section id="instancemigration">
+    <title>Instance Migration</title>
+    <para>By default the behaviour of jBPM upon redeployment is to start new process instances with the newly deployed version.
+   	Also, it is possible to start new process instances using a specified older version if needed. The existing running 
+   	process instances always keep running following the definition that they were started in. But what when a customer 
+   	or some piece of legislation mandates that this behaviour is not enough? We could e.g. think of a situation where
+   	process instances do not make sense anymore when a new definition is deployed. In this case these instances should be
+   	ended. In another situation it might be needed that all (or even some particular) instances are migrated and moved 
+   	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>
+   	<para>For all the examples that follow, we will start from the same original 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;end&quot;/&gt;
+  &lt;/state&gt;
+  &lt;end name=&quot;end&quot;/&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	</para>
+   	
+   	<section>
+      <title>Simple Migration</title>
+      <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>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
+      has to be inserted or if new paths of execution have to be added. Consider the following modification of the
+      above process definition to indicate that running instances have to be migrated:
+   	  <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;end&quot;/&gt;
+  &lt;/state&gt;
+  &lt;end name=&quot;end&quot;/&gt;
+  &lt;migrate-instances/&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	  When this second process is deployed the running instances of the previous version - and only of the previous
+   	  version - will be migrated to the new version. We&quot;ll explain later what to do if you want more than only the
+   	  instances of the previous version to be migrated. Assume that when deploying the second version there would
+   	  be one process instance in the state &quot;a&quot; and one process instance in the state &quot;b&quot;. The following snippet 
+   	  in a unit test would be valid:
+   	  <programlisting>
+    ProcessDefinition pd1 = deployProcessDefinition(&quot;foobar&quot;, originalVersion);
+    ProcessInstance pi1 = startAndSignal(pd1, &quot;a&quot;);
+    ProcessInstance pi2 = startAndSignal(pd1, &quot;b&quot;);
+    ProcessDefinition pd2 = deployProcessDefinition(&quot;foobar&quot;, versionWithSimpleMigration);
+    pi1 = executionService.findProcessInstanceById(pi1.getId());
+    pi2 = executionService.findProcessInstanceById(pi2.getId());
+    assertEquals(pd2.getId(), pi1.getProcessDefinitionId());
+    assertEquals(pd2.getId(), pi2.getProcessDefinitionId());
+    assertEquals(pi1, pi1.findActiveExecutionIn(&quot;a&quot;));
+    assertEquals(pi2, pi2.findActiveExecutionIn(&quot;b&quot;));
+   	  </programlisting>
+      </para>
+   	</section>
 
+   	<section>
+   	  <title>Ending Running Instances</title>
+   	  <para>The second use case is when the instances of the previous process definition have to be ended. 
+   	  The way to indicate this would be to add the action attribute to the migrate-instances tag with the
+   	  value of &quot;end&quot;.
+   	  <programlisting>
+&lt;process name=&quot;foobar&quot;&gt;
+  ...
+  &lt;migrate-instances action=&quot;end&quot;/&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	  If we take the situation from above with one process in state &quot;a&quot; and another in state &quot;b&quot; 
+   	  the two processes would be ended as can be seen in the following snippet:
+   	  <programlisting>
+    ProcessDefinition pd1 = deployProcessDefinition(&quot;foobar&quot;, originalVersion);
+    ProcessInstance pi1 = startAndSignal(pd1, &quot;a&quot;);
+    ProcessInstance pi2 = startAndSignal(pd1, &quot;b&quot;);
+    ProcessDefinition pd2 = deployProcessDefinition(&quot;foobar&quot;, versionWithSimpleAbortion);
+    pi1 = executionService.findProcessInstanceById(pi1.getId());
+    pi2 = executionService.findProcessInstanceById(pi2.getId());
+    assertNull(pi1);
+    assertNull(pi2);
+   	  </programlisting>
+   	  </para>
+   	</section>
+   	
+   	<section>
+   	  <title>Version Ranges</title>
+   	  <para>So far I have showed you how instances of the previously deployed version - and only that one -
+   	  could be either migrated or ended. But what to do when you want to perform these actions on process
+   	  instances of other already deployed versions. This can be done by making use of the versions attribute
+   	  of the migrate-instances tag. This attribute lets you specify a range of versions that need to be
+   	  migrated (or ended). 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;end&quot;/&gt;
+  &lt;/state&gt;
+  &lt;end name=&quot;end&quot;/&gt;
+  &lt;migrate-instances versions=&quot;2..3&quot;/&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	  Imagine a situation where we would deploy the original process definition 4 times in a row and for each
+   	  deployment start a process instance that waits in state &quot;a&quot;. Then we deploy the above version
+   	  of the process definition with instance migration. The result will be that instance 2 and instance 3 
+   	  will be migrated while instance 1 and instance 4 will keep running following their original definition.
+   	  This is shown in the snippet below:
+   	  <programlisting>
+    ProcessDefinition pd1 = deployProcessDefinition(&quot;foobar&quot;, originalVersion);
+    ProcessInstance pi1 = startAndSignal(pd1, &quot;a&quot;);
+    ProcessDefinition pd2 = deployProcessDefinition(&quot;foobar&quot;, originalVersion);
+    ProcessInstance pi2 = startAndSignal(pd2, &quot;a&quot;);
+    ProcessDefinition pd3 = deployProcessDefinition(&quot;foobar&quot;, originalVersion);
+    ProcessInstance pi3 = startAndSignal(pd3, &quot;a&quot;);
+    ProcessDefinition pd4 = deployProcessDefinition(&quot;foobar&quot;, originalVersion);
+    ProcessInstance pi4 = startAndSignal(pd4, &quot;a&quot;);
+    ProcessDefinition pd5 = deployProcessDefinition("foobar", versionWithAbsoluteVersionRange);
+    pi1 = executionService.findProcessInstanceById(pi1.getId());
+    pi2 = executionService.findProcessInstanceById(pi2.getId());
+    pi3 = executionService.findProcessInstanceById(pi3.getId());
+    pi4 = executionService.findProcessInstanceById(pi4.getId());
+    assertEquals(pd1.getId(), pi1.getProcessDefinitionId());
+    assertEquals(pd5.getId(), pi2.getProcessDefinitionId());
+    assertEquals(pd5.getId(), pi3.getProcessDefinitionId());
+    assertEquals(pd4.getId(), pi4.getProcessDefinitionId());
+   	  </programlisting> 
+   	  A number of variants exist for the versions attribute. The example above uses an absolute version range.
+   	  It is also possible to use an expression of the form x-n to indicate a version number relative to the 
+   	  last deployed version. So if you want to only migrate instances from the last two versions you could 
+   	  use the following expression for the versions attribute:
+   	  <programlisting>
+&lt;process name=&quot;foobar&quot;&gt;
+  ...
+  &lt;migrate-instances versions=&quot;x-2..x&quot;/&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	  You can also mix and match the absolute and the relative specifications. E.g. if you would like to 
+   	  migrate all the instances of all the versions to the newly deployed version you can use the following:
+   	  <programlisting>
+&lt;process name=&quot;foobar&quot;&gt;
+  ...
+  &lt;migrate-instances versions=&quot;1..x&quot;/&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	  And for this last example you can also use the &quot;*&quot; wildcard notation:
+   	  <programlisting>
+&lt;process name=&quot;foobar&quot;&gt;
+  ...
+  &lt;migrate-instances versions=&quot;*&quot;/&gt;
+&lt;/process&gt;
+   	  </programlisting>
+   	  </para>
+   	</section>
+   	
+   	<section>
+   	  <title>Activity Mappings</title>
+   	</section>
+   	
+   	<section>
+   	  <title>Migration Handlers</title>
+   	</section>
+   	
+  </section>
+
   <section>
     <title>User object caching</title>
     <para>As indicated in section "User code" in the Users guide, instantiated user objects 



More information about the jbpm-commits mailing list