JBoss.orgCommunity Documentation
Read this chapter to learn about process variables. Process variables are key-value pairs that maintain process instance-related information.
Since one must be able to store the context in a database, some minor limitations apply.
org.jbpm.context.exe.ContextInstance
serves as the central interface for process variables. Obtain the
ContextInstance from a process
instance in this manner:
ProcessInstance processInstance = ...;
ContextInstance contextInstance =
(ContextInstance) processInstance.getInstance(ContextInstance.class);
These are the basic operations:
void ContextInstance.setVariable(String variableName, Object value);
void ContextInstance.setVariable(
String variableName, Object value, Token token);
Object ContextInstance.getVariable(String variableName);
Object ContextInstance.getVariable(String variableName, Token token);
The variable name is java.lang.String. By
default, the Business Process Manager supports the following
value types. (It also supports any other class that can be persisted
with Hibernate.)
java.lang.String | java.lang.Boolean |
java.lang.Character | java.lang.Float |
java.lang.Double | java.lang.Long |
java.lang.Byte | java.lang.Integer |
java.util.Date | byte[] |
java.io.Serializable |
Untyped null values can also be stored persistently.
Do not save a process instance if there are any other types stored in the process variables as this will cause an exception error.
Variables do not have to be declared in the process archive. At
run-time, simply put any Java object in the variables. If a
variable did not exist, it will be created, in the same way as a
plain java.util.Map. Note that
variables can also be deleted.
ContextInstance.deleteVariable(String variableName);
ContextInstance.deleteVariable(String variableName, Token token);
Types can change automatically. This means that a type is allowed to overwrite a variable with a value of a different type. It is important to always try to limit the number of type changes since this generates more comunications with the database than a plain column update.
The variables are part of the process instance. Saving the process instance in the database will synchronise the database with the process instance. (The variables are created, updated and deleted by doing this.) For more information, see Chapter 6, Persistence .
Each path of execution (also known as a
token) has its own set of process variables.
Variables are always requested on a path of execution. Process
instances have a tree of these paths. If a variable is requested but
no path is specified, the root token will
be used by default.
The variable look-up occurs recursively. It runs over the parents of the given path of execution. (This is similar to the way in which variables are scoped in programming languages.)
When a non-existent variable is set on a path of execution, the
variable is created on the root token.
(Hence, each variable has, by default, a process scope.) To make
a variable token "local", create it explicitly, as per this
example:
ContextInstance.createVariable(String name, Object value, Token token);
Variable overloading means that each path of execution can have its own copy of a variable with the same name. These copies are all treated independently of each other and can be of different types. Variable overloading can be interesting if one is launching multiple concurrent paths of execution over the same transition. This is because the only thing that will distinguish these paths will be their respective set of variables.
Variable over-riding simply means that
variables in nested paths of execution
over-ride variables in more global paths of execution.
Generally, "nested paths of execution" relates to concurrency:
the paths of execution between a fork and a join are children
(nested) of the path of execution that arrived in the fork. For
example, ione can over-ride a variable named
contact in the process instance scope with
this variable in the nested paths of execution
shipping and billing.
To learn about task instance variables, read Section 11.4, “ Task Instance Variables ”.
When a process instance is persisted in the database, so too are normal variables. However, at times one might want to use a variable in a delegation class without storing it in the database. This can be achieved with transient variables.
The lifespan of a transient variable is the same as that of a
ProcessInstance Java object.
Because of their nature, transient variables are not related to paths of execution. Therefore, a process instance object will have only one map of them.
The transient variables are accessible through their own set of methods
in the context instance. They do not need to be declared in the
processdefinition.xml file.
Object ContextInstance.getTransientVariable(String name);
void ContextInstance.setTransientVariable(String name, Object value);
This chapter has covered process variables in great detail. The reader should now be confident that he or she understands this topic.