Expressions are executed when guards are evaluated, when they are nested in actions, and for other configurable computations. Like actions, expressions are typically executed in the context of a task, but may occasionally be executed in the context of a process.
The main method of an expression is
evaluate(WorkflowObject,Map<String,Object>)
, which receives as arguments
the workflow object in which the expression is evaluated and a number of local properties.
These properties must not be confused with the variables present in the workflow object or
its view. Instead, the properties are purely local to the expression, without any form of
persistence. They are typically set in the predefined expressions Let
,
Exists
, or ForAll
.
If an expression modifies the given map, it should make sure to return it to its previous
state before returning from the evaluate
method. Preferably, this is done in a
try
/finally
construction.
Please see the Javadoc for more details regarding the data types that are permitted as return values of the expression and for the parameter map.
If you are creating an expression that will only return Boolean values, you can implement the interface BooleanExpression. Thereby you indicate the reduced set of return values and make your expression usable in a greater number of contexts, in particular in guards and as a subexpression of predefined Boolean connectives.
Mixing Unified API and WfAPI Expressions
You can include Unified API expressions and WfAPI expressions in one process definition. This allows a stepwise migration of existing plugins to the new APIs. You may even use, for example, old-style expressions as subexpressions of Unified API expressions. In this case, the expressions are automatically wrapped so that they appear as objects of the API that is used by the containing object. The wrappers will take care of converting argument values and return values when calling methods of the wrapped expression.
When using Unified API expression inside
WfAPI actions, care has to be taken with
respect to the correct treatment of null values. Because the
WfAPI uses typed nulls and the
Unified API expressions may return an ordinary Java
null
, a special subtype of
WfValue
has been introduced to the WfAPI:
NullValue.
This value should not be used when working purely inside the
WfAPI. Only when a
Unified API expression returns a null
and
when that value must be propagated to a WfAPI
action or expression, the above mentioned wrapper objects convert the value to a
NullValue.
Of course a plugin that was written for CoreMedia CMS
2005 or earlier may not expect a value of that type, possibly failing during a
type cast. Therefore, existing plugin implementations may have to be hardened against the
new value type
NullValue,
before you can use them with Unified API subexpressions.
Note that it is often desired to port the entire set of plugins to the new API anyway, so that this paragraph applies to a few specific cases, only. It is possible to use the built-in actions and expressions without restrictions. They will neither produce untyped nulls nor misbehave when they come across a NullValue.