[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>
<process name="foobar">
@@ -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>
+<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="d"/>
+ </state>
+ <state name="d">
+ <transition to="end"/>
+ </state>
+ <end name="end"/>
+ <migrate-instances>
+ <activity-mapping old-name="b" new-name="a"/>
+ <activity-mapping old-name="c" new-name="d"/>
+ </migrate-instances>
+</process>
+ </programlisting>
+ Deploying this process will put all the instances of the previously deployed process that are waiting
+ in the state "b" into the state "a" of the newly deployed process. Likewise all
+ instances of the previously deployed process definition that are waiting in state "c" will be
+ placed in the state "d". The following piece of code illustrates this:
+ <programlisting>
+ ProcessDefinition pd1 = deployProcessDefinition("foobar", originalVersion);
+ ProcessInstance pi1 = startAndSignal(pd1, "a");
+ ProcessInstance pi2 = startAndSignal(pd1, "b");
+ ProcessInstance pi3 = startAndSignal(pd1, "c");
+ ProcessDefinition pd2 = deployProcessDefinition("foobar", 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("a"));
+ assertEquals(pi2, pi2.findActiveExecutionIn("a"));
+ assertEquals(pi3, pi3.findActiveExecutionIn("d"));
+ pi1 = executionService.signalExecutionById(pi1.getId());
+ pi2 = executionService.signalExecutionById(pi2.getId());
+ pi2 = executionService.signalExecutionById(pi2.getId());
+ pi3 = executionService.signalExecutionById(pi3.getId());
+ assertEquals(pi1, pi1.findActiveExecutionIn("b"));
+ assertEquals(pi2, pi2.findActiveExecutionIn("c"));
+ 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
+ "org.jbpm.pvm.internal.migration.MigrationHandler":
+ <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>
+<process name="foobar">
+ ...
+ <migrate-instances>
+ <migration-handler class="org.jbpm.test.migration.TestHandler"/>
+ </migrate-instances>
+</process>
+ </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 "end"
+ 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