Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the @@@ W3C Proposed Recommendation of SCXML Version 1.0. W3C publishes a technical report as a Proposed Recommendation to indicate that the document is a mature technical report that has received wide review for technical soundness and implementability and to request final endorsement from the W3C Advisory Committee. Proposed Recommendation status is described in section 7.1.1 of the Process Document.
The W3C Membership and other interested parties are invited to review the document and send comments to the Working Group's public mailing list www-voice@w3c.org(archive) until @@@. See W3C Mailing List and Archive Usage Guidelines. Advisory Committee Representatives should consult their WBS questionnaires.
This document is based upon the State Chart XML (SCXML) Candidate Recommendation of 13 March 2014, the subsequent third Last Call Working Draft version of 29 May 2014, and feedback received during the review period (see the Disposition of Comments - UPDATE LINK document). No substantive changes have been made since 29 May 2014 Last Call Working Draft.
The Voice Browser Working Group ((W3C Members only) believes that this specification addresses its requirements and all Last Call and Candidate Recommendation issues. Known implementations are documented in the SCXML 1.0 Implementation Report - UPDATE LINK, along with the associated test suite.
This document has been produced as part of the Voice Browser Activity (activity statement), following the procedures set out for the W3C Process. The authors of this document are members of the Voice Browser Working Group.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
Publication as a Proposed Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
The sections of this document are normative unless otherwise specified.
1 Terminology
2 Overview
3 Core Constructs
3.1 Introduction
3.2 <scxml>
3.3 <state>
3.4 <parallel>
3.5 <transition>
3.6 <initial>
3.7 <final>
3.8 <onentry>
3.9 <onexit>
3.10 <history>
3.11 Legal State Configurations and Specifications
3.12 SCXML Events
3.13 Selecting and Executing Transitions
3.14 IDs
4 Executable Content
4.1 Introduction
4.2 <raise>
4.3 <if>
4.4 <elseif>
4.5 <else>
4.6 <foreach>
4.7 <log>
4.8 Other Executable Content
4.9 Evaluation of Executable Content
4.10 Extensibility of Executable Content
5 Data Model and Data Manipulation
5.1 Introduction
5.2 <datamodel>
5.3 <data>
5.4 <assign>
5.5 <donedata>
5.6 <content>
5.7 <param>
5.8 <script>
5.9 Expressions
5.10 System Variables
6 External Communications
6.1 Introduction
6.2 <send>
6.3 <cancel>
6.4 <invoke>
6.5 <finalize>
A Conformance
A.1 Conforming Documents
A.2 Conforming Processors
B Data Models
B.1 The Null Data Model
B.2 The ECMAScript Data Model
B.3 The XPath Data Model
C Event I/O Processors
C.1 SCXML Event I/O Processor
C.2 Basic HTTP Event I/O Processor
C.3 DOM Event I/O Processor
D Algorithm for SCXML Interpretation
E Schema
F Related Work
G Examples
G.1 Language Overview
G.2 Microwave Example
G.3 Microwave Example (Using parallel)
G.4 Calculator Example
G.5 Examples of Invoke and finalize
G.6 Inline Content and Namespaces
G.7 Custom Action Elements
H MIME Type
H.1 Registration of MIME media type application/scxml+xml
H.2 Fragment Identifiers
I References
I.1 Normative References
I.2 Informative References
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC 2119].
The terms base URI and relative URI are used in this specification as they are defined in [RFC 2396].
All sections not marked as "informative" are normative.
[This section is informative.]
This document outlines State Chart XML (SCXML), which is a general-purpose event-based state machine language that combines concepts from CCXML and Harel State Tables. CCXML [CCXML 1.0] is an event-based state machine language designed to support call control features in Voice Applications (specifically including VoiceXML but not limited to it). The CCXML 1.0 specification defines both a state machine and event handing syntax and a standardized set of call control elements. Harel State Tables are a state machine notation that was developed by the mathematician David Harel [Harel and Politi] and is included in UML [UML 2.3]. They offer a clean and well-thought out semantics for sophisticated constructs such as parallel states. They have been defined as a graphical specification language, however, and hence do not have an XML representation. The goal of this document is to combine Harel semantics with an XML syntax that is a logical extension of CCXML's state and event notation.
3 Core Constructs presents the core state machine concepts, while 4 Executable Content contains an extensible set of actions that the state machine can take in response to events. 5 Data Model and Data Manipulation defines constructs for storing and modifying data, while 6 External Communications provides the capability of communicating with external entities.
[This section is informative.]
The most basic state machine concepts are 3.3 <state>, 3.5 <transition> and event (3.12 SCXML Events). Each state contains a set of transitions that define how it reacts to events. Events can be generated by the state machine itself or by external entities. In a traditional state machine, the machine is always in a single state. This state is called the active state. When an event occurs, the state machine checks the transitions that are defined in the active state. If it finds one that matches the event, it moves from the active state to the state specified by the transition (called the "target" of the transition.) Thus the target state becomes the new active state.
The Harel state notation defines several extensions to these basic notions. First of all, the state machine may take actions (as defined in 4 Executable Content) while taking transitions. Specifically, each state may contain 3.8 <onentry> and 3.9 <onexit> actions. Transitions may also contain actions. If a state machine takes transition T from state S1 to state S2, it first performs the onexit actions in S1, then the actions in T, then the onentry actions in S2. Secondly, in addition to the 'event' attribute that specifies the event(s) that can trigger it, transitions also have a 'cond' attribute. If a transition has both 'event' and 'cond' attributes, it will be selected only if an event is raised whose name matches the 'event' attribute (see 3.12.1 Event Descriptors for details) and the 'cond' condition evaluates to true. If the 'event' attribute is missing, the transition is taken whenever the 'cond' evaluates to true. If more than one transition matches, the first one in document order will be taken. Thus, in the following example, the system will transition to s1 when event e (or e.foo, etc.) occurs if x is equal to 1, but will transition to s2 if event e (or e.foo, etc.) occurs and x is not equal to 1, and will go to s3 if any other event occurs.
<state id=s"> <transition event="e" cond="x==1" target="s1"/> <transition event="e" target="s2"/> <transition event="*" target="s3"/> </state>
Note that the semantics of the <parallel> element does not call for multiple threads or truly concurrent processing. The children of <parallel> execute in parallel in the sense that they are all simultaneously active and each one independently selects transitions for any event that is received. However, the parallel children process the event in a defined, serial order, so no conflicts or race conditions can occur. See D Algorithm for SCXML Interpretation for a detailed description of the semantics of <parallel> and the rest of SCXML.
In the presence of compound states, transitions no longer simply move from the current active state to a new active state, but from one set of active states to another. (See 3.11 Legal State Configurations and Specifications for details.) If the target of a transition is an atomic state, the state machine will enter not only the atomic state, but also any of its ancestor states that are not already active. Conversely, a transition may take a compound state as its target. In this case, one of the compound state's children must also become active, but the transition does not specify which one. In this case we look at the target state's 3.6 <initial> child which specifies the state's default initial state, that is, the child state to enter if the transition does not specify one. (If the default initial state is itself compound, the state machine will also enter its default initial state, and so on recursively until it reaches an atomic state.) The presence of default initial states provides a form of encapsulation, since a transition may select a compound state as its target without understanding its internal substate structure.
The default initial state of a compound state may also be specified via the 'initial' attribute. The only difference between the <initial> element and the 'initial' attribute is that the <initial> element contains a <transition> element which may in turn contain executable content which will be executed before the default state is entered. If the 'initial' attribute is specified instead, the specified state will be entered, but no executable content will be executed. (If neither the <initial> child or the 'initial' element is specified, the default initial state is the first child state in document order.) As an example, suppose that parent state S contains child states S1 and S2 in that order. If S specifies S1 as its default initial state via the 'initial' attribute (or fails to specify any initial state), then any transition that specifies S as its target will result in the state machine entering S1 as well as S. In this case, the result is exactly the same as if the transition had taken S1 as its target. If, on the other hand, S specifies S1 as its default initial state via an <initial> element containing a <transition> with S1 as its target, the <transition> can contain executable content which will execute before the default entry into S1. In this case, there is a difference between a transition that takes S as its target and one that takes S1 as its target. In the former case, but not in the latter, the executable content inside the <initial> transition will be executed.
A compound state may also have final and history states as children. 3.7 <final> is used to signify that the parent state is in some sense "done" with its processing. When a state machine enters a <final> substate of a compound state, the parent state remains active, but the event "done.state.id" is generated, where id is the state id of the parent state. This event can trigger a transition in any ancestor state (including the parent). If the transition takes a target outside the parent state, the "done.state.id" event in effect serves as a signal that it is time to leave the parent state. 3.10 <history> allows for pause and resume semantics in compound states. Before the state machine exits a compound state, it records the state's active descendants. If the 'type' attribute of the <history> state is set to "deep", the state machine saves the state's full active descendant configuration, down to the atomic descendant(s). If 'type' is set to "shallow", the state machine remembers only which immediate child was active. After that, if a transition takes a <history> child of the state as its target, the state machine re-enters not only the parent compound state but also the state(s) in the saved configuration. Thus a transition with a deep history state as its target returns to exactly where the state was when it was last exited, while a transition with a shallow history state as a target re-enters the previously active child state, but will enter the child's default initial state (if the child is itself compound.)
In the case of a transition located in a compound state, the 'type' attribute is significant. The behavior of a transition with 'type' of "external" (the default) is defined in terms of the transition's source state (which is the state that contains the transition), the transition's target state(or states), and the Least Common Compound Ancestor (LCCA) of the source and target states (which is the closest compound state that is an ancestor of all the source and target states). When a transition is taken, the state machine will exit all active states that are proper descendants of the LCCA, starting with the innermost one(s) and working up to the immediate descendant(s) of the LCCA. (A 'proper descendant' of a state is a child, or a child of a child, or a child of a child of a child, etc.) Then the state machine enters the target state(s), plus any states that are between it and the LCCA, starting with the outermost one (i.e., the immediate descendant of the LCCA) and working down to the target state(s). As states are exited, their <onexit> handlers are executed. Then the executable content in the transition is executed, followed by the <onentry> handlers of the states that are entered. If the target state(s) of the transition is not atomic, the state machine will enter their default initial states recursively until it reaches an atomic state(s).
In the example below, assume that state s11 is active when event 'e' occurs. The source of the transition is state s1, its target is state s21, and the LCCA is state S. When the transition is taken, first state S11 is exited, then state s1, then state s2 is entered, then state s21. Note that the LCCA S is neither entered nor exited. For more details see 3.13 Selecting and Executing Transitions and D Algorithm for SCXML Interpretation.
<state id="S" initial="s1"> <state id="s1" initial="s11"> <onexit> <log expr="'leaving s1'"/> </onexit> <state id="s11"> <onexit> <log expr="'leaving s11'"/> </onexit> </state> <transition event="e" target="s21"> <log expr="'executing transition'"/> </transition> </state> <state id="s2" initial="s21"> <state id="s21"> <onentry> <log expr="'entering s21'"/> </onentry> </state> <onentry> <log expr="'entering s2'"/> </onentry> </state> <onentry> <log expr="'entering S'"/> <onentry> <onexit> <log expr="'leaving S'"/> <onexit> </state> ==== log output will be ======> leaving s11 leaving s1 executing transition entering s2 entering s21
The behavior of transitions with 'type' of "internal" is identical, except in the case of a transition whose source state is a compound state and whose target(s) is a descendant of the source. In such a case, an internal transition will not exit and re-enter its source state, while an external one will, as shown in the example below.
<state id="S" initial="s1"> <state id="s1" initial="s11"> <onentry> <log expr="entering S1"/> </onentry> <onexit> <log expr="'leaving s1'"/> </onexit> <state id="s11"> <onentry> <log expr="entering s11"/> </onentry> <onexit> <log expr="'leaving s11'"/> </onexit> </state> <transition event="e" target="s11" type="internal"> <log expr="'executing transition'"/> </transition> </state> ==== log output will be ======> leaving s11 executing transition entering s11 === if transition were external, log output would be ====> leaving s11 leaving s1 executing transition entering s1 entering s11
If the 'target' on a <transition> is omitted, then the value of 'type' does not have any effect and taking the transition does not change the state configuration but does invoke the executable content that is included in the transition. Note that this is different from a <transition> whose 'target' is its source state. In the latter case, the state is exited and reentered, triggering execution of its <onentry> and <onexit> executable content.
The top-level wrapper element, which carries version information. The actual state machine consists of its children. Note that only one of the children is active at any one time. See 3.11 Legal State Configurations and Specifications for details.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
initial | false | none | IDREFS | none | A legal state specification. See 3.11 Legal State Configurations and Specifications for details. | The id of the initial state(s) for the document. If not specified, the default initial state is the first child state in document order. |
name | false | none | NMTOKEN | none | Any valid NMTOKEN | The name of this state machine. It is for purely informational purposes. |
xmlns | true | none | URI | none | The value MUST be "http://www.w3.org/2005/07/scxml". | |
version | true | none | decimal | none | The value MUST be "1.0" | |
datamodel | false | none | NMTOKEN | platform-specific | "null", "ecmascript", "xpath" or other platform-defined values. | The datamodel that this document requires. "null" denotes the Null datamodel, "ecmascript" the ECMAScript datamodel, and "xpath" the XPath datamodel, as defined in B Data Models. |
binding | false | none | enum | "early" | "early", "late" | The data binding to use. See 5.3.3 Data Binding for details. |
A conformant SCXML document MUST have at least one <state>, <parallel> or <final> child. At system initialization time, the SCXML Processor MUST enter the states specified by the 'initial' attribute, if it is present. If it is not present, the Processor MUST enter the first state in document order. Platforms SHOULD document their default data model.
Holds the representation of a state.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
id | false | none | ID | none | A valid id as defined in [XML Schema] | The identifier for this state. See 3.14 IDs for details. |
initial | false | MUST NOT be specified in conjunction with the <initial> element. MUST NOT occur in atomic states. | IDREFS | none | A legal state specification. See 3.11 Legal State Configurations and Specifications for details. | The id of the default initial state (or states) for this state. |
[Definition: An atomic state is a <state> that has no <state>, <parallel> or <final> children.]
[Definition: A compound state is a <state> that has <state>, <parallel>, or <final> children (or a combination of these).]
[Definition: The default initial state(s) of a compound state are those specified by the 'initial' attribute or <initial> element, if either is present. Otherwise it is the state's first child state in document order. ]
In a conformant SCXML document, a compound state MAY specify either an "initial" attribute or an <initial> element, but not both. See 3.6 <initial> for a discussion of the difference between the two notations.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
id | false | ID | none | A valid id as defined in [XML Schema] | The identifier for this state. See 3.14 IDs for details. |
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
event | false | EventsTypes.datatype. | none | A space-separated list of event descriptors. See 3.12.1 Event Descriptors for details. | A list of designators of events that trigger this transition. See 3.13 Selecting and Executing Transitions for details on how transitions are selected and executed. See E Schema for the definition of the datatype. | |
cond | false | Boolean expression | 'true' | Any boolean expression. See 5.9.1 Conditional Expressions for details. | The guard condition for this transition. See 3.13 Selecting and Executing Transitions for details. | |
target | false | . | IDREFS | none | A legal state specification. See 3.11 Legal State Configurations and Specifications for details. | The identifier(s) of the state or parallel region to transition to. See 3.13 Selecting and Executing Transitions for details. |
type | false | enum | "external" | "internal" "external" | Determines whether the source state is exited in transitions whose target state is a descendant of the source state. See 3.13 Selecting and Executing Transitions for details. |
A conformant SCXML document MUST specify at least one of 'event', 'cond' or 'target'. 3.13 Selecting and Executing Transitions contains more detail on the semantics of transitions.
<final> represents a final state of an <scxml> or compound <state> element.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
id | false | ID | none | A valid id as defined in [XML Schema] | The identifier for this state. See 3.14 IDs for details. |
When the state machine enters the <final> child of a <state> element, the SCXML Processor MUST generate the event done.state.id after completion of the <onentry> elements, where id is the id of the parent state. Immediately thereafter, if the parent <state> is a child of a <parallel> element, and all of the <parallel>'s other children are also in final states, the Processor MUST generate the event done.state.id where id is the id of the <parallel> element.
When the state machine reaches the <final> child of an <scxml> element, it MUST terminate. See D Algorithm for SCXML Interpretation for details. If the SCXML session was triggered as the result by an <invoke> element in another session, the SCXML processor MUST generate the event done.invoke.id after termination and return it to the other session, where id is the unique identifier generated when the <invoke> element was executed. See 6.4 <invoke> for details.
A wrapper element containing executable content to be executed when the state is entered.
The children of the <onentry> handler consist of executable content as defined in 4 Executable Content.
The SCXML processor MUST execute the <onentry> handlers of a state in document order when the state is entered. In doing so, it MUST treat each handler as a separate block of executable content.
A wrapper element containing executable content to be executed when the state is exited.
The children of the <onexit> handler consist of executable content as defined in 4 Executable Content.
The SCXML processor MUST execute the <onexit> handlers of a state in document order when the state is exited. In doing so, it MUST treat each handler as a separate block of executable content.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
id | false | ID | none | A valid id as defined in [XML Schema] | Identifier for this pseudo-state. See 3.14 IDs for details. | |
type | false | enum | "shallow" | "deep" or "shallow" | Determines whether the active atomic substate(s) of the current state or only its immediate active substate(s) are recorded. |
If the 'type' of a <history> element is "shallow", the SCXML processor MUST record the immediately active children of its parent before taking any transition that exits the parent. If the 'type' of a <history> element is "deep", the SCXML processor MUST record the active atomic descendants of the parent before taking any transition that exits the parent. After the parent state has been visited for the first time, for each <history> element, we define the set of states that the processor has recorded to be the 'stored state configuration' for that history state. We also define the states specified by the 'target' of the <history> element's <transition> child to be the 'default stored state configuration' for that element. If a transition is executed that takes the <history> state as its target, the behavior depends on whether the parent state has been visited before. If it has, the SCXML processor MUST behave as if the transition had taken the stored state configuration for that history state as its target. If it has not, the SCXML processor MUST behave as if the transition had taken the default stored state configuration for that history state as its target. The Process MUST execute any executable content in the transition after the parent state's onentry handlers, and, in the case where the history pseudo-state is the target of an <initial> transition, the executable content inside the <initial> transition. (Note that in a conformant SCXML document, a <state> or <parallel> element MAY have both "deep" and "shallow" <history> children.)
[Definition: A <state> or <parallel> element is active if it has been entered by a transition and has not subsequently been exited.]
[Definition: The state configuration of a state machine is the set of currently active states. ]
An SCXML document places the state machine in an initial state configuration at initialization time (via the 'initial' attribute of the <scxml> element). Each transition that the state machine takes thereafter places the state machine in another state configuration (which need not be distinct from the former one.) A conformant SCXML document MUST place the state machine only in legal state configurations, where a legal state configuration is one that meets the following conditions:
It follows from this definition that if a state machine is in more than one atomic state, the atomic states can be traced back through a chain of <state> or <parallel> ancestors to a single <parallel> ancestor.
The 'target' attribute of a <transition> (or the 'initial' attribute of a <state> or <scxml> element) do not in the general case specify a full legal state configuration since 1) they can contain <parallel> or non-atomic <state> elements 2) they do not contain the ancestors of the states in the list. We therefore define a legal state specification to be a set of states such that 1) no state is an ancestor of any other state on the list, and 2) a full legal state configuration results when all ancestors and default initial descendants have been added. (Note that the process of adding default initial descendants is recursive, since the 'initial' value may itself be non-atomic.) In a conformant SCXML document, the value of an 'initial' attribute or the 'target' of a <transition> MUST either be empty or contain a legal state specification.
In a conformant SCXML document, there is an additional requirement on the value of the 'initial' attribute of a <state> and on the 'target' of a <transition> inside an <initial> or <history> element: all the states MUST be descendants of the containing <state> or <parallel> element.
For the most part, the set of events raised during the execution of an SCXML document is application-specific and generated under author control by use of the <raise> and <send> elements. However, certain events are mandatory and generated automatically by the interpreter. These are described in 3.12.3 List of Errors and Events. Platforms MAY extend the names of these automatically generated events by adding a suffix. For example, a platform could extend done.state.id with a timestamp suffix and generate done.state.id.timestamp instead. Because any prefix of done.state.id is also a prefix of done.state.id.timestamp, any transition that matches the former event will also match the latter.
[Definition: A transition matches an event if at least one of its event descriptors matches the event's name. ]
[Definition: An event descriptor matches an event name if its string of tokens is an exact match or a prefix of the set of tokens in the event's name. In all cases, the token matching is case sensitive. ]
For example, a transition with an 'event' attribute of "error foo" will match event names "error", "error.send", "error.send.failed", etc. (or "foo", "foo.bar" etc.) but would not match events named "errors.my.custom", "errorhandler.mistake","errOr.send" or "foobar".
For compatibility with CCXML, and to make the prefix matching possibly more clear to a reader of the SCXML document, an event descriptor MAY also end with the wildcard '.*', which matches zero or more tokens at the end of the processed event's name. Note that a transition with 'event' of "error", one with "error.", and one with "error.*" are functionally equivalent since they are token prefixes of exactly the same set of event names.
An event designator consisting solely of "*" can be used as a wildcard matching any sequence of tokens, and thus any event. Note that this is different from a transition lacking the 'event' attribute altogether. Such an eventless transition does not match any event, but will be taken whenever its 'cond' attribute evaluates to 'true'. As shown in D Algorithm for SCXML Interpretation, the SCXML interpreter will check for such eventless transitions when it first enters a state, before it looks for transitions driven by internal or external events.
The set of error events may be extended in future versions of this specification. However, the set of names beginning with 'error.platform' is reserved for platform- and application-specific errors. Therefore applications and platforms MAY extend the set of errors defined in this specification in two ways. First by adding a suffix to an error name defined in this specification, and second by using 'error.platform' with or without a suffix. In addition, platforms MAY include additional information about the nature of the error in the 'data' field of the event. See 5.10 System Variables for details.
Note however that authors can arrange for otherwise unhandled errors to cause the interpreter to exit by creating a transition with "event" attribute of 'error' and a target of any top-level final state (i.e. one that is a child of <scxml>). If such a transition T is placed in a state S, it will cause the state machine to terminate on any error that is raised in S or one of its substates and is not handled by another transition that is placed in a substate of S or in S and preceding T in document order.
Name | Description | Defined in | See also |
---|---|---|---|
done.state.id | Indicates that the state machine has entered a final substate of state id. | 3.7 <final> | 3.1 Introduction |
done.invoke.id | Indicates that the invoked process with invokeid id has completed processing. | 6.4 <invoke> | 3.7 <final>, exitInterpreter procedure in D Algorithm for SCXML Interpretation |
error.communication | Indicates that an error has occurred while trying to communicate with an external entity. | 3.12.2 Errors | 6.2 <send>, C.1 SCXML Event I/O Processor, C.2 Basic HTTP Event I/O Processor, C.3 DOM Event I/O Processor |
error.execution | Indicates that an error internal to the execution of the document has occurred, such as one arising from expression evaluation. | 3.12.2 Errors | 4.6 <foreach>, 5.4 <assign>, 5.7 <param>, 5.9.1 Conditional Expressions, 5.9.2 Location Expressions, 5.9.3 Legal Data Values and Value Expressions, 5.9.4 Errors in Expressions, 5.10 System Variables, 6.2 <send>, B.2.4 Location Expressions, B.2.7 <assign>, B.3.6 <assign> |
error.platform | Indicates that a platform- or application-specific error has occurred. | 3.12.2 Errors |
[Definition: A transition T is enabled by named event E in atomic state S if a) T's source state is S or an ancestor of S,and b) T matches E's name (see 3.12.1 Event Descriptors) and c) T lacks a 'cond' attribute or its 'cond' attribute evaluates to "true". A transition is enabled by NULL in atomic state S if a) T lacks an 'event' attribute, and b) T's source state is S or an ancestor of S and c) T lacks an 'cond' attribute or its 'cond' attribute evaluates to "true". (Note that such a transition can never be enabled by any named event.)]
[Definition: The source state of a transition is the <state> or <parallel> element that it occurs in. The effective target state(s) of the transition is the state or set of states specified by its 'target' attribute, with any history states being replaced by the corresponding stored state configuration or default stored state configuration. The complete target set of a transition consists of all the states that will be active after the transition is taken. It contains the effective target states of the transition plus all their ancestors, expanded by the recursive application of the following two operations: 1) if any <parallel> element is a member of the set, any of its children that are not members of the set must be added 2) if any compound <state> is in the set and none of its children is in the set, its default initial state(s) are added to the set. Any state whose child(ren) are added to the complete target set by clause 2 is called a default entry state. ]
[Definition: The exit set of a transition in configuration C is the set of states that are exited when the transition is taken when the state machine is in C. If the transition does not contain a 'target', its exit set is empty. Otherwise (i.e., if the transition contains a 'target'), if its 'type' is "external", its exit set consists of all active states in C that are proper descendants of the Least Common Compound Ancestor (LCCA) of the source and target states. Otherwise, if the transition has 'type' "internal", its source state is a compound state, and all its target states are proper descendants of its source state, the exit set consists of all active states in C that are proper descendants of its source state. (If a transition has 'type' of "internal", but its source state is not compound or its target states are not all proper descendants of its source state, its exit set is defined as if it had 'type' of "external". The exit set of a set of transitions is the union of the exit sets of the individual transitions. ]
[Definition: The entry set of a transition in configuration C is the set of states that are entered when the transition is taken. If a transition does not contain a 'target', its entry set is empty. Otherwise, it consists of all members of the transition's complete target set that that are not currently active or are in the exit set. (Thus the entry set consists of all members of the transition's complete target set that will not be active once the states in the exit set have been exited.) The entry set of a set of transitions is the union of the entry sets of the individual transitions.]
[Definition: A transition T is optimally enabled by event E in atomic state S if a) T is enabled by E in S and b) no transition that precedes T in document order in T's source state is enabled by E in S and c) no transition is enabled by E in S in any descendant of T's source state.]
[Definition: Two transitions T1 and T2 conflict in state configuration C if their exit sets in C have a non-null intersection.]
N.B. If two transitions conflict, then taking them both may lead to an illegal configuration. Hence, only one of the transitions may safely be taken. In order to resolve conflicts between transitions, we assign priorities to transitions as follows: let transitions T1 and T2 conflict, where T1 is optimally enabled in atomic state S1, and T2 is optimally enabled in atomic state S2, where S1 and S2 are both active. We say that T1 has a higher priority than T2 if a) T1's source state is a descendant of T2's source state, or b) S1 precedes S2 in document order.
[Definition: The optimal transition set enabled by event E in state configuration C is the largest set of transitions such that a) each transition in the set is optimally enabled by E in an atomic state in C b) no transition conflicts with another transition in the set c) there is no optimally enabled transition outside the set that has a higher priority than some member of the set. ]
[Definition: A microstep consists of the execution of the transitions in an optimal enabled transition set.]
[Definition: A macrostep is a series of one or more microsteps ending in a configuration where the internal event queue is empty and no transitions are enabled by NULL. ]
To execute a microstep, the SCXML Processor MUST execute the transitions in the corresponding optimal enabled transition set. To execute a set of transitions, the SCXML Processor MUST first exit all the states in the transitions' exit set in exit order. It MUST then execute the executable content contained in the transitions in document order. It MUST then enter the states in the transitions' entry set in entry order.
To exit a state, the SCXML Processor MUST execute the executable content in the state's <onexit> handler. Then it MUST cancel any ongoing invocations that were triggered by that state. Finally, the Processor MUST remove the state from the active state's list.
To enter a state, the SCXML Processor MUST add the state to the active state's list. Then it MUST execute the executable content in the state's <onentry> handler. If the state is a default entry state and has an <initial> child, the SCXML Processor MUST then execute the executable content in the <initial> child's <transition>.
At startup, the SCXML Processor MUST place the state machine in the configuration specified by the 'initial' attribute of the <scxml> element.
After entering the initial configuration, and after executing each microstep, the SCXML Processor MUST check the state configuration for <final> states that it has entered during the microstep. If it has entered a <final> state that is a child of <scxml>, it MUST halt processing. If it has entered a <final> state that is a child of a compound state, it MUST generate the event done.state.id, where id is the id of the compound state. If the compound state is itself the child of a <parallel> element, and all the <parallel> element's other children are in final states, the Processor MUST generate the event done.state.id, where id is the id of the <parallel> elements.
After checking the state configuration, the Processor MUST select the optimal transition set enabled by NULL in the current configuration. If the set is not empty, it MUST execute it as a microstep. If the set is empty, the Processor MUST remove events from the internal event queue until the queue is empty or it finds an event that enables a non-empty optimal transition set in the current configuration. If it finds such a set, the processor MUST then execute it as a microstep. (Otherwise the internal event queue is empty and the Processor has completed a macrostep.)
After completing a macrostep, the SCXML Processor MUST execute in document order the <invoke> handlers in all states that have been entered since the completion of the last macrostep. Then the Processor MUST remove events from the external event queue, waiting till events appear if necessary, until it finds one that enables a non-empty optimal transition set in the current configuration. The Processor MUST then execute that set as a microstep.
In a conformant SCXML document, the values of all attributes of type "id" MUST be unique within the session. When such an attribute is defined to be optional and the author omits it, then, for elements other than <send> and <invoke>, the SCXML processor MUST generate a unique id automatically at document load time. (Note that Such system generated IDs cannot normally be referenced elsewhere in the document because they are not known to the author. In particular, a state with a system generated ID cannot be the target of a transition.) The ids for <send> and <invoke> are subtly different. In a conformant SCXML document, they MUST be unique within the session, but in the case where the author does not provide them, the processor MUST generate a new unique ID not at load time but each time the element is executed. Furthermore the attribute 'idlocation' can be used to capture this automatically generated id. Finally note that the automatically generated id for <invoke> has a special format. See 6.4.1 Attribute Details for details. The SCXML processor MAY generate all other ids in any format, as long as they are unique.
[This section is informative.]
This standard defines elements of executable content which can raise events4.2 <raise>, communicate with external entities 6.2 <send>, log information 4.7 <log> execute scripts 5.8 <script> and modify the data model 5.4 <assign>, as well as control constructs to conditionalize execution 4.3 <if> and to iterate over the items in a collection 4.6 <foreach>. In addition, SCXML implementations are allowed to define their own, platform-specific executable content (see 4.10 Extensibility of Executable Content).
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
event | true | NMTOKEN | none | Specifies the name of the event. This will be matched against the 'event' attribute of transitions. |
<if> is a container for conditionally executed elements.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
cond | true | Conditional expression | none | A valid conditional expression | A boolean expression. See 5.9.1 Conditional Expressions for details. |
The behavior of <if> is defined in terms of partitions of executable content. The first partition consists of the executable content between the <if> and the first <elseif>, <else> or </if> tag. Each <elseif> tag defines a partition that extends from it to the next <elseif>, <else> or </if> tag. The <else> tag defines a partition that extends from it to the closing </if> tag. In a conformant SCXML document, a partition MAY be empty. In a conformant SCXML document, <else> MUST occur after all <elseif> tags.
When the <if> element is executed, the SCXML processor MUST execute the first partition in document order that is defined by a tag whose 'cond' attribute evaluates to true, if there is one. Otherwise, it MUST execute the partition defined by the <else> tag, if there is one. Otherwise it MUST NOT execute any of the executable content.
Here is an example:
<if cond="cond1"> <!-- selected when "cond1" is true --> <elseif cond="cond2"/> <!-- selected when "cond1" is false and "cond2" is true --> <elseif cond="cond3"/> <!-- selected when "cond1" and "cond2" are false and "cond3" is true --> <else/> <!-- selected when "cond1", "cond2", and "cond3" are false --> </if>
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
array | true | Value expression | none | A value expression that evaluates to an iterable collection. | The <foreach> element will iterate over a shallow copy of this collection. | |
item | true | xsd:string | none | Any variable name that is valid in the specified data model. | A variable that stores a different item of the collection in each iteration of the loop. | |
index | false | xsd:string | none | Any variable name that is valid in the specified data model. | A variable that stores the current iteration index upon each iteration of the foreach loop. |
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
label | false | string | empty string | A character string with an implementation-dependent interpretation. It is intended to provide meta-data about the log string specified by 'expr'. | ||
expr | false | Value expression | none | An expression returning the value to be logged. See 5.9.3 Legal Data Values and Value Expressions for details. The nature of the logging mechanism is implementation-dependent. For example, the SCXML processor may convert this value to a convenient format before logging it. |
Events raised during the processing of executable content are treated like any other events. Note in particular, that error events will not be removed from the queue and processed until all events preceding them in the queue have been processed. See 3.12.2 Errors. for details.
In a conformant SCXML document any extensions to executable content MUST NOT be defined the 'scxml' namespace. (Note that the schema E Schema allows elements from arbitrary namespaces inside blocks of executable content.) The following example shows the incorporation of CCXML functionality (see [CCXML 1.0]) into SCXML. In particular an <accept> element in the 'ccxml' namespace is invoked as executable content inside a transition.
<transition event="ccxml:connection.alerting"> <ccxml:accept connectionid="_event.data.connectionid"/> </transition>
This markup is legal on any SCXML interpreter, but the behavior of <accept> element is platform-dependent. See A.2 Conforming Processors for details.
A general method for implementing extensions using the <send> element is presented in G.7 Custom Action Elements.
[This section is informative.]
The Data Model offers the capability of storing, reading, and modifying a set of data that is internal to the state machine. This specification does not mandate any specific data model, but instead defines a set of abstract capabilities that can be realized by various languages, such as ECMAScript or XML/XPath. Implementations may choose the set of data models that they support. In addition to the underlying data structure, the data model defines a set of expressions as described in 5.9 Expressions. These expressions are used to refer to specific locations in the data model, to compute values to assign to those locations, and to evaluate boolean conditions. Finally, the data model includes a set of system variables, as defined in 5.10 System Variables, which are automatically maintained by the SCXML processor.
The data model is defined via the 5.2 <datamodel> element, which contains zero or more 5.3 <data> elements, each of which defines a single data element and assigns an initial value to it. These values may be specified in-line or loaded from an external source. They can then be updated via the 5.4 <assign> element. The 5.5 <donedata>, 5.6 <content> , and 5.7 <param> elements can be used to incorporate data into communications with external entities. Finally, the 5.8 <script> element permits the incorporation of a scripting language.
The interpretation of these elements depends on the data model in question, and not all elements are supported in all data models. For the details of specific data models, see B Data Models.
The <data> element is used to declare and populate portions of the data model.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
id | true | ID | none | The name of the data item. See 3.14 IDs for details. | ||
src | false | URI | none | Gives the location from which the data object should be fetched. See 5.9.3 Legal Data Values and Value Expressions for details. | ||
expr | false | Expression | none | Any valid value expression | Evaluates to provide the value of the data item. See 5.9.3 Legal Data Values and Value Expressions for details. |
If the 'expr' attribute is present, the Platform MUST evaluate the corresponding expression at the time specified by the 'binding' attribute of <scxml> and MUST assign the resulting value as the value of the data element. If the 'src' attribute is present, the Platform MUST fetch the specified object at the time specified by the 'binding' attribute of <scxml> and MUST assign it as the value of the data element. If child content is specified, the Platform MUST assign it as the value of the data element at the time specified by the 'binding' attribute of <scxml>. Note that in the latter two cases, the interpretation of the object or content will depend on the data model. See B Data Models for details. If the value specified for a <data> element (by 'src', children, or the environment) is not a legal data value, the SCXML Processor MUST raise place error.execution in the internal event queue and MUST create an empty data element in the data model with the specified id.
Implementations MAY predeclare and predefine variables in the data model. However, conformant SCXML implementations SHOULD NOT assume the existence of any predeclared or predefined variables (i.e., ones not explicitly defined by <data>).
Note that this specification does not define any way to modify the data model except by<assign>, <finalize>, and possibly platform-specific elements of executable content. In particular, no means is defined for external entities to modify the data model. In this sense the data model is local to the SCXML session and the SCXML Processor checks for eventless transitions (i.e. ones that are triggered based only on the state of the data model) only after entering a state or processing an event. However in some deployments it may be possible for external entities to modify the data model. For example, if SCXML is implemented in JavaScript in a browser, the scope of a document's data model is always accessible through the main window object and thus JavaScript code elsewhere in the window can modify the data model independent of the SCXML interpretation algorithm. Such a situation can lead to race conditions and unpredictable behavior
The <assign> element is used to modify the data model.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
location | true | path expression | none | Any valid location expression. | The location in the data model into which to insert the new value. See 5.9.2 Location Expressions for details. | |
expr | false | This attribute must not occur in an <assign> element that has children. | value expression | none | Any valid value expression | An expression returning the value to be assigned. See 5.9.3 Legal Data Values and Value Expressions for details. |
The children of the <assign>element provide an in-line specification of the legal data value (see 5.9.3 Legal Data Values and Value Expressions) to be inserted into the data model at the specified location.
A conformant SCXML document MUST specify either "expr" or children of <assign>, but not both.
Assignment to a data model is done by using a location expression to denote the part of the data model where the insertion is to be made. If the location expression does not denote a valid location in the data model or if the value specified (by 'expr' or children) is not a legal value for the location specified, the SCXML Processor MUST place the error 'error.execution' in the internal event queue. Otherwise, the SCXML Processor MUST place the specified value at the specified location. Note that the nature of the insertion and the definition of a legal value depends on the data model language used. Note also that data models MAY support additional attributes for <assign> beyond those specified here. See B Data Models for details.
A wrapper element holding data to be returned when a <final> state is entered.
A conformant SCXML document MUST specify either a single <content> element or one or more <param> elements as children of <donedata>, but not both.
In cases where the SCXML Processor generates a 'done' event upon entry into the final state, it MUST evaluate the <donedata> elements <param> or <content> children and place the resulting data in the _event.data field. The exact format of that data will be determined by the data model (see B Data Models for details). In other cases (namely when the <final> element is a child of <scxml> and the state machine has not been triggered by <invoke>), the SCXML Processor SHOULD return the data to the environment in an implementation-dependent manner.
A container element holding data to be passed to an external service.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
expr | false | must not occur with child content | Value expression | none | Any valid value expression | A value expression. See 5.9.3 Legal Data Values and Value Expressions for details. |
The use of the <content> element depends on the context in which it occurs. See 5.5 <donedata>, 6.2 <send> and 6.4 <invoke> for details. When the SCXML Processor evaluates the <content> element, if the 'expr' value expression is present, the Processor MUST evaluate it and use the result as the output of the <content> element. If the evaluation of 'expr' produces an error, the Processor MUST place error.execution in the internal event queue and use the empty string as the value of the <content> element. If the 'expr' attribute is not present, the Processor MUST use the children of <content> as the output. The interpretation of the output of the <content> element depends on the data model. See B Data Models for details. For the use of namespaces inside <content>, see G.6 Inline Content and Namespaces.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
name | true | NMTOKEN | none | A string literal | The name of the key. | |
expr | false | May not occur with 'location' | value expression | none | Valid value expression | A value expression (see 5.9.3 Legal Data Values and Value Expressions) that is evaluated to provide the value. |
location | false | May not occur with 'expr' | location expression | none | Valid location expression | A location expression (see 5.9.2 Location Expressions) that specifies the location in the datamodel to retrieve the value from. |
A conformant SCXML document MUST specify either the 'expr' attribute of <param> or the 'location' attribute, but MUST NOT specify both. If the 'location' attribute does not refer to a valid location in the data model, or if the evaluation of the 'expr' produces an error, the SCXML Processor MUST place the error 'error.execution' on the internal event queue and MUST ignore the name and value. Otherwise the use of the name and value depends on the context in which the <param> element occurs. See 5.5 <donedata>, 6.2 <send> and 6.4 <invoke> for details.
The <script> element adds scripting capability to the state machine.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
src | false | May not occur if the element has children. | none | A valid URI | Gives the location from which the script should be downloaded. |
In a conformant SCXML document, the name of any script variable MAY be used as a location expression (see 5.9.2 Location Expressions).
For an example of a data model incorporating scripting, see B.2 The ECMAScript Data Model.
Location expressions are used to specify a location in the data model, e.g. as part of the <assign>, <param>, <send> or <invoke> elements. The exact nature of a location depends on the data model. For example, in the XPath data model (B.3 The XPath Data Model), the underlying data structure is an XML document consisting of a root node and children which are specified by individual <data> elements. The set of valid locations consists of the nodes and nodesets in this document. If a location expression cannot be evaluated to yield a valid location, the SCXML processor MUST place the error 'error.execution' in the internal event queue.
A data model definition contains a specification of the underlying data structure. For example, the XPath data model (B.3 The XPath Data Model) defines the data structure to be an XML document. Such a specification of the data structure implicitly defines a set of "legal data values", namely the objects that can be part of such a data structure. For an XML data model, the set of legal data values consists of XML data nodes and descendants, plus strings (as values of attributes or text children). In conjunction with this, the data model definition specifies a set of value expressions which can be evaluated at runtime to return legal data values. If a value expression does not return a legal data value, the SCXML Processor MUST place the error 'error.execution' in the internal event queue.
The set of system variables may be expanded in future versions of this specification. Variable names beginning with '_' are reserved for system use. A conformant SCXML document MUST NOT contain ids beginning with '_' in the <data> element. Platforms MUST place all platform-specific system variables under the '_x' root.
The concrete realization of these variables in a specific data model depends on the language used. For the exact location of these variables in an XML data model, see B.3 The XPath Data Model. The Processor MUST cause any attempt to change the value of a system variable to fail and MUST place the error 'error.execution' on the internal event queue when such an attempt is made.
[This section is informative.]
The External Communications capability allows an SCXML session to send and receive events from external entities, and to invoke external services. 6.2 <send> provides "fire and forget" capability to deliver events and data to any destination, including other SCXML sessions. The 'delay' attribute allows for deferred event delivery and can be used to implement a timer. The details of event transport as well as the format of the event and data are determined by the Event I/O Processor selected. Each implementation will support one or more such processor, and the author of the SCXML markup can choose the one that is appropriate for the type of endpoint he is trying to reach.
6.4 <invoke> offers a more tightly coupled form of communication, specifically the ability to trigger a platform-defined service and pass data to it. It and its child <finalize> are useful in states that model the behavior of an external service. The <invoke> element is executed after the state's <onentry> element and causes an instance of the external service to be created. The <param> and <content> elements and the 'namelist' attribute can be used to pass data to the service. Any events that are received by the state machine from the invoked component during the invocation are preprocessed by the <finalize> handler before transitions are selected. The <finalize> code is used to normalize the form of the returned data and to update the data model before the transitions' "event" and "cond" clauses are evaluated.
When parallel states invoke the same external service concurrently, separate instances of the external service will be started. They can be distinguished by ids which are associated with them. Similarly, the ids contained in the events returned from the external services can be used to determine which events are responses to which invocation. Each event that is returned will be processed only by the <finalize> in the state that invoked it, but that event is then processed like any other event that the state machine receives. The finalize code can thus be thought of as a preprocessing stage that applies before the event is added to the event queue. Note that the event will be passed to all parallel states to check for transitions.
Since an invocation will be canceled when the state machine leaves the invoking state, it does not make sense to start an invocation in a state that will be exited immediately. Therefore the <invoke> element is executed upon entry into the state, but only after checking for eventless transitions and transitions driven by pending internal events. If any such enabled transition is found , it is taken and the state is exited immediately, without triggering the invocation. Thus invocations are triggered only when the state machine has reached a stable configuration, i.e., one that it will be staying in while it waits for external events.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
event | false | Must not occur with 'eventexpr'. If the type is http://www.w3.org/TR/scxml/#SCXMLEventProcessor, either this attribute or 'eventexpr' must be present. | EventType.datatype | none | A string indicating the name of message being generated. See E Schema for details on the data type. | |
eventexpr | false | Must not occur with 'event'. If the type is http://www.w3.org/TR/scxml/#SCXMLEventProcessor, either this attribute or 'event' must be present. | Value expression | none | A dynamic alternative to 'event'. If this attribute is present, the SCXML Processor MUST evaluate it when the parent <send> element is evaluated and treat the result as if it had been entered as the value of 'event'. | |
target | false | Must not occur with 'targetexpr' | URI | none | A valid target URI | The unique identifier of the message target that the platform should send the event to. See 6.2.4 The Target of Send for details. |
targetexpr | false | Must not occur with 'target' | Value expression | none | An expression evaluating to a valid target URI | A dynamic alternative to 'target'. If this attribute is present, the SCXML Processor MUST evaluate it when the parent <send> element is evaluated and treat the result as if it had been entered as the value of 'target'. |
type | false | Must not occur with 'typeexpr' | URI | none | The URI that identifies the transport mechanism for the message. See 6.2.5 The Type of Send for details. | |
typeexpr | false | Must not occur with 'type' | value expression | none | A dynamic alternative to 'type'. If this attribute is present, the SCXML Processor MUST evaluate it when the parent <send> element is evaluated and treat the result as if it had been entered as the value of 'type'. | |
id | false | Must not occur with 'idlocation'. | xml:ID | none | Any valid token | A string literal to be used as the identifier for this instance of <send>. See 3.14 IDs for details. |
idlocation | false | Must not occur with 'id'. | Location expression | none | Any valid location expression | Any location expression evaluating to a data model location in which a system-generated id can be stored. See below for details. |
delay | false | Must not occur with 'delayexpr' or when the attribute 'target' has the value "_internal". | Duration.datatype | None | A time designation as defined in CSS2 [CSS2] format | Indicates how long the processor should wait before dispatching the message. See E Schema for details on the data type. |
delayexpr | false | Must not occur with 'delay' or when the attribute 'target' has the value "_internal". | Value expression | None | A value expression which returns a time designation as defined in CSS2 [CSS2] format | A dynamic alternative to 'delay'. If this attribute is present, the SCXML Processor MUST evaluate it when the parent <send> element is evaluated and treat the result as if it had been entered as the value of 'delay'. |
namelist | false | Must not be specified in conjunction with <content> element. | List of location expressions | none | List of valid location expressions | A space-separated list of one or more data model locations to be included as attribute/value pairs with the message. (The name of the location is the attribute and the value stored at the location is the value.) See 5.9.2 Location Expressions for details. |
A conformant SCXML document MUST specify exactly one of 'event', 'eventexpr' and <content>. A conformant document MUST NOT specify "namelist" or <param> with <content>.
The SCXML Processor MUST include all attributes and values provided by <param> or 'namelist' even if duplicates occur.
If 'idlocation' is present, the SCXML Processor MUST generate an id when the parent <send> element is evaluated and store it in this location. See 3.14 IDs for details.
If a delay is specified via 'delay' or 'delayexpr', the SCXML Processor MUST
interpret the character string as a time interval.
It MUST dispatch the message only when the delay interval
elapses. (Note that the evaluation of the send
tag will return immediately.)
The Processor MUST evaluate all arguments to <send>
when the <send> element is evaluated, and not when
the message is actually dispatched. If the
evaluation of <send>'s arguments produces an error, the Processor
MUST
discard the message without attempting to deliver it. If the SCXML
session terminates before the delay interval has elapsed, the SCXML
Processor
MUST discard the message without attempting to deliver it.
SCXML Processors MUST support the following type:
Value | Details |
---|---|
http://www.w3.org/TR/scxml/#SCXMLEventProcessor | Target is an SCXML session. The transport mechanism is platform-specific. |
For details on the http://www.w3.org/TR/scxml/#SCXMLEventProcessor type, see C.1 SCXML Event I/O Processor.
Support for HTTP POST is optional, however Processors that support it must use the following value for the "type" attribute:
Value | Details |
---|---|
http://www.w3.org/TR/scxml/#BasicHTTPEventProcessor | Target is a URL. Data is sent via HTTP POST |
For details on the http://www.w3.org/TR/scxml/#BasicHTTPEventProcessor type, see C.2 Basic HTTP Event I/O Processor.
Support for DOM event delivery is optional, however Processors that support it must use the following value for the "type" attribute:
Value | Details |
---|---|
http://www.w3.org/TR/scxml/#DOMEventProcessor | Target is a node in the current document, which may contain markup from multiple namespaces. A DOM event will be targeted at that node. |
For details on the http://www.w3.org/TR/scxml/#DOMEventProcessor type, see C.3 DOM Event I/O Processor.
Processors MAY support other types such as web-services, SIP or basic HTTP GET. When they do so, they SHOULD assign such types the URI of the description of the relevant Event I/O Processor. Processors MAY define short form notations as an authoring convenience (e.g., "scxml" as equivalent to http://www.w3.org/TR/scxml/#SCXMLEventProcessor).
Note that the document author can specify the message content in one of two mutually exclusive ways:
<datamodel> <data id="target" expr="'tel:+18005551212'"/> <data id="content" expr="'http://www.example.com/mycontent.txt'"/> </datamodel> ... <send target="target" type="x-messaging" event="fax.SEND" namelist="content"/>
<send target="csta://csta-server.example.com/" type="x-csta"> <content> <csta:MakeCall> <csta:callingDevice>22343</callingDevice> <csta:calledDirectoryNumber>18005551212</csta:calledDirectoryNumber> </csta:MakeCall> </content> </send>
Note that the absence of any error events does not mean that the event was successfully delivered to its target, but only that the platform was able to dispatch the event.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
sendid | false | Must not occur with sendidexpr. | IDREF | none | The sendid of a delayed event | The ID of the event(s) to be cancelled. If multiple delayed events have this sendid, the Processor will cancel them all. |
sendidexpr | false | Must not occur with sendid. | Value Expression | none | Any expression that evaluates to the ID of a delayed event | A dynamic alternative to 'sendid'. If this attribute is present, the SCXML Processor MUST evaluate it when the parent <cancel> element is evaluated and treat the result as if it had been entered as the value of 'sendid'. |
A conformant SCXML document MUST specify exactly one of sendid or sendidexpr.
The <invoke> element is used to create an instance of an external service.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
type | false | Must not occur with the 'typeexpr' attribute. | URI | none | http://www.w3.org/TR/scxml/, http://www.w3.org/TR/ccxml/, http://www.w3.org/TR/voicexml30/, http://www.w3.org/TR/voicexml21/ plus other platform-specific values. | A URI specifying the type of the external service. See below for details. |
typeexpr | false | Must not occur with the 'type' attribute. | value expression | none | Any value expression that evaluates to a URI that would be a valid value for 'type'. | A dynamic alternative to 'type'. If this attribute is present, the SCXML Processor MUST evaluate it when the parent <invoke> element is evaluated and treat the result as if it had been entered as the value of 'type'. |
src | false | Must not occur with the 'srcexpr' attribute or the <content> element. | URI | None | Any URI. | A URI to be passed to the external service. See below for details. |
srcexpr | false | Must not occur with the 'src' attribute or the <content> element. | Value expression | None | Any expression evaluating to a valid URI. | A dynamic alternative to 'src'. If this attribute is present, the SCXML Processor MUST evaluate it when the parent <invoke> element is evaluated and treat the result as if it had been entered as the value of 'src'. |
id | false | Must not occur with the 'idlocation' attribute. | ID | none | Any valid token | A string literal to be used as the identifier for this instance of <invoke>. See 3.14 IDs for details. |
idlocation | false | Must not occur with the 'id' attribute. | Location expression | none | Any valid location expression | Any data model expression evaluating to a data model location. See 5.9.2 Location Expressions for details. |
namelist | false | Must not occur with the <param> element. | List of location expressions | none | List of valid location expressions | A space-separated list of one or more data model locations to be passed as attribute/value pairs to the invoked service. (The name of the location is the attribute and the value stored at the location is the value.) See 6.4.4 Data Sharing and 5.9.2 Location Expressions for details. |
autoforward | false | boolean | false | true or false | A flag indicating whether to forward events to the invoked process. See below for details. |
Platforms MUST support http://www.w3.org/TR/scxml/ as a value for the 'type' attribute. Platforms MAY support http://www.w3.org/TR/voicexml21/, which indicates a VoiceXML 2.1 interpreter, http://www.w3.org/TR/voicexml30/, which indicates a VoiceXML 3.x interpreter, and http://www.w3.org/TR/ccxml/, which indicates a CCXML 1.0 interpreter. Platforms MAY support additional values, but they SHOULD assign them the URI of a description of the relevant service. Processors MAY define short form notations as an authoring convenience (e.g., "scxml" as equivalent to http://www.w3.org/TR/scxml/).
A conformant SCXML document MAY specify either the 'id' or 'idlocation' attribute, but MUST NOT specify both. If the 'idlocation' attribute is present, the SCXML Processor MUST generate an id automatically when the <invoke> element is evaluated and store it in the location specified by 'idlocation'. (In the rest of this document, we will refer to this identifier as the "invokeid", regardless of whether it is specified by the author or generated by the platform). The automatically generated identifier MUST have the form stateid.platformid, where stateid is the id of the state containing this element and platformid is automatically generated. platformid MUST be unique within the current session.
When the <invoke> element is executed, if the evaluation of its arguments produces an error, the SCXML Processor MUST terminate the processing of the element without further action. Otherwise the Processor MUST start a new logical instance of the external service specified in 'type' or 'typeexpr', passing it the URL specified by 'src' or the data specified by <content>, "namelist" or <param>. (Note that the invoked service may ignore some or all of the data passed to it. See 6.4.3 Implementation of <invoke> for a discussion of how the passed data is treated by an invoked SCXML service.) The service instance MAY be local or remote. In addition to the explicit arguments, the Processor MUST keep track of the unique invokeid and ensure that it is included in all events that the invoked service returns to the invoking session.
When the 'autoforward' attribute is set to true, the SCXML Processor MUST send an exact copy of every external event it receives to the invoked process. All the fields specified in 5.10.1 The Internal Structure of Events MUST have the same values in the forwarded copy of the event. The SCXML Processor MUST forward the event at the point at which it removes it from the external event queue of the invoking session for processing.
The external service MAY return multiple events while it is processing. If there is a <finalize> handler in the instance of <invoke> that created the service that generated the event, the SCXML Processor MUST execute the code in that <finalize> handler right before it removes the event from the event queue for processing. It MUST NOT execute the <finalize> handler in any other instance of <invoke>. Once the external service has finished processing it MUST return a special event 'done.invoke.id' to the external event queue of the invoking process, where id is the invokeid for the corresponding <invoke> element. The external service MUST NOT generate any other events after this done event. If the invoking session takes a transition out of the state containing the <invoke> before it receives the 'done.invoke.id' event, the SCXML Processor MUST automatically cancel the invoked component and stop its processing. The cancel operation MUST act as if it were the final <onexit> handler in the invoking state.
Invoked services of type http://www.w3.org/TR/scxml/, http://www.w3.org/TR/ccxml/, http://www.w3.org/TR/voicexml30/, or http://www.w3.org/TR/voicexml21/ MUST interpret values specified by the <content> element or 'src' attribute as markup to be executed. Similarly, they MUST interpret values specified by <param> element or 'namelist' attribute as values that are to be injected into their data models. For targets of other invoked service types, the interpretation of <param> and <content> elements and the 'src' and 'namelist' attributes is platform-specific. However, these services MUST treat values specified by <param> and namelist identically. They MUST also treat values specified by 'src' and <content> identically.
The following conformance requirements hold for all SCXML documents.
A SCXML 1.0 processor is a user agent that can parse and process Conforming SCXML 1.0 documents.
In a Conforming SCXML 1.0 Processor, the XML parser MUST be able to parse and process all well-formed XML constructs defined within [XML] and [XMLNames]. It is not required that a Conforming SCXML 1.0 processor use a validating parser.
A Conforming SCXML 1.0 Processor MUST support the syntax and semantics of all mandatory SCXML elements described in this document. A Conforming SCXML 1.0 Processor MAY support the syntax and semantics of any optional SCXML elements described in this document.
When a Conforming SCXML 1.0 Processor encounters a non-conformant document, or one containing non-SCXML elements or attributes which are proprietary, or defined in a non-SCXML namespace, its behavior is undefined.
There is no conformance requirement with respect to performance characteristics of the SCXML 1.0 Processor.
The definition of a data model MUST:
The <foreach> element and the elements defined in 5 Data Model and Data Manipulation are not supported in the Null Data Model.
The value 'ecmascript' for the 'datamodel' attribute results in an ECMAScript data model. Implementations that support this value MUST support the third edition of ECMAScript [ECMASCRIPT-262]. Implementations MAY support JSON [RFC 4627] or ECMAScript for XML (E4X) [E4X].
The Processor MUST convert ECMAScript expressions used in conditional expressions into their effective boolean value using the ToBoolean operator as described in Section 9.2 of [ECMASCRIPT-262].
The following example illustrates this usage.
The SCXML processor MUST define an ECMAScript function named '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 5.9.1 Conditional Expressions. Here is an example of its use, taken from G.3 Microwave Example (Using parallel) below:
<transition cond="In('closed')" target="cooking"/>
The SCXML Processor MUST accept any ECMAScript expression as a value expression.
When <content> is a child of <donedata>, the Processor MUST interpret its value as defined in B.2.8.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.
The SCXML Processor MUST define
an ECMAScript read-only variable for each system variable defined
in 5.10 System Variables. The _sessionid
and _name
system variables are defined as variables with ECMAScript String values.
The _event
system variable is defined as an
object with properties for each of the fields defined in 5.10.1 The Internal Structure of Events:
name
,type
, sendid
, origin
, origintype
,
and invokeid
are String values, while data
can be of any type.
In cases where this specification does not specify a value for one of these fields or
states that the field is empty or has no value,
the Processor MUST set the value to ECMAScript undefined.
As the value of the _ioprocessors system variable the Processor MUST create an object
with a named property for each Event I/O processor that it supports, where the name of the property
is the same as that of the I/O processor and the value of the property is an object
that represents the I/O processor. For the SCXML and BasicHTTP Event I/O processors,
the Processor MUST create a "location" property under that object,
assigning the access URI as its String value. For example, in systems that support the
BasicHTTP Event I/O Processor, the access URI of the BasicHTTP Event I/O processor
can be accessed as _ioprocessors['http://www.w3.org/TR/scxml/#BasicHTTPEventProcessor'].location.
Then the underlying ECMAScript data model would have the following form:
As an example, here is a sample transition that accesses the
_event
variable in that data model.
The SCXML Processor MUST accept any ECMAScript program as defined in Section 14 of [ECMASCRIPT-262] as the content of a <script> element.
The value "xpath" for the 'datamodel' attribute results in an XML data model with XPath used as the expression language. Implementations that support this data model MUST support [XPath 1.0].
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.
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 5.9.1 Conditional Expressions. For examples of the use of this predicate (but in an ECMAScript context), see G.3 Microwave Example (Using parallel).
Function signature: In($stateID as xs:string?) as xs:boolean
Returns an xs:boolean
indicating whether or not the state with ID $stateID is
one of the currently active states.
When <content> is a child of <donedata>, the Processor MUST interpret its value as defined in B.3.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.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
type | false | enum | replacechildren | replacechildren, firstchild, lastchild, previoussibling, nextsibling, replace, delete, addattribute | Defines the nature of the insertion to be performed. See below for details. | |
attr | false | This attribute must be present if and only if 'type' is 'addattribute'. | NMTOKEN | none | The attribute name to add at the specified location. |
Here is an example of assignment of a string to an element node.
Here are examples of legal and illegal assignment to an attribute:
For each system variable defined in 5.10 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 5.10.1 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().
The sending and receiving SCXML Processors MUST maintain the following mappings:
When using the SCXML Event I/O Processor, SCXML Processors MUST support the following special targets for <send>:
If neither the 'target' nor the 'targetexpr' attribute is specified, the SCXML Processor MUST add the event to the external event queue of the sending session.
If the sending SCXML session specifies a session that does not exist or is inaccessible, the SCXML Processor MUST place the error error.communication on the internal event queue of the sending session. If the receiving Processor cannot handle the data format contained in the message, the receiving Processor MUST place the error error.communication in internal queue of the session for which the message was intended and MUST ignore the message. The Processor SHOULD also notify the sending processor of the error. If no errors occur, the receiving Processor MUST convert the message into an SCXML event, using the mapping defined above, and insert the event into the appropriate queue, as defined in 6.2.4 The Target of Send
An SCXML Processor that supports the Basic HTTP Event I/O Processor MUST accept messages at the access URI as HTTP POST requests (see [RFC 2616]). The SCXML Processor MUST validate the message it receives and then MUST build the appropriate SCXML event and MUST add it to the external event queue.
If a single instance of the parameter '_scxmleventname' is present, the SCXML Processor MUST use its value as the name of the SCXML event that it raises. If multiple instances of the parameter are present, the behavior is platform-specific. If the parameter '_scxmleventname' is not present, the SCXML Processor MUST use the name of the HTTP method that was used to deliver the message as the name of the event that it raises. The processor MUST use any message content other than '_scxmleventname' to populate _event.data. See B Data Models for details.
After it adds the received message to the appropriate event queue, the SCXML Processor MUST then indicate the result to the external component via a success response code 2XX. Note that this response is sent before the event is removed from the queue and processed. In the cases where the message cannot be formed into an SCXML event, the Processor MUST return an HTTP error code as defined in [RFC 2616].
An SCXML implementation can send events with the Basic HTTP Event I/O Processor using the <send> element (see 6.2 <send>) with the type attribute set to "http://www.w3.org/TR/scxml/#BasicHTTPEventProcessor" and the target attribute set to the access URI of the target. If neither the 'target' nor the 'targetexpr' attribute is specified, the SCXML Processor MUST add the event error.communication to the internal event queue of the sending session.
The SCXML Processor MUST attempt to deliver the message using HTTP method "POST" and with parameter values encoded by default in an application/x-www-form-urlencoded body (POST method). An SCXML Processor MAY support other encodings, and allow them to be specified in a platform-specific way.
If the 'event' parameter of <send> is defined, the SCXML Processor MUST use its value as the value of the HTTP POST parameter _scxmleventname. If the namelist attribute is defined, the SCXML Processor MUST map its variable names and values to HTTP POST parameters. If one or more <param> children are present, the SCXML Processor MUST map their names (i.e. name attributes) and values to HTTP POST parameters. If a <content> child is present, the SCXML Processor MUST use its value as the body of the message.
The DOM Event I/O processor handles communication between SCXML Interpreters and nodes in documents that implement the DOM. An example of this would be a document containing both SCXML and HTML markup. In such a case, each language retains its own context and its own independent semantics. (Note that the syntax and semantics of SCXML make no reference to the DOM, so that SCXML's event processing algorithm is not affected by the fact that there is HTML markup elsewhere in the document.) It is however useful for the two languages to be able to communicate by sending events back and forth, so that the User Agent can notify SCXML when the user clicks on a button, and the SCXML markup can notify the appropriate element when it is time to place a certain field in focus, etc. The DOM Event I/O processor handles this communication by means of DOM Events [DOMEvents], which are a general means for information propagation in XML documents. Note that we do not require that the SCXML document be represented in the other markup's DOM (though it may be).
The SCXML Processor MUST support sending DOM events to any node in the document by selecting the DOM Event I/O processor (type="http://www.w3.org/TR/scxml/#DOMEventProcessor") and specifying the node as the target. Processors MUST support CSS notation [CSS2] for specifying the node, and MAY support XPath [XPath 1.0] or other notations. The SCXML Processor MUST support sending events that implement the CustomEvent interface. The Processor MAY support sending events that implement other interfaces. In this case, the Processor MUST support an additional attribute on <send>, called 'interface', that allows the author to specify the interface to use. The default value of this attribute MUST be 'CustomEvent'.
The Processor MUST use the value of the 'event' attribute as the type of the DOM event. The Processor MUST support two additional attributes on <send>, called 'cancelable' and 'bubbles', which can be used to set the corresponding properties of the event. The default value for 'cancelable' MUST be 'false'. The default value of 'bubbles' MUST be 'true'. The Processor MUST populate any other initializable attributes of the event with the values of any matching keys specified via "namelist" or <param>. If the specified DOM event type has a 'detail' attribute, the Processor MUST populate it with any remaining data (i.e., values specified by 'namelist', <param> or <content> that are not used to populate the event's initializable attributes.) If the specified event is not a legal DOM event or if the specified node cannot be reached, the SCXML Processor MUST place the error error.communication in the internal event queue.
[This section is informative.]
We state here some principles and constraints, on the level of semantics, that SCXML adheres to:
These are the abstract datatypes that are used in the algorithm.
datatype Listfunction
head() // Returns the head of the listfunction
tail() // Returns the tail of the list (i.e., the rest of the list once the head is removed)function
append(l) // Returns the list appended with lfunction
filter(f) // Returns the list of elements that satisfy the predicate ffunction
some(f) // Returns true if some element in the list satisfies the predicate f. Returns false for an empty list.function
every(f) // Returns true if every element in the list satisfies the predicate f. Returns true for an empty list. The notation [...] is used as a list constructor, so that '[t]' denotes a list whose only member is the object t. datatype OrderedSetprocedure
add(e) // Adds e to the set if it is not already a memberprocedure
delete(e) // Deletes e from the setprocedure
union(s) // Adds all members of s that are not already members of the set (s must also be an OrderedSet)function
isMember(e) // Is e a member of set?function
some(f) // Returns true if some element in the set satisfies the predicate f. Returns false for an empty set.function
every(f) // Returns true if every element in the set satisfies the predicate f. Returns true for an empty set.function
hasIntersection(s) // Returns true if this set and set s have at least one member in commonfunction
isEmpty() // Is the set empty?procedure
clear() // Remove all elements from the set (make it empty)function
toList() // Converts the set to a list that reflects the order in which elements were originally added // In the case of sets created by intersection, the order of the first set (the one on which the method was called) is used // In the case of sets created by union, the members of the first set (the one on which union was called) retain their original ordering // while any members belonging to the second set only are placed after, retaining their ordering in their original set. datatype Queueprocedure
enqueue(e) // Puts e last in the queuefunction
dequeue() // Removes and returns first element in queuefunction
isEmpty() // Is the queue empty? datatype BlockingQueueprocedure
enqueue(e) // Puts e last in the queuefunction
dequeue() // Removes and returns first element in queue, blocks if queue is empty datatype HashTable // table[foo] returns the value associated with foo. table[foo] = bar sets the value associated with foo to be bar.
global configuration global statesToInvoke global datamodel global internalQueue global externalQueue global historyValue global running global binding
entryOrder
// Ancestors precede descendants, with document order being used to break ties (Note:since ancestors precede descendants, this is equivalent to document order.)exitOrder
// Descendants precede ancestors, with reverse document order being used to break ties (Note: since descendants follow ancestors, this is equivalent to reverse document order.)
The following binary predicate is used to determine the order in which we examine transitions within a state.
documentOrder
// The order in which the elements occurred in the original document.
This section defines the procedures and functions that make up the core of the SCXML interpreter. N.B. in the code below, the keyword 'continue' has its traditional meaning in languages like C: break off the current iteration of the loop and proceed to the next iteration.
procedure
interpret(scxml,id)The purpose of this procedure is to initialize the interpreter and to start processing.
In order to interpret an SCXML document, first (optionally) perform [xinclude] processing and (optionally) validate the document, throwing an exception if validation fails. Then convert initial attributes to <initial> container children with transitions to the state specified by the attribute. (This step is done purely to simplify the statement of the algorithm and has no effect on the system's behavior. Such transitions will not contain any executable content). Initialize the global data structures, including the data model. If binding is set to 'early', initialize the data model. Then execute the global <script> element, if any. Finally call enterStates on the initial configuration, set the global running variable to true and start the interpreter's event loop.
procedure interpret(doc): if not valid(doc): failWithError() expandScxmlSource(doc) configuration = new OrderedSet() statesToInvoke = new OrderedSet() internalQueue = new Queue() externalQueue = new BlockingQueue() historyValue = new HashTable() datamodel = new Datamodel(doc) if doc.binding == "early": initializeDatamodel(datamodel, doc) running = true executeGlobalScriptElement(doc) enterStates([doc.initial.transition]) mainEventLoop()
procedure
mainEventLoop()This loop runs until we enter a top-level final state or an external entity cancels processing. In either case 'running' will be set to false (see EnterStates, below, for termination by entering a top-level final state.)
At the top of the loop, we have either just entered the state machine, or we have just processed an external event. Each iteration through the loop consists of four main steps: 1)Complete the macrostep by repeatedly taking any internally enabled transitions, namely those that don't require an event or that are triggered by an internal event. After each such transition/microstep, check to see if we have reached a final state. 2) When there are no more internally enabled transitions available, the macrostep is done. Execute any <invoke> tags for states that we entered on the last iteration through the loop 3) If any internal events have been generated by the invokes, repeat step 1 to handle any errors raised by the <invoke> elements. 4) When the internal event queue is empty, wait for an external event and then execute any transitions that it triggers. However special preliminary processing is applied to the event if the state has executed any <invoke> elements. First, if this event was generated by an invoked process, apply <finalize> processing to it. Secondly, if any <invoke> elements have autoforwarding set, forward the event to them. These steps apply before the transitions are taken.
This event loop thus enforces run-to-completion semantics, in which the system process an external event and then takes all the 'follow-up' transitions that the processing has enabled before looking for another external event. For example, suppose that the external event queue contains events ext1 and ext2 and the machine is in state s1. If processing ext1 takes the machine to s2 and generates internal event int1, and s2 contains a transition t triggered by int1, the system is guaranteed to take t, no matter what transitions s2 or other states have that would be triggered by ext2. Note that this is true even though ext2 was already in the external event queue when int1 was generated. In effect, the algorithm treats the processing of int1 as finishing up the processing of ext1.
procedure mainEventLoop(): while running: enabledTransitions = null macrostepDone = false # Here we handle eventless transitions and transitions # triggered by internal events until macrostep is complete while running and not macrostepDone: enabledTransitions = selectEventlessTransitions() if enabledTransitions.isEmpty(): if internalQueue.isEmpty(): macrostepDone = true else: internalEvent = internalQueue.dequeue() datamodel["_event"] = internalEvent enabledTransitions = selectTransitions(internalEvent) if not enabledTransitions.isEmpty(): microstep(enabledTransitions.toList()) # either we're in a final state, and we break out of the loop if not running: break # or we've completed a macrostep, so we start a new macrostep by waiting for an external event # Here we invoke whatever needs to be invoked. The implementation of 'invoke' is platform-specific for state in statesToInvoke.sort(entryOrder): for inv in state.invoke.sort(documentOrder): invoke(inv) statesToInvoke.clear() # Invoking may have raised internal error events and we iterate to handle them if not internalQueue.isEmpty(): continue # A blocking wait for an external event. Alternatively, if we have been invoked # our parent session also might cancel us. The mechanism for this is platform specific, # but here we assume it’s a special event we receive externalEvent = externalQueue.dequeue() if isCancelEvent(externalEvent): running = false continue datamodel["_event"] = externalEvent for state in configuration: for inv in state.invoke: if inv.invokeid == externalEvent.invokeid: applyFinalize(inv, externalEvent) if inv.autoforward: send(inv.id, externalEvent) enabledTransitions = selectTransitions(externalEvent) if not enabledTransitions.isEmpty(): microstep(enabledTransitions.toList()) # End of outer while running loop. If we get here, we have reached a top-level final state or have been cancelled exitInterpreter()
procedure
exitInterpreter()The purpose of this procedure is to exit the current SCXML process by exiting all active states. If the machine is in a top-level final state, a Done event is generated. (Note that in this case, the final state will be the only active state.) The implementation of returnDoneEvent is platform-dependent, but if this session is the result of an <invoke> in another SCXML session, returnDoneEvent will cause the event done.invoke.<id> to be placed in the external event queue of that session, where <id> is the id generated in that session when the <invoke> was executed.
procedure exitInterpreter(): statesToExit = configuration.toList().sort(exitOrder) for s in statesToExit: for content in s.onexit.sort(documentOrder): executeContent(content) for inv in s.invoke: cancelInvoke(inv) configuration.delete(s) if isFinalState(s) and isScxmlElement(s.parent): returnDoneEvent(s.donedata)
function
selectEventlessTransitions()This function selects all transitions that are enabled in the current configuration that do not
require an event trigger. First find a transition with no 'event' attribute
whose condition evaluates to true
.
If multiple matching transitions are present, take the first
in document order. If none are present, search in the state's
ancestors in ancestry order until one is found. As soon as such a transition
is found, add it to enabledTransitions, and proceed to the next atomic state
in the configuration. If no such transition is found in the state
or its ancestors, proceed to the next state in the configuration.
When all atomic states have been visited and transitions selected,
filter the set of enabled transitions, removing any that are preempted by other
transitions, then return the resulting set.
function selectEventlessTransitions(): enabledTransitions = new OrderedSet() atomicStates = configuration.toList().filter(isAtomicState).sort(documentOrder) for state in atomicStates: loop: for s in [state].append(getProperAncestors(state, null)): for t in s.transition.sort(documentOrder): if not t.event and conditionMatch(t): enabledTransitions.add(t) break loop enabledTransitions = removeConflictingTransitions(enabledTransitions) return enabledTransitions
function
selectTransitions(event)The purpose of the selectTransitions()procedure is to collect the transitions that are enabled by this event in the current configuration.
Create an empty set of enabledTransitions
. For each atomic state ,
find a transition whose 'event' attribute matches
event
and whose condition evaluates to true
.
If multiple matching transitions are present, take the first
in document order. If none are present, search in the state's
ancestors in ancestry order until one is found. As soon as such a transition
is found, add it to enabledTransitions, and proceed to the next atomic state
in the configuration. If no such transition is found in the state
or its ancestors, proceed to the next state in the configuration.
When all atomic states have been visited and transitions selected,
filter out any preempted transitions and return the resulting set.
function selectTransitions(event): enabledTransitions = new OrderedSet() atomicStates = configuration.toList().filter(isAtomicState).sort(documentOrder) for state in atomicStates: loop: for s in [state].append(getProperAncestors(state, null)): for t in s.transition.sort(documentOrder): if t.event and nameMatch(t.event, event.name) and conditionMatch(t): enabledTransitions.add(t) break loop enabledTransitions = removeConflictingTransitions(enabledTransitions) return enabledTransitions
function
removeConflictingTransitions(enabledTransitions)enabledTransitions will contain multiple transitions only if a parallel state is active. In that case, we may have one transition selected for each of its children. These transitions may conflict with each other in the sense that they have incompatible target states. Loosely speaking, transitions are compatible when each one is contained within a single <state> child of the <parallel> element. Transitions that aren't contained within a single child force the state machine to leave the <parallel> ancestor (even if they reenter it later). Such transitions conflict with each other, and with transitions that remain within a single <state> child, in that they may have targets that cannot be simultaneously active. The test that transitions have non-intersecting exit sets captures this requirement. (If the intersection is null, the source and targets of the two transitions are contained in separate <state> descendants of <parallel>. If intersection is non-null, then at least one of the transitions is exiting the <parallel>). When such a conflict occurs, then if the source state of one of the transitions is a descendant of the source state of the other, we select the transition in the descendant. Otherwise we prefer the transition that was selected by the earlier state in document order and discard the other transition. Note that targetless transitions have empty exit sets and thus do not conflict with any other transitions.
We start with a list of enabledTransitions and produce a conflict-free list of filteredTransitions. For each t1 in enabledTransitions, we test it against all t2 that are already selected in filteredTransitions. If there is a conflict, then if t1's source state is a descendant of t2's source state, we prefer t1 and say that it preempts t2 (so we we make a note to remove t2 from filteredTransitions). Otherwise, we prefer t2 since it was selected in an earlier state in document order, so we say that it preempts t1. (There's no need to do anything in this case since t2 is already in filteredTransitions. Furthermore, once one transition preempts t1, there is no need to test t1 against any other transitions.) Finally, if t1 isn't preempted by any transition in filteredTransitions, remove any transitions that it preempts and add it to that list.
function removeConflictingTransitions(enabledTransitions): filteredTransitions = new OrderedSet() //toList sorts the transitions in the order of the states that selected them for t1 in enabledTransitions.toList(): t1Preempted = false transitionsToRemove = new OrderedSet() for t2 in filteredTransitions.toList(): if computeExitSet([t1]).hasIntersection(computeExitSet([t2])): if isDescendant(t1.source, t2.source): transitionsToRemove.add(t2) else: t1Preempted = true break if not t1Preempted: for t3 in transitionsToRemove.toList(): filteredTransitions.delete(t3) filteredTransitions.add(t1) return filteredTransitions
procedure
microstep(enabledTransitions)The purpose of the microstep procedure
is to process a single set of
transitions. These may have been enabled by an external event, an internal event, or
by the presence or absence of certain values in the data model at the current point in time.
The processing of the enabled transitions must be done in parallel ('lock step') in the sense
that their source states must first be exited, then their actions must be executed, and finally
their target states entered.
If a single atomic state is active, then enabledTransitions will contain only a single transition. If multiple states are active (i.e., we are in a parallel region), then there may be multiple transitions, one per active atomic state (though some states may not select a transition.) In this case, the transitions are taken in the document order of the atomic states that selected them.
procedure microstep(enabledTransitions): exitStates(enabledTransitions) executeTransitionContent(enabledTransitions) enterStates(enabledTransitions)
procedure
exitStates(enabledTransitions)Compute the set of states to exit. Then remove all the states on statesToExit from the set of states that will have invoke processing done at the start of the next macrostep. (Suppose macrostep M1 consists of microsteps m11 and m12. We may enter state s in m11 and exit it in m12. We will add s to statesToInvoke in m11, and must remove it in m12. In the subsequent macrostep M2, we will apply invoke processing to all states that were entered, and not exited, in M1.) Then convert statesToExit to a list and sort it in exitOrder.
For each state s in the list, if s has a deep history state h, set the history value of h to be the list of all atomic descendants of s that are members in the current configuration, else set its value to be the list of all immediate children of s that are members of the current configuration. Again for each state s in the list, first execute any onexit handlers, then cancel any ongoing invocations, and finally remove s from the current configuration.
procedure exitStates(enabledTransitions): statesToExit = computeExitSet(enabledTransitions) for s in statesToExit: statesToInvoke.delete(s) statesToExit = statesToExit.toList().sort(exitOrder) for s in statesToExit: for h in s.history: if h.type == "deep": f = lambda s0: isAtomicState(s0) and isDescendant(s0,s) else: f = lambda s0: s0.parent == s historyValue[h.id] = configuration.toList().filter(f) for s in statesToExit: for content in s.onexit.sort(documentOrder): executeContent(content) for inv in s.invoke: cancelInvoke(inv) configuration.delete(s)
procedure
computeExitSet(enabledTransitions)For each transition t in enabledTransitions, if t is targetless then do nothing, else compute the transition's domain. (This will be the source state in the case of internal transitions) or the least common compound ancestor state of the source state and target states of t (in the case of external transitions. Add to the statesToExit set all states in the configuration that are descendants of the domain.
function computeExitSet(transitions) statesToExit = new OrderedSet for t in transitions: if t.target: domain = getTransitionDomain(t) for s in configuration: if isDescendant(s,domain): statesToExit.add(s) return statesToExit
procedure
executeTransitionContent(enabledTransitions)For each transition in the list of enabledTransitions
, execute its executable content.
procedure executeTransitionContent(enabledTransitions): for t in enabledTransitions: executeContent(t)
procedure
enterStates(enabledTransitions)First, compute the list of all the states that will be entered as a result of taking the transitions in enabledTransitions. Add them to statesToInvoke so that invoke processing can be done at the start of the next macrostep. Convert statesToEnter to a list and sort it in entryOrder. For each state s in the list, first add s to the current configuration. Then if we are using late binding, and this is the first time we have entered s, initialize its data model. Then execute any onentry handlers. If s's initial state is being entered by default, execute any executable content in the initial transition. If a history state in s was the target of a transition, and s has not been entered before, execute the content inside the history state's default transition. Finally, if s is a final state, generate relevant Done events. If we have reached a top-level final state, set running to false as a signal to stop processing.
procedure enterStates(enabledTransitions): statesToEnter = new OrderedSet() statesForDefaultEntry = new OrderedSet() // initialize the temporary table for default content in history states defaultHistoryContent = new HashTable() computeEntrySet(enabledTransitions, statesToEnter, statesForDefaultEntry, defaultHistoryContent) for s in statesToEnter.toList().sort(entryOrder): configuration.add(s) statesToInvoke.add(s) if binding == "late" and s.isFirstEntry: initializeDataModel(datamodel.s,doc.s) s.isFirstEntry = false for content in s.onentry.sort(documentOrder): executeContent(content) if statesForDefaultEntry.isMember(s): executeContent(s.initial.transition) if defaultHistoryContent[s.id]: executeContent(defaultHistoryContent[s.id]) if isFinalState(s): if isSCXMLElement(s.parent): running = false else: parent = s.parent grandparent = parent.parent internalQueue.enqueue(new Event("done.state." + parent.id, s.donedata)) if isParallelState(grandparent): if getChildStates(grandparent).every(isInFinalState): internalQueue.enqueue(new Event("done.state." + grandparent.id))
procedure
computeEntrySet(transitions, statesToEnter, statesForDefaultEntry, defaultHistoryContent)Compute the complete set of states that will be entered as a result of taking 'transitions'. This value will be returned in 'statesToEnter' (which is modified by this procedure). Also place in 'statesForDefaultEntry' the set of all states whose default initial states were entered. First gather up all the target states in 'transitions'. Then add them and, for all that are not atomic states, add all of their (default) descendants until we reach one or more atomic states. Then add any ancestors that will be entered within the domain of the transition. (Ancestors outside of the domain of the transition will not have been exited.)
procedure computeEntrySet(transitions, statesToEnter, statesForDefaultEntry, defaultHistoryContent) for t in transitions: for s in t.target: addDescendantStatesToEnter(s,statesToEnter,statesForDefaultEntry, defaultHistoryContent) ancestor = getTransitionDomain(t) for s in getEffectiveTargetStates(t)): addAncestorStatesToEnter(s, ancestor, statesToEnter, statesForDefaultEntry, defaultHistoryContent)
procedure
addDescendantStatesToEnter(state,statesToEnter,statesForDefaultEntry, defaultHistoryContent)The purpose of this procedure is to add to statesToEnter 'state' and any of its descendants that the state machine will end up entering when it enters 'state'. (N.B. If 'state' is a history pseudo-state, we dereference it and add the history value instead.) Note that this procedure permanently modifies both statesToEnter and statesForDefaultEntry.
First, If state is a history state then add either the history values associated with state or state's default target to statesToEnter. Then (since the history value may not be an immediate descendant of 'state's parent) add any ancestors between the history value and state's parent. Else (if state is not a history state), add state to statesToEnter. Then if state is a compound state, add state to statesForDefaultEntry and recursively call addStatesToEnter on its default initial state(s). Then, since the default initial states may not be children of 'state', add any ancestors between the default initial states and 'state'. Otherwise, if state is a parallel state, recursively call addStatesToEnter on any of its child states that don't already have a descendant on statesToEnter.
procedure addDescendantStatesToEnter(state,statesToEnter,statesForDefaultEntry, defaultHistoryContent): if isHistoryState(state): if historyValue[state.id]: for s in historyValue[state.id]: addDescendantStatesToEnter(s,statesToEnter,statesForDefaultEntry, defaultHistoryContent) for s in historyValue[state.id]: addAncestorStatesToEnter(s, state.parent, statesToEnter, statesForDefaultEntry, defaultHistoryContent) else: defaultHistoryContent[state.parent.id] = state.transition.content for s in state.transition.target: addDescendantStatesToEnter(s,statesToEnter,statesForDefaultEntry, defaultHistoryContent) for s in state.transition.target: addAncestorStatesToEnter(s, state.parent, statesToEnter, statesForDefaultEntry, defaultHistoryContent) else: statesToEnter.add(state) if isCompoundState(state): statesForDefaultEntry.add(state) for s in state.initial.transition.target: addDescendantStatesToEnter(s,statesToEnter,statesForDefaultEntry, defaultHistoryContent) for s in state.initial.transition.target: addAncestorStatesToEnter(s, state, statesToEnter, statesForDefaultEntry, defaultHistoryContent) else: if isParallelState(state): for child in getChildStates(state): if not statesToEnter.some(lambda s: isDescendant(s,child)): addDescendantStatesToEnter(child,statesToEnter,statesForDefaultEntry, defaultHistoryContent)
procedure
addAncestorStatesToEnter(state, ancestor, statesToEnter, statesForDefaultEntry, defaultHistoryContent)Add to statesToEnter any ancestors of 'state' up to, but not including, 'ancestor' that must be entered in order to enter 'state'. If any of these ancestor states is a parallel state, we must fill in its descendants as well.
procedure addAncestorStatesToEnter(state, ancestor, statesToEnter, statesForDefaultEntry, defaultHistoryContent) for anc in getProperAncestors(state,ancestor): statesToEnter.add(anc) if isParallelState(anc): for child in getChildStates(anc): if not statesToEnter.some(lambda s: isDescendant(s,child)): addDescendantStatesToEnter(child,statesToEnter,statesForDefaultEntry, defaultHistoryContent)
procedure
isInFinalState(s)Return true if s is a compound <state> and one of its children is an active <final> state (i.e. is a member of the current configuration), or if s is a <parallel> state and isInFinalState is true of all its children.
function isInFinalState(s): if isCompoundState(s): return getChildStates(s).some(lambda s: isFinalState(s) and configuration.isMember(s)) elif isParallelState(s): return getChildStates(s).every(isInFinalState) else: return false
function
getTransitionDomain(transition)Return the compound state such that 1) all states that are exited or entered as a result of taking 'transition' are descendants of it 2) no descendant of it has this property.
function getTransitionDomain(t) tstates = getEffectiveTargetStates(t) if not tstates: return null elif t.type == "internal" and isCompoundState(t.source) and tstates.every(lambda s: isDescendant(s,t.source)): return t.source else: return findLCCA([t.source].append(tstates))
function
findLCCA(stateList)The Least Common Compound Ancestor is the <state> or <scxml> element s such that s is a proper ancestor of all states on stateList and no descendant of s has this property. Note that there is guaranteed to be such an element since the <scxml> wrapper element is a common ancestor of all states. Note also that since we are speaking of proper ancestor (parent or parent of a parent, etc.) the LCCA is never a member of stateList.
function findLCCA(stateList): for anc in getProperAncestors(stateList.head(),null).filter(isCompoundStateOrScxmlElement): if stateList.tail().every(lambda s: isDescendant(s,anc)): return anc
function
getEffectiveTargetStates(transition)Returns the states that will be the target when 'transition' is taken, dereferencing any history states.
function getEffectiveTargetStates(transition) targets = new OrderedSet() for s in transition.target if isHistoryState(s): if historyValue[s.id]: targets.union(historyValue[s.id]) else: targets.union(getEffectiveTargetStates(s.transition)) else: targets.add(s) return targets
function
getProperAncestors(state1, state2)If state2 is null, returns the set of all ancestors of state1 in ancestry order (state1's parent followed by the parent's parent, etc. up to an including the <scxml> element). If state2 is non-null, returns in ancestry order the set of all ancestors of state1, up to but not including state2. (A "proper ancestor" of a state is its parent, or the parent's parent, or the parent's parent's parent, etc.))If state2 is state1's parent, or equal to state1, or a descendant of state1, this returns the empty set.
function
isDescendant(state1, state2)Returns 'true' if state1 is a descendant of state2 (a child, or a child of a child, or a child of a child of a child, etc.) Otherwise returns 'false'.
function
getChildStates(state1)Returns a list containing all <state>, <final>, and <parallel> children of state1.
[This section is informative.]
Schemas for SCXML can be found in www.w3.org/2011/04/SCXML. Two sets of schemas are available. One uses Schema 1.0 and is relatively loose, in the sense that it does not enforce all the restrictions contained in this specification. Its master schema is http://www.w3.org/2011/04/SCXML/scxml.xsd. The other set of schemas uses Schema 1.1, in particular the <assert> element, and is stricter. Its master schema is http://www.w3.org/2011/04/SCXML/scxml-strict.xsd.
[This section is informative.]
A number of other XML-based state machine notations have been developed, but none serves the same purpose as SCXML. XMI [UML XMI] is a notation developed for representing UML diagrams, including Harel statecharts. However it is intended as a machine interchange format and is not readily authorable by humans. ebXML [ebXML] is a language for business process specification intended to support B2B e-commerce applications. It contains a state machine language that is in some ways similar to the one presented here, but its syntax and semantics are closely tied to its intended use in e-commerce. It is therefore not suitable as a general-purpose state machine language. XTND [XTND], also called XML Transition Network Definition, is a notation for simple finite state machines but lacks Harel's notions of hierarchical and parallel states and are thus not suitable for a general-purpose state machine that is semantically equivalent to Harel state charts.
[This section is informative.]
The example below shows the implementation of a simple microwave oven using SCXML.
The following example shows a the control flow for a blackjack game.
The recipient of the message will see the following:
The following markup would cause the message to be delivered without namespaces:
The recipient of the message will see the following:
This appendix registers a new MIME media type, "application/scxml+xml
".
application
scxml+xml
application/scxml+xml
" may describe content that has
security implications beyond those described here.
However, if the processor follows only the normative semantics of this
specification, this content will be ignored.
Only in the case where the processor recognizes and processes the
additional content, or where further processing of that content is
dispatched to other processors, would security issues potentially
arise.
And in that case, they would fall outside the domain of this
registration document.application/scxml+xml
" processors MAY expect that
content received is well-formed XML, but processors SHOULD NOT
assume that the content is valid SCXML or expect to recognize all of
the elements and attributes in the document..scxml
".