1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
# uSCXML ReadMe
[](https://travis-ci.org/sradomski/uscxml)
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
- [General](#general)
- [Test Reports](#test-reports)
- [License](#license)
- [Download](#download)
- [Usage](#usage)
- [Advanced Topics](#advanced-topics)
- [Embedding uSCXML](#embedding-uscxml)
- [Extending uSCXML](#extending-uscxml)
- [Acknowledgments](#acknowledgments)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## General
uSCXML is a SCXML interpreter written in C/C++. It is [standards compliant](#test-reports) and [easily extended](#extending-uscxml)
even in C# and Java. It runs on <b>Linux</b>, <b>Windows</b> and <b>Mac OSX</b>, each 32- as well as 64Bits as well as <b>iOS</b>.
* <b>Datamodels</b>
* Full [ECMAScript datamodel](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/ecmascript) using Google's v8 (and JavaScriptCore on MacOSX and iOS)
* Simplified support for [Web Storage](http://www.w3.org/TR/2013/REC-webstorage-20130730/) in document.localStorage
* Support for binary data via [TypedArrays](https://www.khronos.org/registry/typedarray/specs/latest/) (will not throw exceptions yet)
* Full [NULL datamodel](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/null) with required <tt>In</tt> predicate
* [Prolog datamodel](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/prolog/swi) using SWI prolog
* Experimental [Promela datamodel](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/promela) for use
with the [SPIN](http://spinroot.com/spin/whatispin.html) model-checker
* Early support for a [Lua datamodel](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/lua)
* Rudimentary support for [XPath datamodel](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/xpath)
* <b>Invokers</b>
* <tt>scxml</tt>: Invoke a nested scxml interpreter
* <tt>dirmon</tt>: Watches a directory for changes to files
* <tt>scenegraph</tt>: Simplified 3D scenegraphs with custom markup
* <tt>heartbeat</tt>: Periodically sends events
* <tt>umundo</tt>: Subscribe to channels and publish events
* [Many others](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/invoker)
* <b>DOM</b>
* DOM Core Level 2 + XPath extensions available for ecmascript datamodel
* Namespace aware to embed custom markup for special invokers
* <b>Communication</b>
* Features the standard basichttp io-processor
* Features the required SCXML io-processor
* <b>No</b> DOM io-processor
* Early support for [WebSockets](http://datatracker.ietf.org/doc/rfc6455/)
* Can actually respond to HTTP requests with data via <response>
* <b>Language Bindings</b>
* PHP module for apache and cli interpreter
* Java bindings
### Test Reports
* We continuously run the [W3C IRP tests](http://www.w3.org/Voice/2013/scxml-irp/) for SCXML.
* Have a look at the [result](http://uscxml.tk.informatik.tu-darmstadt.de/cdash/index.php?project=uscxml) for the various platforms.
* The manual and XPath specific tests are [excluded](https://github.com/tklab-tud/uscxml/blob/master/contrib/ctest/CTestCustom.ctest.in).
uSCXML still fails the following ecmascript tests:
<table>
<tr><th>Test#</th><th>Status</th><th>Description</th><th>Comment</th></tr>
<tr>
<td>
<tt>
<a href="https://github.com/tklab-tud/uscxml/blob/master/test/w3c/ecma/test326.scxml">326</a> /
<a href="https://github.com/tklab-tud/uscxml/blob/master/test/w3c/ecma/test326.scxml">329</a>
</tt>
</td>
<td><tt>Fail for v8</tt></td>
<td>"test that _ioprocessors stays bound till the session ends" / "test that none of the system variables can be modified"</td>
<td>The v8 implementation will return a new <tt>_ioprocessor</tt> object for each access.</td>
</tr>
<tr>
<td><tt><a href="https://github.com/tklab-tud/uscxml/blob/master/test/w3c/ecma/test579.scxml">579</a></tt></td>
<td><tt>Failed</tt></td>
<td>"Before the parent state has been visited for the first time, if a transition is executed that takes the history state as its target, the SCXML processor MUST execute any executable content in the transition after the parent state's onentry content and any content in a possible initial transition."</td>
<td>Functionality was recently added and is not yet supported.</td>
</tr>
</table>
### License
uSCXML itself is distributed under the Simplified BSD license as in, do not sue us and do
not misrepresent authorship. Please have a look at the licenses of the [libraries we depend
upon](https://github.com/tklab-tud/uscxml/blob/master/docs/BUILDING.md#build-dependencies) as well.
### Download
We do not yet feature installers. Please download the source and have a look at the [build
instructions](https://github.com/tklab-tud/uscxml/blob/master/docs/BUILDING.md).
## Usage
In order to use the interpreter, you need to <tt>#include "uscxml/Interpreter.h"</tt> and instantiate
objects of <tt>uscxml::Interpreter</tt>.
### Non-Blocking Interpretation with SCXML from URL
Interpreter scxml = Interpreter::fromURL("http://www.example.com/fancy.scxml");
scxml.start(); // non-blocking in own thread
There are some cases, i.e. with graphical invokers, where the main thread is <emph>required</emph> in order
to react to UI events. You will have to deligate control flow from the main thread into the interpreter
every now and then:
interpreter.runOnMainThread(25);
This will perform a single iteration on the invoked components with a maximum of 25 frames per seconds
or return immediately. You will have to call this method every now and then if you are using e.g. the
<tt>scenegraph</tt> invoker.
### Blocking Interpretation with inline SCXML
Interpreter scxml = Interpreter::fromXML("<scxml><final id="exit"/></scxml>");
scxml.interpret(); // blocking
When using blocking interpretation, it is assumed that it is running on the main thread and
it will call <tt>runOnMainThread</tt> between stable configurations.
### Interleaved Interpretation with inline SCXML
Interpreter scxml = Interpreter::fromXML("<scxml><final id="exit"/></scxml>");
InterpreterState state;
do {
state = interpreter.step(true); // boolean argument causes blocking or not
} while(state > 0)
Using <tt>step</tt>, you can run a single macrostep of the interpreter and interleave
interpretation with the rest of your code.
### Callbacks for an Interpreter
You can register an <tt>InterpreterMonitor</tt> prior to start in order to receive
control-flow upon various events in the Interpreter.
class StatusMonitor : public uscxml::InterpreterMonitor {
void onStableConfiguration(...)
void beforeCompletion(...)
void afterCompletion(...)
void beforeMicroStep(...)
void beforeTakingTransitions(...)
void beforeEnteringStates(...)
void afterEnteringStates(...)
void beforeExitingStates(...)
void afterExitingStates(...)
};
StatusMonitor statMon;
Interpreter scxml = Interpreter::fromXML("<scxml><final id="exit"/></scxml>");
scxml.addMonitor(&statMon);
scxml.start();
This will cause the interpreter to invoke the callbacks from the monitor whenever the corresponding
internal phase is reached.
## Advanced Topics
### Embedding uSCXML
There are bindings for [Java](https://github.com/tklab-tud/uscxml/tree/master/embedding/java) and
[C#](https://github.com/tklab-tud/uscxml/tree/master/embedding/csharp) with some examples in the
<tt>embedding</tt> directory. The bindings consist of two parts each
1. The C++ uscxml interpreter compiled as a loadable module for the target language and
2. A target language specific module (uscxml.jar / uscxmlCSharp.dll) with the wrapper classes.
The first one is loaded by the target language (System.loadLibrary / SetDLLDirectory) while the second is to be
included in your actual project. Have a look at the examples in <tt>embedding</tt> and adapt the paths to reflect
your setup. See the [build instructions](https://github.com/tklab-tud/uscxml/blob/master/docs/BUILDING.md) for
details on how to build these.
### Extending uSCXML
The uSCXML interpreter can be extended by introducing new
1. DataModels as embedded scripting languages (e.g. ECMAScript, Prolog and XPath)
2. Invokers to represent external components that deliver and accept events (e.g. iCal, SceneGraph, DirectoryMonitor)
3. I/O-Processors to provide communication with external systems (e.g. BasicHTTP, SCXML).
4. Elements for Executable Content (e.g. <respond>, <fetch>, <postpone>).
The basic approach to extend the interpreter is the same in all cases:
1. Write a class inheriting the abstract base class (e.g. <tt>DataModelImpl</tt>, <tt>InvokerImpl</tt>, <tt>IOProcessorImpl</tt>, <tt>ExecutableContentImpl</tt>).
2. Instantiate your class and register it as a prototype at the <tt>Factory</tt> via one of its static <tt>register*</tt> methods.
1. You can register at the global Factory Singleton via <tt>Factory::register*(prototypeInstance)</tt>
2. Or provide a new Factory instance to selected interpreters as an in-between.
3. Write an interpreter using your new functionality.
<b>Note:</b> Within the language bindings, you will have to inherit the base classes without the <tt>Impl</tt>
suffix. Have a look at the examples in <tt>embedding/<tt> for examples.
#### Ad-hoc Extensions
Sometimes, it is more suited to provide an interpreter with an already instantiated extension (e.g. an
IOProcessor with an existing connection). In this case, it is somewhat awkward to register a prototype and
have all initialization in its <tt>create(Interpreter interpreter)</tt> method. While you can still dispatch
over the interpreter instance and access information from some global Interpreter->Data map, there is a
more straight-forward approach, e.g. in Java:
Interpreter interpreter = Intepreter.fromURI(uri);
AdhocIOProcessor ioProc = new AdhocIOProcessor(Whatever youLike);
ioProc.setParameter1(something);
interpreter.addIOProcessor(ioProc);
This will cause the interpreter to use the given instance for all send requests targeting one of the types
returned by <tt>ioProc.getNames()</tt> and not instantiate an instance via the factory. The instance can
deliver events into the interpreter via <tt>returnEvent(Event e, boolean toExternalQueue)</tt>. The same
approach can be used for invokers:
Interpreter interpreter = Intepreter.fromURI(uri);
TestAdhocInvoker invoker1 = new TestAdhocInvoker(Whatever youLike);
invoker1.setParameter1(something);
interpreter.setInvoker("invokeId", invoker1);
This will cause the interpreter to use the given instance for a given <tt>invokeId</tt> and not instantiate via
the factory. Similarly, datamodels can be registered via <tt>interpreter.setDataModel(DataModel dm)</tt>.
<b>Note:</b> Providing ad-hoc extensions is only supported before the interpreter is started. If you change
instances with a running interpreter, the behavior is undefined.
# Acknowledgments
This SCXML interpreter is developed at the [Telekooperation Group](http://www.tk.informatik.tu-darmstadt.de) of the Technical University of Darmstadt as part of the [SmartVortex](http://smartvortex.eu) project funded by the [7th European framework program](http://ec.europa.eu/research/fp7/index_en.cfm).
|
