XPath Data Model for SCXML

2.1 Data Model

The underlying structure of the XPath data model follows the document syntax closely. In particular, the SCXML Processor MUST maintain the XPath data model as an XML document with a root element called <datamodel>. For each <data> element in the document, the SCXML Processor MUST create a child of <datamodel> called <data> with an 'id' attribute whose value is the same as that of the 'id' attribute of the document <data> element. The Processor MUST insert the value of the document <data> element as the child(ren) of the datamodel <data> element. The Processor MUST also bind an XPath variable of the same name to that datamodel <data> element.

If either the 'src' attribute or in-line content is provided in the document <data> element, then if the content (whether fetched or provided in-line) is an XML document or node set, the SCXML Processor MUST insert the XML as the child of the datamodel <data> element. Otherwise the Processor MUST treat the content as a space-normalized string literal and insert it as the child of the datamodel <data> element. If no value is assigned, the SCXML Processor MUST leave the datamodel <data> element empty, as follows:

<data xmlns=""></data>

<scxml version="1.0" datamodel="xpath">
<datamodel>
  <data id="company">
    <about xmlns="">
      <name>Example company</name>
      <website>example.com</website>
      <CEO>John Doe</CEO>
    </about>
  </data>
  <data id="employees" src="http://example.com/employees.xml"/>
  <data id="defaultdata"/>
</datamodel>
</scxml>

2.2 Conditional Expressions

The SCXML Processor MUST accept any XPath 1.0 expression as a conditional expression and MUST convert it into its effective boolean value as described in section 2.4.3 of the [XPath 2.0] specification. (Note that the definition of effective boolean value is taken from the XPath 2.0 specification, even though the XPath datamodel requires support only for expressions as defined in XPath 1.0, and not for the broader range of expressions defined in XPath 2.0.) The following example illustrates this usage.

<state id="errorSwitch" xmlns:fn="http://www.w3.org/2005/xpath-functions">
  <datamodel>
    <data id="time"/>
  </datamodel>
          
  <onentry>
    <assign location="$time" expr="fn:current-dateTime()"/>
  </onentry>
          
  <transition cond="fn:year-from-dateTime($time) > 2009" target="newBehavior"/>
  <transition target="currentBehavior"/>
</state>
       

The SCXML processor MUST define an XPath function 'In()' that takes a stateID as its argument and returns 'true' if and only if that state is in the current state configuration, as described in Conditional Expressions. For examples of the use of this predicate (but in an ECMAScript context), see microwave example.

2.3 Location Expressions

The SCXML Processor MUST accept any XPath expression as a location expression. The following example illustrates this usage:

<state id="errorSwitch">
  <datamodel>
    <data id="cities">
      <list xmlns="">
        <city id="nyc" count="0">New York</city>
        <city id="bos" count="0">Boston</city>
      </list>
    </data>
  </datamodel>

  <onentry>
    <assign location="$cities/list/city[@id='nyc']/@count" expr="1"/>
  </onentry>
</state>

2.4 Value Expressions

The SCXML Processor MUST allow any XPath expression to be used as a value expression. If the result of the value expression is a node-set, the Processor MUST make a deep copy of the subtree rooted at each node. The Processor MAY convert the expression result to a string In contexts where a string is expected.

<state id="processEvent">
  <datamodel>
    <data id="myEventData"/>
  </datamodel>
    
  <onentry>
    <assign location="$myEventData" expr="$_event/data"/>
  </onentry>
</state>

2.5 <content>

When <content> is a child of <donedata>, the Processor MUST interpret its value as defined in 2.7.1 _event.data. When <content> is a child of <send>, the interpretation of its value depends on the Event I/O Processor. When <content> is a child of <invoke>, the interpretation of its value is platform-specific.

2.6 <assign>

Implementations supporting the XPath data model MUST support the following additional attributes for the <assign> element.

The SCXML Processor MUST modify the data model as directed by the 'type' attribute as described below. If it is unable to do so, it MUST place the error error.execution on the internal event queue:

• replacechildren. Replace all the children at 'location' with the value specified by 'expr'.
• firstchild. Insert the value specified by 'expr' before all of the children at 'location'.
• lastchild. Insert the value specified by 'expr' after all of the children at 'location'.
• previoussibling. Insert the value specified by 'expr' before the node specified by 'location', keeping the same parent.
• nextsibling. Insert the value specified by 'expr' after the node specified by 'location', keeping the same parent.
• replace. Replace the node specified by 'location' by the value specified by 'expr'.
• delete. Delete the node specified by 'location'. ('expr' is ignored.)
• addattribute. Add an attribute with the name specified by 'attr' and value specified by 'expr' to the node specified by 'location'.

If the specified location contains a node set, the Processor MUST perform the assignment to each node in the set. It MAY do so in any order it chooses, and MUST evaluate 'expr' only once.

Note that in the case of an XML data model, it is not required to assign to the root of a tree (i.e., the "name" value in a <data> tag), since the path expression can reach down into the tree to assign a new value to an internal node. The following examples show various aspects of assignment in the XPath data model. Suppose we have a data model of the following form:

<data id="cart">
  <myCart xmlns="">
    <books>
      <book>
        <title>The Zen Mind</title>
      </book>
      <book>
        <title>Freakonomics</title>
      </book>
    </books>
    <cds>
      <cd name="Something"/>
    </cds>
  </myCart>
</data>

Here is an example of assignment of a string to an element node.

 
<assign location="$cart/myCart/books/book[1]/title"  expr="'My favorite book'"/>

results in

<data id="cart">
  <myCart xmlns="">
    <books>
      <book>
        <title>My favorite book</title>
      </book>
      <book>
        <title>Freakonomics</title>
      </book>
      ...
</data>

Now suppose we assign an XML structure to an element node. The following assignment statement would have the effect of replacing the children of the element "$cart/myCart/books/book[1]" by the XML tree rooted in <bookinfo>.

<assign location="$cart/myCart/books/book[1]">
  <bookinfo xmlns="">
    <isbn>12334455</isbn>
    <author>some author</author>
  </bookinfo>
</assign>

results in

<data id="cart">
  <myCart xmlns="">
    <books>
      <book>
        <bookinfo>
          <isbn>12334455</isbn>
          <author>some author</author>
        </bookinfo>
      </book>
      <book>
        <title>Freakonomics</title>
      </book>
      ...
</data>

Here are examples of legal and illegal assignment to an attribute:

<!-- Legal assignment: -->
<assign location="$cart/myCart/cds/cd/@name" expr"'Something Else'"/>

<!-- Illegal assignment: -->
<assign  location="$cart/myCart/cds/cd/@name" >
  <foo>
    <bar/>
  </foo>
</assign>

Now suppose we assign a string to a nodeset. The following assignment statement would have the effect of replacing the children of each node in the nodeset $cart/myCart/books/book with the string "The Zen Mind":

<assign location="$cart/myCart/books/book" expr="'The Zen Mind'"/>

results in

<data id="cart">
  <myCart xmlns="">
    <books>
      <book>The Zen Mind</book>
      <book>The Zen Mind</book>
    </books>
    ...
</data>

Finally suppose we assign a structure to a nodeset. The following statement would iterate over the elements in the nodeset of <book> elements and replace their children with the <price> structure:

<assign location="$cart/myCart/books/book">
  <price>20.0</price>
</assign>

results in

<data id="cart">
  <myCart xmlns="">
    <books>
      <book>
        <price>20.0</price>
      </book>
      <book>
        <price>20.0</price>
      </book>
    </books>
    ...
</data>

If the evaluation of any of the expressions in an <assign> element causes an error to be raised, evaluation of the element terminates immediately and the <assign> has no effect. For example, the following assignment statement would raise an error because the sample data model we are using does not have an <ISBN> node as a child of <book>:

 
<assign location="$cart/myCart/books/book[1]/ISBN"  expr="'....'"/>

2.7 System Variables

For each system variable defined in System Variables, the SCXML Processor MUST create a data model <data> element with an 'id' attribute whose value is the name of the system variable. The Processor also MUST bind an XPath variable whose name is the name of the system variable to this element. For the _event system variable (i.e., the <data id="_event"> child of <datamodel>), for each of the fields defined in The Internal Structure of Events, the Processor also MUST create an child element whose name is the name of the field. For the _ioprocessors system variable the Processor MUST create an child <processor> element for each Event I/O processor that it supports, with a 'name' attribute whose value is the name of the I/O processor. For the SCXML and BasicHTTP Event I/O processors, the Processor MUST create a <location> child under the child element, assigning the access URI as its text child. For example, in systems that support the BasicHTTP Event I/O Processor, the access URI of the BasicHTTP Event I/O processor can be a accessed as $_ioprocessors/processor[@name="/http://www.w3.org/TR/scxml/#BasicHTTPEventProcessor/"]/location/text().

Suppose as part of executing a state machine named "myName" with a platform-assigned sessionid "12345", we are processing an event with the name "foo.bar" and the following XML payload:

<payload xmlns="">
    <answer>42</answer>
</payload>

Then the underlying XML data model would have the following form (not all the fields of the event are shown):

  <datamodel>

    <!-- The four data elements below are automatically populated by the system -->

    <data id="_name">myName</data>
    <data id="_sessionid">12345</data>
    <data id="_event">
      <name xmlns="">foo.bar</name>
      <data xmlns="">
        <payload>
          <answer>42</answer>
        </payload>
      </data>
    </data>
    <data id="_ioprocessors">
      <processor name="http://www.w3.org/TR/scxml/#BasicHTTPEventProcessor">
        <location>http://example.com/scxml-http/12345</location>
      </processor>
      <processor name="http://www.w3.org/TR/scxml/#SCXMLEventProcessor">
        <location/>
      </processor>
    </data>

    <!-- Rest of the application / developer-authored
         data model goes here -->

  </datamodel>

As an example, here is a sample transition that accesses the $_sessionid variable in that data model.

<state id="checkSessionid">
  <transition cond="$_sessionid = '12345'" target="nextState"/>
  ...
</state>

2.8 Serialization

In certain circumstances, e.g. when including data in events sent via the BasicHTTP Event I/O Processor, the SCXML Processor is required to serialize data from the XPath data model for transmission to a remote entity. In such cases, the Processor MUST serialize the data as a string.

2.9 Scripting

There is no scripting language.

2.10 <foreach>

In the XPath data model, the legal iterable collections are Node-Sets. The legal values for the 'item' attribute are legal XPath variable names. The iteration order is the order of the underlying Node-set, and goes from an index of 1 by increments of one to an index of count(node-set).

<foreach array="$cart//book" item="book">
<log expr="fn:concat('Cart contains book with ISBN ', + $book/isbn)"/>
</foreach>

2.11 Unsupported Elements

The script element is not supported in the XPath Data Model.