Author: koen.aers(a)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>