Specify LockMode to prevent StaleObjectStateException

Note:

This article applies to jBPM version 3.2.5.SP5 (and higher) and to certain databases, eg. PostgreSQL

Problem:

Executing a process with multiple async nodes within a fork/join results in StaleObjectStateExceptions upon entering the join node.

Sample process:

<fork name="fork1">
     <transition to="node1" name="to node1"></transition>
     <transition to="node2" name="to node2"></transition>
     <transition to="node3" name="to node3"></transition>
</fork>

<node name="node1" async="true">
     <action class="com.sample.ActionHandler"/>
     <transition to="join"></transition>
</node>

<node name="node2" async="true">
     <action class="com.sample.ActionHandler"/>
     <transition to="join"></transition>
</node>

<node name="node3" async="true">
     <action class="com.sample.ActionHandler"/>
     <transition to="join"></transition>
</node>

<join name="join">
     <transition to="node4"></transition>
</join>

Running this process with PostgreSQL set up for jBPM, a StaleObjectStateException might occur when the child tokens arrive in the join node.

Solution:

Specify the lock attribute on the join node and set it to FORCE:

<join name="join" lock="FORCE"/>

For this to work, a few config as well as database schema changes have to be made:

1. An alternate mapping file for the Node element has to be used, which contains the column definition for the lock attribute. The alternate mapping is distributed in jbpm-jpdl.jar. To use the alternative, make a copy of the default Hibernate configuration file hibernate.cfg.xml and replace:

   <mapping resource="org/jbpm/graph/node/Join.hbm.xml"/>

   with

   <mapping resource="org/jbpm/graph/node/Join.lock.hbm.xml"/>
2. An additional column PARENTLOCKMODE_ has to be added to the JBPM_NODE table:

   ALTER TABLE jbpm_node ADD COLUMN parentlockmode_ character varying(255);
3. Finally, the process definition has to be changed and redeployed by changing the join node as outlined above.

Background information:

In earlier jBPM versions, the FORCE lock mode has been the default in the Join node. This worked on most databases, but led to StaleObjectStateExceptions on others such as Oracle. Therefore, the idea of the additional PARENTLOCKMODE_ was to be able to configure the locking behavior so that it best fits the different environments. This schema change has been introduced with JBPM-1755 (version 3.2.4). Later on it was discovered that the schema change would be problematic for some of our customers, therefore the change has been reverted in JBPM-2119 (version 3.2.5.SP5). Also, the default behavior changed from LockMode.FORCE to LockMode.UPGRADE.

For PostgreSQL specific instructions see also InstallPostgreSQLonFedora.