SCXML - API notes - Contexts and Evaluators

Commons SCXML - Pluggable expression languages

The SCXML specification allows implementations to support multiple expression languages to enable using SCXML documents in varying environments. These expressions become part of attribute values for executable content, such as:

     <var name="foo" expr="1 + 2 + bar" />

or are used to evaluate the boolean guard conditions that decide whether or not a particular transition is followed once its associated trigger event is received, such as:

     <transition event="day.close" cond="day eq 'Friday'"
                 target="weekend" />

To that end, the Context and Evaluator interfaces serve as adapters to the particular expression language APIs for a given usecase.

Variable resolution bubbles up from the current state up to the document root, similar to variable shadowing via blocks in a procedural language.

What is a Context?

The Context is a collection of variables that defines a variable "scope". Each <state> element within an SCXML document gets its own Context or variable scope.

What is a root context?

The root context is the context that may be supplied to the Commons SCXML engine as representing the variables in the "host environment". See SCXMLExecutor#setRootContext(Context) from the Javadoc.

What is an Evaluator?

The Evaluator is a component with the capability of parsing and evaluating expressions. It is the "expression language engine".

Available expression languages

Commons SCXML currently supports using Commons JEXL, Javascript, XPath and Groovy as the expression language. The expressions throughout the document must be homogeneous. This also applies to any external documents that may be referred by this document, for example via "src" attributes, like so:

     <state id="foo" src="foo.xml">
      <!-- Something, possibly very interesting, here -->
     </state>

Here, foo.xml must use the same expression language as the document above that hosts the state foo.
Check out the engine API docs on how to plug in the suitable root context and evaluator tuple.

Commons JEXL

See org.apache.commons.scxml2.env.jexl package summary for the relevant root context and evaluator tuple to use.

Javascript

See org.apache.commons.scxml2.env.javascript package summary for the relevant root context and evaluator tuple to use.

XPath

See org.apache.commons.scxml2.env.xpath package summary for the relevant root context and evaluator tuple to use.

Groovy

See org.apache.commons.scxml2.env.groovy package summary for the relevant root context and evaluator tuple to use.

Method invocation in expressions

Commons SCXML uses the mechanisms provided by the expression language chosen for the document to support method invocation. Commons JEXL allow for method invocations as follows:

Commons JEXL

See Commons JEXL reference for builtin JEXL functions and the calling methods section of the examples page. As a summary, if the context contains an object under name foo which has an accessible method bar(), then the JEXL expression for calling the method is foo.bar()