B Algorithm for SCXML
Interpretation
This section presents a normative algorithm for the
interpretation of an SCXML document. Implementations are free to
implement SCXML interpreters in any way they choose, but they must
behave as if they were using the algorithm defined
here.
The fact that SCXML implements a variant of the Statechart
formalism does not as such determine a semantics for SCXML. Many
different Statechart variants have been proposed, each with its own
semantics. This section presents an informal semantics of SCXML
documents, as well as a normative algorithm for the interpretation
of SCXML documents.
Informal Semantics
The following definitions and highlevel principles and
constraint are intended to provide a background to the normative
algorithm, and to serve as a guide for the proper understanding of
it.
Preliminary definitions
- state
- An element of type <state>, <parallel>,
<final> or <scxml>.
- pseudo state
- An element of type <initial> or <history>.
- transition target
- A state, or an element of type <history>.
- atomic state
- A state of type <state> with no child states, or a state
of type <final>.
- compound state
- A state of type <state> with at least one child state, or
a state of type <scxml>.
- start state
- A dummy state equipped with a transition which when triggered
by the Run event leads to the initial state(s). Added by the
interpreter with an id guaranteed to be unique within the
statemachine. The only role of the start state is to
simplify the algorithm.
- configuration
- The maximal consistent set of states (including parallel and
final states) that the machine is currently in. We note that if a
state s is in the configuration c, it is always the
case that the parent of s (if any) is also in c. Note,
however, that <scxml> is not a(n explicit) member of the
configuration.
- source state
- The source state of a transition is the atomic state from which
the transition is leaving.
- target state
- A target state of a transition is a state that the transition
is entering. Note that a transition can have zero or more target
states.
- targetless transition
- A transition having zero target states.
- eventless transition
- A transition lacking the 'event' attribute.
- external event
- An SCXML event appearing in the external event queue. See
section ? for details.
- internal event
- An event appearing in the internal event queue. It's exact
representation is implementation dependent, but a simple string
would work.
- macrostep
- An external event causes an SCXML state machine to take exactly
one macrostep. A macrostep consists of a sequence (a chain) of
microsteps. However, if the external event does not enable any
transitions, no microstep will be taken, and the corresponding
macrostep will be empty.
- microstep
- If an external event enables one or (in the
case
of parallel states) more transitions, a microstep is taken,
involving the processing of each of the enabled transitions. This
microstep may change the the current configuration, update the
datamodel and/or generate new (internal and/or
external) events. This, by causality, may in turn enable additional
transitions which will be handled in the next microstep in the
sequence, and so on.
Principles and Constraints
We state here some principles and constraints, on the level of
semantics, that SCXML adheres to:
- Encapsulation
- An SCXML processor is a pure event processor . The
only way to get data into an SCXML statemachine is to send external
events to it. The only way to get data out is to receive events
from it.
- Causality
- There shall be a causal justification of why events
are (or are not) returned back to the environment, which can be
traced back to the events provided by the system environment.
- Determinism
- An SCXML statemachine which does not invoke any external event
processor must always react with the same behavior (i.e. the same
sequence of output events) to a given sequence of input events
(unless, of course, the statemachine is explicitly programmed to
exhibit an non-deterministic behavior). In particular, the
availability of the <parallel> element must not introduce any
non-determinism of the kind often associated with concurrency. Note
that observable determinism does not necessarily hold for state
machines that invoke other event processors.
- Completeness
- An SCXML interpreter must always treat an SCXML document as
completely specifying the behavior of a statemachine. In
particular, SCXML is designed to use priorities (based on document
order) to resolve situations which other statemachine frameworks
would allow to remain under-specified (and thus non-deterministic,
although in a different sense from the above).
- Run to completion
- SCXML adheres to a run to completion semantics in the sense
that an external event can only be processed when the processing of
the previous external event has completed, i.e. when all microsteps
(involving all triggered transitions) have been completely
taken.
- Termination
- A microstep always terminates. A macrostep may not. A macrostep
that does not terminate may be said to consist of an infinitely
long sequence of microsteps. This is currently allowed.
Algorithm
This section presents a normative algorithm for the
interpretation of SCXML documents. Implementations are free to
implement SCXML interpreters in any way they choose, but they must
behave as if they were using the algorithm defined here.
Note that the algorithm assumes a Lisp-like
semantics in which the empty Set null is equivalent to boolean
'false' and all other entities are equivalent to 'true'.
Datatypes
These are the abstract datatypes that are used in the
algorithm.
datatype List
function head() // Returns the head of the list
function tail() // Returns the tail of the list
function append(l) // Returns the list appended with l
filter(f) // Returns the list of elements that satisfy the predicate f
some(f) // Returns true if some element in the list satisfies the predicate f
every(f) // Returns true if every element in the list satisfies the predicate f
function filter(f) // Returns the list of elements that satify the predicate f
function some(f) // Returns true if some element in the list satifies the predicate f
function every(f) // Returns true if every element in the list satifies the predicate f
datatype Set
procedure add(e) // Adds e to the set
procedure delete(e) // Deletes e from the set
function member(e) // Is e a member of set?
function isEmpty() // Is the set empty?
function toList() // Converts the set to a list
function diff(set2) //Returns all members of Set that are not in set2
datatype Queue
procedure enqueue(e) // Puts e last in the queue
function dequeue() // Removes and returns first element in queue
function isEmpty() // Is the queue empty?
datatype BlockingQueue
procedure enqueue(e) // Puts e last in the queue
function dequeue() // Removes and returns first element in queue, blocks if queue is empty
Global
variables
The following variables are global from the point of view of the
algorithm. Their values will be set in the procedure
interpret() .
global datamodel;
global configuration;
global internalQueue;
global externalQueue;
global historyValue;
global continue
Procedures and Functions
This section defines the procedures and functions that make up
the core of the SCXML interpreter.
procedure
interpret(scxml,id)
The purpose of this procedure is to initialize the interpreter.
It is called with a parsed representation of an SCXML document.
In order to interpret an SCXML document, first perform inplace
expansions of states by including SCXML source referenced by
URIs urls
(see 3.11
3.13 Referencing External Files
) and change initial attributes to initial container children with
empty transitions to the state from the attribute. Then
(optionally) validate the resulting SCXML, and throw an exception
if validation fails. Create an empty configuration complete with a
new populated instance of the data model and a execute the global
scripts. Create the two queues to handle events and set the global
continue variable to true. Call executeTransitionContent on the
initial transition that is a child of scxml. Then call enterState
on the initial transition. Finally, start the interpreter's event
loop.
procedure interpret(doc):
expandScxmlSource(doc)
if (!valid(doc)) {fail with error}
configuration = new Set()
previousConfiguration = newSet()
datamodel = new Datamodel(doc)
executeGlobalScriptElements(doc)
internalQueue = new Queue()
externalQueue = new BlockingQueue()
continue = true
executeTransitionContent([doc.initial.transition])
enterState([doc.initial.transition])
startEventLoop()
procedure
startEventLoop()
The interpreter's event loop has two main
parts. First it selects enabled transitions. Then it executes
Upon entering the selected transitions. It stays in a continuous loop of
selecting state machine, we take all
internally enabled transitions, namely those that don't require an
event and executing transitions
until those that are triggered by
internal events. (Internal events can only be generated by
the interpreter is finished. The details of
how it selects state machine itself.)
When all such transitions are
specified have been taken, we
move to achieve the desired run to completion semantics and final
processing. main event loop, which is
driven by external events.
procedure procedure startEventLoop():
previousConfiguration = null;
initialStepComplete = false;
until(initialStepComplete):
enabledTransitions = selectTransitions(null)
if (enabledTransitions.isEmpty()):
internalEvent = internalQueue.dequeue()// this call returns immediately if no event is available
if (internalEvent):
datamodel.assignValue("event", internalEvent)
enabledTransitions = selectTransitions(internalEvent)
if (enabledTransitions):
microstep(enabledTransitions.toList()
else:
initialStepComplete = true
mainEventLoop()
procedure mainEventLoop()
The interpreter's event This loop enforces the
run runs until we enter a top-level
final state or an external entity cancels processing. In either
case 'continue' will be set to completion semantics false
(see EnterStates, below, for termination by only breaking at entering a
top-level final state.)
Each iteration through the
end of handling all loop consists of the
microsteps associated with three main
steps: 1) execute any given event. It
accomplishes this by each and every time <invoke> tags for atomic states that we entered on
the last iteration through the loop enforcing 2) Wait for
an ordering on which transitions are
selected. First the interpreter checks to see if there are
external event and then execute any
eventless transitions that need to be taken. If there are it triggers 3) Take any then
they subsequent internally enabled
transitions, namely those that don't require an event or that
are executed triggered by the microstep
being performed and the next iteration of the loop continues. If
there were no eventless transitions to execute then the internal
event queue is checked and if there is an internal
event then transitions are selected based on
this event. If there were transitions
selected based on this
This event then these are executed by the microstep being performed
and the next iteration of the loop continues. If there were no transitions enabled then we
check if we have reached a final state by checking if continue is
true. If continue is false the statemachine is done and we break
out of thus enforces run-to-completion
semantics, in which the startEventLoop.
If continue is true then we grab system
process an external event from
and then takes all the external event queue, blocking if necessary. Once we
have 'follow-up' transitions that
the processing has enabled before looking for
another external event we perform the
appropriate data model manipulation related to finalizing
event. For example, suppose that the
external event queue contains events e1 and e2 and modifying the data model with the event information. Finally we select transitions that
were enabled by this event. machine is
in state s1. If there were transitions
enabled by processing e1 takes
the machine to s2 and generates
internal event we execute them by the microstep function
e3, and start the
next iteration of s2 contains a
transition t triggered by e3, the loop.
If there were system is guaranteed to
take t, no matter what
transitions selected s2 or other states have that would be triggered by
e2. Note that this is true even though e2 was
already in the external event we also
start queue when e3 was generated. In
effect, the next iteration
algorithm treats the processing of
e3 as finishing up the loop. processing of
e1.
procedure startEventLoop():
while ():
enabledTransitions = selectTransitions(null)
(enabledTransitions.isEmpty() && !internalQueue.isEmpty()):
enabledTransitions = selectTransitions(internalQueue.dequeue())
(enabledTransitions.isEmpty()enabledTransitions.isEmpty() && !internalQueue.isEmpty():
(continue):
ee = externalQueue.dequeue()
datamodel.assignID("event",ee)
enabledTransitions = selectTransitions(ee)
:
(!enabledTransitions.isEmpty()):
procedure procedure mainEventLoop():
while(continue):
for state in configuration.diff(previousConfiguration): if(isAtomic(state)): if state.invoke:
state.invokeid = executeInvoke(state.invoke)
datamodel.assignValue(state.invoke.attribute('idlocation'),state.invokeid)
previousConfiguration = configuration
externalEvent = externalQueue.dequeue() // this call blocks until an event is available
datamodel.assignValue("event",externalEvent)
enabledTransitions = selectTransitions(externalEvent)
if (enabledTransitions):
microstep(enabledTransitions.toList())
// now take any newly enabled null transitions and any transitions triggered by internal events
macroStepComplete = false;
until(macroStepComplete):
enabledTransitions = selectEventlessTransitions()
if (enabledTransitions.isEmpty()):
internalEvent = internalQueue.dequeue()// this call returns immediately if no event is available
if (internalEvent):
datamodel.assignValue("event", internalEvent)
enabledTransitions = selectTransitions(internalEvent)
if (enabledTransitions):
microstep(enabledTransitions.toList()
else:
macroStepComplete = true
// if we get here, we have reached a top-level final state or some external entity has set continue to false
exitInterpreter()
procedure
exitInterpreter()
The purpose of this procedure is to exit the
current SCXML process by halting
exiting all active states. If the
interpreter's machine is in a top-level final state, a Done
event loop. It does so by setting the global
variable continue to is
generated.
procedure exitInterpreter():
inFinalState = false
statesToExit = new Set(configuration)
for s in statesToExit.toList().sort(exitOrder)
for content in s.onexit:
executeContent(content)
for inv in s.invoke:
cancelInvoke(inv)
if (isFinalState(s) && isScxmlState(s.parent())):
inFinalState = true
configuration.delete(s)
if (inFinalState):
sendDoneEvent(???)
false function. selectEventlessTransitions()
This will terminate function selects all transitions that are enabled
in the outer as well as
current configuration that do not require an
event trigger. First test if the inner
loop. Note, however, state has been
preempted by a transition that has already been selected and
that any current microstep will
first cause the
state to be completely
exited when the transition is taken.
If the state has not been preempted, 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 ancestory 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, return
the set of enabled transitions.
exitInterpreter():
continue =
function selectEventlessTransitions(event):
enabledTransitions = new Set()
atomicStates = configuration.toList().filter(isAtomicState)
for state in atomicStates:
if !(isPreempted(s, enabledTransitions)):
loop: for s in [state].append(getProperAncestors(state,null)):
for t in s.transition: if ( t.attribute('event') == null && conditionMatch(t))
enabledTransitions.add(t)
break loop return enabledTransitions
function
selectTransitions(event)
The purpose of the selectTransitions()
procedure is to collect the transitions that are
enabled by this event in a given the current
configuration.
Create an empty set of enabledTransitions . For
each atomic state in the configuration, first check if the event is the result of an <invoke> in
this state. If so, apply any <finalize> code in the state.
Next test if the state has been preempted by a transition
that has already been selected and that will cause the state to be
exited when the transition is taken. If the state has not been
preempted, find a transition whose 'event' attribute is either empty or matches event and
whose condition evaluates to true . (N.B. If event is null only transitions with empty event
attributes match it.) If multiple matching transitions are
present, take the first in document order. If none are present,
search in the state's ancestors in ancestory 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, return the set of enabled transitions.
function selectTransitions(event):
enabledTransitions = new Set()
atomicStates = configuration.toList().filter(isAtomicState)
for state in atomicStates:
if (event.attribute('invokeid') != null && state.invokeid = event.invokeid): //event is the result of an <invoke> in this state
applyFinalize(state, event)
if !(isPreempted(s, enabledTransitions)):
loop: for s in [state].append(getProperAncestors(state,null)):
for t in s.transition:
&& conditionMatch(t)) ||
(event != && nameMatch(event,t) && conditionMatch(t))):
if (t.attribute('event')!= null && isPrefix(t.attribute('event'), event.name) && conditionMatch(t)):
enabledTransitions.add(t)
break loop
return enabledTransitions
procedure functionisPreempted?(s isPreempted(s transitionList)
Return true if a transition T in transitionList exits an
ancestor of state s. In this case, taking T will pull the state
machine out of s and we say that it preempts the selection of a
transition from s. Such preemption will occur only if s is a
descendant of a parallel region and T exits that region. If we did
not do this preemption check, we could end up in an illegal
configuration, namely one in which there were multiple active
states that were not all descendants of a common parallel
ancestor.
isPreempted?(s transitionList):
boolean preempted = false
function isPreempted(s transitionList):
preempted = false
for t in transitionList:
if (t.attribute('target') != null):
LCA = findLCA([t.parent()].append(getTargetStates(t)))
if (isDescendant(s,LCA)):
preempted = true
break;
if (isDescendant(s,LCA)):
preempted = true
break
return preempted
procedure microstep(enabledTransitions)
The purpose of the microstep procedure is to
process the set of transitions enabled by an external event, an
internal event, or by the presence or absence of certain values in
the datamodel 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.
procedure microstep(enabledTransitions):
exitStates(enabledTransitions)
executeTransitionContent(enabledTransitions)
enterStates(enabledTransitions)
procedure exitStates(enabledTransitions)
Create an empty statesToExit set. For each
transition t in enabledTransitions , if
t is targetless then do nothing, else let
LCA be the least common ancestor state of the source
state and target states of t . Add to the
statesToExit set all states in the configuration that
are descendants of LCA . Convert the
statesToExit set 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 = new Set()
for t in enabledTransitions:
if (t.attribute('target') != null):
LCA = findLCA([t.parent()].append(getTargetStates(t)))
for s in configuration.toList():
if (isDescendant(s,LCA)):
statesToExit.add(s)
statesToExit = statesToExit.toList().sort(exitOrder)
for s in statesToExit:
for h in s.history:
f = (h.attribute('type') == "deep") ?
lambda(s0): isAtomicState(s0) && isDescendant(s0,s) :
lambda(s0): s0.parent() == s
historyValue[h.attribute('id')] = configuration.toList().filter(f)
for s in statesToExit:
for content in s.onexit:
executeContent(content)
for inv in s.invoke:
cancelInvoke(inv)
configuration.delete(s)
procedure
executeTransitionContent(enabledTransitions)
For each transition in the list of
enabledTransitions , execute its executable
content.
procedure executeTransitions(enabledTransitions):
for t in enabledTransitions:
executeContent(t)
procedure enterStates(enabledTransitions)
Create an empty statesToEnter set, and an empty
statesForDefaultEntry set. For each transition
t in enabledTransitions , if
t is targetless then do nothing, else let
LCA be the least common ancestor state of the source
state and target states of t . For each target state
s , if s is a history state then add
either the history values associated with s or
s 's default target to statesToEnter .
Else (if s is not a history state), add s
to statesToEnter . Convert statesToEnter
to a list and sort it in enterOrder enterorder
For each state s in the list, first add
s to the current configuration, then invoke any
external processes specified in <invoke> elements and assign
their sessionID sessionidID,
id, then execute any onentry handlers,
and finally, if s is a final state, generate relevant
Done events. If we have reached a top-level final
state, exit the interpreter.
procedure enterStates(enabledTransitions):
statesToEnter = new Set()
statesForDefaultEntry = new Set()
for t in enabledTransitions:
if (t.attribute('target') != null):
LCA = findLCA([t.parent()].append(getTargetStates(t)))
for s in getTargetStates(t):
if (isHistoryState(s)):
if (historyValue[s.attribute('id')] != null):
for s0 in historyValue[s.attribute('id')]:
addStatesToEnter(s0,LCA,statesToEnter,statesForDefaultEntry)
else:
for s0 in getTargetStates(s.transition):
addStatesToEnter(s0,LCA,statesToEnter,statesForDefaultEntry)
else:
addStatesToEnter(s,LCA,statesToEnter,statesForDefaultEntry)
statesToEnte ):
r = statesToEnter.toList().sort(enterOrder)
statesToEnter = statesToEnter.toList().sort(enterOrder)
for s in statesToEnter:
configuration.add(s)
s.invoke:
sessionID = executeInvoke(inv)
datamodel.assignValue(inv.attribute('ID'),sessionID)
for content in s.onentry:
executeContent(content)
if (statesForDefaultEntry.member(s)):
executeContent(s.initial.transition.children())
if (isFinalState(s)):
parent = s.parent()
grandparent = parent.parent()
internalQueue.enqueue(parent.attribute('id') + ".Done")
if (isParallelState(grandparent)):
if (getChildStates(grandparent).every(isInFinalState)):
internalQueue.enqueue(grandparent.attribute('id') + ".Done")
for s in configuration.toList():
if (isFinalState(s) && isScxmlState(s.parent())):
exitInterpreter()
continue = false;
procedure
addStatesToEnter(s,root,statesToEnter,statesForDefaultEntry)
The purpose of this procedure is to add to
statesToEnter all states that must be entered as a
result of entering state s . These include ancestors
of s , parallel siblings of s or its
ancestors, and s 's default children, if
s is a parallel or compound state. Note that this
procedure permanently modifies both
statesToEnter and statesForDefaultEntry
.
First, add s to statesToEnter . Then,
if s is a parallel state, add each of s
's children to statesToEnter . Else, if s
is a compound state, add s to
statesForDefaultEntry and add its default initial
state to statesToEnter . Finally, for each ancestor
anc of s , add anc to
statesToEnter and if anc is a parallel
state, add the children of anc that does not have a
descendant on statesToEnter to
statesToEnter .
procedure addStatesToEnter(s,root,statesToEnter,statesForDefaultEntry):
statesToEnter.add(s)
if (isParallelState(s)):
for child in getChildStates(s):
addStatesToEnter(child,s,statesToEnter,statesForDefaultEntry)
elif (isCompoundState(s)):
statesForDefaultEntry.add(s)
addStatesToEnter(getDefaultInitialState(s),s,statesToEnter,statesForDefaultEntry)
for anc in getProperAncestors(s,root):
statesToEnter.add(anc)
if (isParallelState(anc)):
for pChild in getChildStates(anc):
if (!statesToEnter.toList().some(lambda(s): isDescendant(s,anc))):
addStatesToEnter(pChild,anc,statesToEnter,statesForDefaultEntry)
procedure
isInFinalState(s)
Return true if state s is a compound
<state> and one of its children is a <final> state and
is a member of the 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) && configuration.member(s))
elif (isParallelState(s)):
return getChildStates(s).every(isInFinalState)
else:
return false
function
findLCA(stateList)
Return the state 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 a state since the <scxml> element
(which we treat as a state here) 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 LCA is never a member of
stateList .
function findLCA(stateList):
for anc in getProperAncestors(stateList.head(),null):
if (stateList.tail().every(lambda(s): isDescendant(s,anc))):
return anc
B.1
Semantics of <anchor>
There are a number of ways of defining the semantics of
<anchor>. We choose the following because it shows that,
except for the rollback of the data model, <anchor> can be
viewed as a syntactic shortcut that does not extend the basic Harel
semantics. We emphasize that implementations are required only to
behave as if they assigned the following interpretation to
<anchor> and that simpler and more efficient implementations
are possible.
First, we add a special branch 'anchors' to the data model, with
a child for each anchor type defined in the document. Thus if the
document defines anchor types "foo" and "bar", the data model will
have paths 'anchors.foo' and 'anchors.bar'. Whenever the state
machine enters a state with an <anchor> element, it sets the
value of the corresponding anchor entry in the datamodel to the
ID id of
that state. Thus if a <state> with ID id 'state27'
defines an <anchor> with 'type' "foo", whenever the state
machine visits this state, it sets 'anchors.foo; to 'state27'.
Furthermore, the state machine automatically adds the 'anchors'
branch to the snapshot specified in the <anchor> element.
Now any <transition> which specifies an 'anchor' is
replaced with a set of <transition>s, one for each
<state> that defines that <anchor>. Each of the
<transition>s takes as its 'target' one of the <state>s
that defines the <anchor>. Furthermore, an extra clause is
added to the 'cond' of the original <transition>, specifying
that the corresponding location in the data model match the target
<state>'s ID. id. Finally, a default transition is added
reentering the current <state>. For example, if the anchor
type "foo" is defined in <state>s 'state27' and 'state33',
then in <state> 'thisState', a transition with "event"
"someEvent", "cond" "someCond" and "anchor" 'foo' will be replaced
by three transitions, as shown below:
<transition event="someEvent" cond="someCond" anchor="foo"/>
is equivalent to
<transition event="someEvent" cond="datamodel.anchors.foo==state27 && someCond" target="state27"/>
<transition event="someEvent" cond="datamodel.anchors.foo==state33 && someCond" target="state33"/>
<transition event="someEvent" cond="someCond" target="state33"/> target="thisState"/>
At runtime when "someEvent" is raised and "someCond" is true, if
either state27 or state33 has been visited, 'datamodel.anchors.foo'
will have the corresponding stateID
stateid as its value and the
corresponding transition will be selected. The only complication is
that the transitions must retain the original 'anchor' attribute,
so that the datamodel must be rolled back to the snapshot specified
in the corresponding <anchor> element. Note that the
'anchors' branch must be automatically added to this snapshot, so
that it will be automatically rolled back as well. (This has the
effect of erasing any intermediate anchors that have been visited
since the target state was exited.) If neither state27 nor state33
has been visited, the third transition will be taken, causing the
state machine to exit and reenter 'thisState' without any rollback
of the datamodel.
G
SCXML Event I/O Processor
The SCXML Event I/O Processor is intended
to transport messages in a specific format to and from SCXML
sessions. This processor specifies the schema of the messages and
how they map onto SCXML events, but it does not define the
transport mechanism, which is platform-specific. The schema for the
message is available at D.10 SCXML Message
Schema :.The sender or the
receiver of the message may be either an SCXML session or an
external entity, but this specification defines the behavior for
SCXML sessions only .
The contents of the individual messages
are defined as follows:
- The value of the 'name' attribute is
taken from the 'event' attribute of the <send> element. It is
then used as value the 'name' field in the event that is generated
by the receiving processor (see 5.6.1 The
Internal Structure of Events ).
This field is what is matched against the 'event' attribute of
<transition>.
- The value of the 'source' attribute is a
URI that the receiving processor can use to reply to the sending
processor. It is used as the value of the 'origin' field in the
event that is generated by the receiving side (see 5.6.1 The
Internal Structure of Events ).
In profiles supporting the Data Module, the access URI is available
in the sending session via the system variable _ioprocessors using
the key "basichttp".
- The 'target' attribute contains an
identifier of SCXML session to which the message should be
delivered. It is taken from the 'target' attribute of the
<send> element. In general, the format of the identifier is
platform-specific. However there are two distinguished values. If
the value of the 'target' attribute in the <send> element is
'_internal', the receiving session will be identical to the sending
session, and it will populate the 'type' field of the resulting
event with "internal" and will add the event to its internal event
queue. If the 'target' attribute is not specified, the receiving
session will be identical to the sending session, and it will
populate the 'type' field of the resulting event with "external"
and will add the event to its external event queue. If the value of
the 'target' attribute is anything else, the receiving processor
will set the type field of the resulting event to "external" and
will add the event to its external event queue.
- The 'sendid' attribute is populated with
the identifier specified in the 'id' attribute or automatically
generated by the platform when the <send> tag executed in the
sending SCXML session. (See 4.1 <send> .)It will be used as the value of the 'sendid' field in
the event that is generated by the receiving processor. If the
author of the sending session did not specify either the 'id' or
'idlocation' attribute, this attribute will be empty.
- The 'sourcetype' attribute contains an
indication of the type of process that generated the message. It
will be used to populate the 'origintype' field of the event that
is generated by the receiving processor. If the sender is an SCXML
processor, the value will be "scxml".
- The 'language' attribute is used to
indicate the type of data contained in the body of the message
inside the <payload> element. The receiving process can use
this information to parse and validate the message.
- The <payload> element contains any
data that is associated with the message. It will be encoded in the
language indicated by the 'language' attribute, for example XML or
JSON. This data may be in any namespace, or in no namespace at all,
but it may also contain <scxml:hint> and
<scxml:property> elements that provide additional information
about the data.
The mapping between <send>, the
SCXML message structure, and the event that is raised in the
receiving session is given below.
| <send>
element |
SCXML Message
Structure |
Target Session
Event |
| 'event' attribute |
'name' attribute |
'name' field |
| not present in <send>
but known to platform |
'source'
attribute |
'origin' field |
| 'target'
attribute |
'target'
attribute |
not present |
| literal provided by author
or value generated by platform |
'sendid'
attribute |
'sendid' field |
| not present |
'sourcetype' attribute.
Always "scxml". |
'origintype' field. Always
"scxml". |
| not present |
'language'
attribute. |
not present |
| 'namelist' attribute,
<content> child, or <param> children |
<payload>
element |
data field |
The sending SCXML Event I/O
processor MUST populate these fields of the SCXML message structure in
the manner defined above, and the receiving processor
MUST use them to create
the appropriate internal or external event structure as defined
above.
When an SCXML processor receives a message
via the SCXML Event I/O Processor it validates the syntax of the
incoming message and checks that it matches an active session. If
the message fails syntactic validation or does not match an active
session, the receiving processor notifies the sending processor of
the error and ignores the message. If the message passes
validation, but the receiving processor cannot handle the data
format contained in the message, the receiving processor
SHOULD raise the error:
error.receive.datamismatch in the session for which the message was
intended and SHOULD also notify the sending processor of the error. It then
ignores the message. If no errors occur, the receiving session
converts the message into an SCXML event, using the mapping defined
above, and inserts the event its external event queue.
If the sending entity is an SCXML session,
it SHOULD also report errors. If the sending session specifies a
sessionid that does not exist on the receiving system, it
SHOULD raise the error:
error.send.nosuchsession. If the sending session specifies a data
format that the receiving session does not support, it
SHOULD raise the error:
error.send.datamismatch. For any other errors, such as inability to
connect to the receiving system, the sending system
SHOULD raise
error.send.failed.scxmlio. An implementation may extend any of the
errors described in this section to provide more information if it
desires. For example, an implmentation may choose to raise
error.send.failed.scxmlio.cannotconnect or
error.receive.datamismatch.ecmascript, etc.
The SCXML Event I/O Processor
MUST handle the
'cancel.invoke. invokeid
' event. In particular, if SCXML session
session1 sends this event to session session2, where session1
invoked session2 via an <invoke> element with invokeid
invokeid ,the SCXML Event I/O Processor MUST set the 'continue'
variable in session2 to 'false' and discard the event. (See
B Algorithm for SCXML Interpretation
for details.) In all other cases (that is, in
cases where the invokeid does not match), the SCXML Event I/O
processor MUST discard the event and SHOULD signal an
error.
G.1
Examples
Here are some examples of SCXML messages
sent between SCXML sessions. Each example shows the original
<send> element, the corresponding <message> structures
and a transition handling the resulting event in the receiving
SCXML session.
EXAMPLE 1: First, here is a message with an XML payload generated
by <send> with a 'namelist':
SESSION1 : SENDING SESSION
Pattern: "event" attribute with an optional "namelist"
<datamodel>
<data id="email" expr="'mailto:recipient@example.com'"/>
<data id="content" expr="'http://www.example.com/mycontent.txt'"/>
<data id="xmlcontent">
<headers xmlns="http://www.example.com/headers">
<cc>archive@example.com</cc>
<subject>Example email</subject>
</headers>
</data>
</datamodel>
...
<send id="send-123"
target="'http://scxml-processors.example.com/session2'"
type="'scxml'" event="'email.send'"
namelist="email content xmlcontent"
hints="'Email headers'"/>
Here is the actual XML message that will
be sent over platform-specific transport and converted into an
event in the target SCXML session:
<scxml:message xmlns:scxml="http://www.w3.org/2005/07/scxml" version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2005/07/scxml scxml-message.xsd"
source="http://scxml-processors.example.com/session1" sourcetype="scxml"
target="http://scxml-processors.example.com/session2" type="scxml"
sendid="send-123" name="email.send">
<scxml:payload>
<scxml:property name="email">mailto:recipient@example.com</scxml:property>
<scxml:property name="content">http://www.example.com/mycontent.txt</scxml:property>
<scxml:property name="xmlcontent">
<scxml:hint>Email headers</scxml:hint>
<headers xmlns="http://www.example.com/headers">
<cc>archive@example.com</cc>
<subject>Example email</subject>
</headers>
</scxml:property>
</scxml:payload>
</scxml:message>
Here is sample SCXML code to process that
event in the receiving SCXML session. In this example
<my:email> is platform-specific executable content that sends
an email:
SESSION2 : RECEIVING SESSION
Pattern: "event" attribute with an optional "namelist"
<scxml:transition event="email.send">
<my:email to="data('_event')/scxml:property[@name='email']"
cc="data('_event')/scxml:property[@name='xmlcontent']/h:headers/h:cc"
subject="data('_event')/scxml:property[@name='xmlcontent']/h:headers/h:subject"
content="data('_event')/scxml:property[@name='content']"/>
</scxml:transition>
EXAMPLE 2: The next example shows <send> using inline XML
content:
SESSION1 : SENDING SESSION
Pattern: "xmlns" attribute with explicit inline content
<send id="send-123"
target="'http://scxml-processors.example.com/session2'"
type="'scxml'"
xmlns:csta="http://www.ecma.ch/standards/ecma-323/csta">
<csta:MakeCall>
<csta:callingDevice>22343</callingDevice>
<csta:calledDirectoryNumber>18005551212</csta:calledDirectoryNumber>
</csta:MakeCall>
</send>
Here is the actual XML message that will
be sent:
<scxml:message xmlns:scxml="http://www.w3.org/2005/07/scxml" version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2005/07/scxml scxml-message.xsd"
source="http://scxml-processors.example.com/session1"
target="http://scxml-processors.example.com/session2"
sendid="send-123">
<scxml:payload xmlns:csta="http://www.ecma.ch/standards/ecma-323/csta">
<csta:MakeCall>
<csta:callingDevice>22343</csta:callingDevice>
<csta:calledDirectoryNumber>18005551212</csta:calledDirectoryNumber>
</csta:MakeCall>
</scxml:payload>
</scxml:message>
Here is sample SCXML code to process the
resulting event in the receiving SCXML session. It uses the special
executable content <csta:makecall> to generate a telephone
call:
SESSION2 : RECEIVING SESSION
Pattern: "xmlns" attribute with explicit inline content
<scxml:transition event="external.event">
<csta:makecall callingDevice="data('_event')/csta:MakeCall/csta:callingDevice"
callingDirectoryNumber="data('_event')/csta:MakeCall/csta:callingDirectoryNumber"/>
</scxml:transition>
EXAMPLE 3: Finally, here is an example generated by <send>
using both 'event' and'namelist' attributes and using JSON
content:
SESSION1 : SENDING SESSION
Pattern: "event" attribute with an optional "namelist"
<datamodel>
<data id="email" expr="'mailto:recipient@example.com'"/>
<data id="content" expr="'http://www.example.com/mycontent.txt'"/>
<data id="jsoncontent" src="http://www.example.com/headers.json"/>
</datamodel>
...
<send sendid="send-123"
target="'http://scxml-processors.example.com/session2'"
type="'scxml'" event="'email.send'"
namelist="email content jsoncontent"
hints="'Email headers'"/>
Here is the actual XML message that will
be sent over platform-specific transport and converted into an
event in the target SCXML session:
<scxml:message xmlns:scxml="http://www.w3.org/2005/07/scxml" version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2005/07/scxml scxml-message.xsd"
source="http://scxml-processors.example.com/session1"
target="http://scxml-processors.example.com/session2"
sendid="send-123" name="email.send" language="json">
<scxml:payload>
<scxml:property name="email">mailto:recipient@example.com</scxml:property>
<scxml:property name="content">http://www.example.com/mycontent.txt</scxml:property>
<scxml:property name="jsoncontent">
<scxml:hint>Email headers</scxml:hint>
<![CDATA[
headers : {
cc : "audit@example.com" ,
subject : "Example email"
}
]]>
</scxml:property>
</scxml:payload>
</scxml:message>
Here is sample SCXML code to process the
resulting event in the receiving SCXML session. In this example,
<my:email> is special executable content as in the first
example.
SESSION2 : RECEIVING SESSION
Pattern: "event" attribute with an optional "namelist"
<scxml:transition event="email.send">
<my:email to="_event.email"
cc="_event.jsoncontent.headers.cc"
subject="_event.jsoncontent.headers.subject"
content="_event.content"/>
</scxml:transition>
In some cases it may be convenient to
included multiple <message> structures in a single payload.
The following schema defines a <messages> element which
contains multiple <message> elements. Support for this schema
is optional.
scxml-messages.xsd
<?xml version="1.0" encoding="UTF-8"?>
<!--
XML Schema for sending messages to SCXML processors.
-->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:scxml="http://www.w3.org/2005/07/scxml"
targetNamespace="http://www.w3.org/2005/07/scxml"
elementFormDefault="qualified">
<xsd:include schemalocation="scxml-message.xsd"/>
<xsd:annotation>
<xsd:documentation xml:lang="en">
XML Schema for sending messages to SCXML processors.
Version 1.0
</xsd:documentation>
<xsd:documentation source="scxml-copyright.xsd" />
</xsd:annotation>
<xsd:attributeGroup name="scxmlmessages.extra.attribs">
<xsd:annotation>
<xsd:documentation>
Group allowing attributes from other namespaces
</xsd:documentation>
</xsd:annotation>
<xsd:anyAttribute namespace="##other" processContents="lax" />
</xsd:attributeGroup>
<xsd:attributeGroup name="scxmlmessages.messages.attlist">
<xsd:attribute name="version" type="xsd:string" fixed="1.0"
use="required" />
<xsd:attributeGroup ref="scxml:scxmlmessages.extra.attribs" />
</xsd:attributeGroup>
<xsd:group name="scxmlmessages.messages.content">
<xsd:sequence>
<xsd:element ref="scxml:message" minOccurs="1"
maxOccurs="unbounded" />
</xsd:sequence>
</xsd:group>
<xsd:complexType name="scxmlmessages.messages.type">
<xsd:group ref="scxml:scxmlmessages.messages.content" />
<xsd:attributeGroup ref="scxml:scxmlmessages.messages.attlist" />
</xsd:complexType>
<xsd:element name="messages" type="scxml:scxmlmessages.messages.type" />
</xsd:schema>
