IBM Support

BPEL process variable changes in Java code

Technote (troubleshooting)


Changing the value of a BPEL process variable in a Java code snippet is visible to other activities and persisted in some cases. In other cases, these changes are discarded. This technote describes the conditions under which these changes are persisted or discarded.

Resolving the problem

Java snippets vs. Java conditions and expressions

By default, BPEL process variables are accessible for read/write access in Java snippet activities. This means that changes to BPEL process variables are persisted after the Java snippet is executed. This is also true for all modified BPEL process variables if a Java exception occurs during the execution of the Java snippet.

For Java conditions and expressions (including join conditions, transition conditions, while conditions, wait duration), the default access for BPEL process variables is read-only. This means that changes to BPEL process variables are discarded after the Java condition or expression is evaluated. However, when the changes are discarded depends on the data type (complex or boxed-primitive) and the process execution mode (long-running or microflow). A common pitfall is a while condition in which a counter is evaluated and then increased or decreased. This action might fail because the default access for the BPEL process variables used in the while condition is read-only.

Sometimes, the default behavior is not sufficient. If you specify BPEL process variables as read-only access in Java snippets, this setting reduces the probability of database deadlocks and can therefore improve the overall BPEL process performance. For example, if you use four variables to initialize a fifth variable without specifying read-only access on the four variables, five database updates will occur. If you specify the variables as read-only, you can save four unnecessary database updates, including four unnecessary update events. The read-only access also lowers the probability of database deadlocks.

In some cases, such as the while condition, that evaluate a counter and modify it in one step, the BPEL process definition can be kept more readable by specifying the counter BPEL process variable as read/write access instead of separate the counter modification of the evaluation.

To do so, you can use the following comments in your snippet code:

// @bpe.readOnlyVariables names="<space separated list of BPEL Variables>"

// @bpe.readWriteVariables names="<space separated list of BPEL Variables>"


// @bpe.readWriteVariables names="LoopCounter Amount"

This example specifies read/write access to the BPEL process variables LoopCounter and Amount.

You can place these comments at any position in your Java code but you need to specify them for each Java snippet, condition, or expression separately. For better readability, list these comments at the beginning of the Java code.

Complex data types vs. boxed-primitive types

Complex data types are represented as data objects. For performance reasons, a Java snippet gets the content of complex data typed BPEL process variables by reference. This means that changes to these variables (represented as instances of commonj.sdo.DataObject in the Java code) are visible to all other activities - assigns, invokes, Java snippets and conditions - running in the same transaction. This is independent from the read/write or read-only settings of a Java snippet, condition, or expression. To treat a complex data typed BPEL process variable as read only, make sure that every Java snippet and condition running within the same transaction access this variable read-only. Otherwise, a change on a read-only variable in a previous Java snippet could be stored in a subsequent Java snippet, if the flag is not set appropriate there also.

If you want to avoid this effect, you need to change the value of the transactional behavior property on the Server Property page of the snippet activity to Commit After. However, note that this setting decreases the performance of your process because each transaction causes overhead.

Boxed-primitive types are immutable. Therefore, only a copy of the content of a BPEL process variable is passed to the Java code and that is why - regardless of transaction boundaries - the access specification (read-only vs. read/write) is regarded for these types of BPEL process variables.

Microflow vs. long-running processes

A microflow is an optimized process execution mode. It is executed within one transaction. Changes made to complex data typed BPEL process variables with read-only access are visible until the end of the process.

A long-running process consists of two or more transactions. Consequently, changes made to complex data typed BPEL process variables with read-only access are visible until the end of the current transaction.

Cross reference information
Segment Product Component Platform Version Edition
Business Integration IBM Business Process Manager Advanced 7.5 Advanced

Document information

More support for: WebSphere Process Server
Business Process Choreographer

Software version: 6.1, 6.1.2, 6.2, 7.0

Operating system(s): AIX, HP-UX, Linux, Solaris, Windows, z/OS

Reference #: 1253978

Modified date: 22 January 2007