[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>
+<process name="foobar">
+ <start>
+ <transition to="a"/>
+ </start>
+ <state name="a">
+ <transition to="b">
+ </state>
+ <state name="b">
+ <transition to="c"/>
+ </state>
+ <state name="c">
+ <transition to="end"/>
+ </state>
+ <end name="end"/>
+</process>
+ </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>
+<process name="foobar">
+ <start>
+ <transition to="a"/>
+ </start>
+ <state name="a">
+ <transition to="b">
+ </state>
+ <state name="b">
+ <transition to="c"/>
+ </state>
+ <state name="c">
+ <transition to="end"/>
+ </state>
+ <end name="end"/>
+ <migrate-instances/>
+</process>
+ </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"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 "a" and one process instance in the state "b". The following snippet
+ in a unit test would be valid:
+ <programlisting>
+ ProcessDefinition pd1 = deployProcessDefinition("foobar", originalVersion);
+ ProcessInstance pi1 = startAndSignal(pd1, "a");
+ ProcessInstance pi2 = startAndSignal(pd1, "b");
+ ProcessDefinition pd2 = deployProcessDefinition("foobar", 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("a"));
+ assertEquals(pi2, pi2.findActiveExecutionIn("b"));
+ </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 "end".
+ <programlisting>
+<process name="foobar">
+ ...
+ <migrate-instances action="end"/>
+</process>
+ </programlisting>
+ If we take the situation from above with one process in state "a" and another in state "b"
+ the two processes would be ended as can be seen in the following snippet:
+ <programlisting>
+ ProcessDefinition pd1 = deployProcessDefinition("foobar", originalVersion);
+ ProcessInstance pi1 = startAndSignal(pd1, "a");
+ ProcessInstance pi2 = startAndSignal(pd1, "b");
+ ProcessDefinition pd2 = deployProcessDefinition("foobar", 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>
+<process name="foobar">
+ <start>
+ <transition to="a"/>
+ </start>
+ <state name="a">
+ <transition to="b">
+ </state>
+ <state name="b">
+ <transition to="c"/>
+ </state>
+ <state name="c">
+ <transition to="end"/>
+ </state>
+ <end name="end"/>
+ <migrate-instances versions="2..3"/>
+</process>
+ </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 "a". 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("foobar", originalVersion);
+ ProcessInstance pi1 = startAndSignal(pd1, "a");
+ ProcessDefinition pd2 = deployProcessDefinition("foobar", originalVersion);
+ ProcessInstance pi2 = startAndSignal(pd2, "a");
+ ProcessDefinition pd3 = deployProcessDefinition("foobar", originalVersion);
+ ProcessInstance pi3 = startAndSignal(pd3, "a");
+ ProcessDefinition pd4 = deployProcessDefinition("foobar", originalVersion);
+ ProcessInstance pi4 = startAndSignal(pd4, "a");
+ 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>
+<process name="foobar">
+ ...
+ <migrate-instances versions="x-2..x"/>
+</process>
+ </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>
+<process name="foobar">
+ ...
+ <migrate-instances versions="1..x"/>
+</process>
+ </programlisting>
+ And for this last example you can also use the "*" wildcard notation:
+ <programlisting>
+<process name="foobar">
+ ...
+ <migrate-instances versions="*"/>
+</process>
+ </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