Chapter 7. The Context
Read this chapter to learn about process variables. Process variables are key-value pairs that maintain process instance-related information.
Note
To be able to store the context in a database, some minor limitations apply.
7.1. Accessing Process Variables
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 |
Note
Untyped null values can also be stored persistently.
Warning
Do not save a process instance if there are any other types stored in the process variables as this will cause an exception error.
7.2. Lives of Variables
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 communications with the database than a plain column update.
7.3. Variable Persistence
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 4, Persistence .
7.4. Variable Scopes
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);
7.4.1. Variable Overloading
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.
7.4.2. Variable Overriding
Variable overriding 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, you can override a variable named
contact in the process instance scope with this variable in the nested paths of execution shipping and billing.
7.4.3. Task Instance Variable Scope
To learn about task instance variables, read Section 8.4, “ Task Instance Variables ”.
7.5. Transient 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.
Note
The lifespan of a transient variable is the same as that of a
ProcessInstance Java object.
Note
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.
