Updated documentation

4 files changed, 135 insertions, 1 deletions

diff --git a/README.md b/README.md
index 76a4eff..a5920f7 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,7 @@
 - [Advanced Topics](#advanced-topics)
     - [Embedding uSCXML](#embedding-uscxml)
     - [Extending uSCXML](#extending-uscxml)
+- [Miscellaneous](#miscellaneous)
 - [Acknowledgments](#acknowledgments)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -188,7 +189,7 @@ The basic approach to extend the interpreter is the same in all cases:
 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.
+suffix. Have a look at the examples in <tt>embedding</tt> for examples.
 
 #### Ad-hoc Extensions
 
@@ -219,6 +220,69 @@ the factory. Similarly, datamodels can be registered via <tt>interpreter.setData
 <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.
 
+# Miscellaneous 
+
+## Ad-hoc extensions are deallocated by their interpreter
+
+If you register any ad-hoc extension with an interpreter, be it in C++ or a language binding, this extension's
+instance <emph>belongs</emph> to the interpreter. This means i.e. that (i) the interpreter's destructor will
+deallocate the extension instance, (ii) you cannot reuse it for another interpreter and (iii) you may not call
+its destructor.
+
+For the language bindings, this means furthermore that you have to call <tt>swigReleaseOwnership()</tt> on the
+extension instance to prevent the target language's memory managment form calling the instances C++ native
+destructor. The destructor can only be called once and the interpreter's destructor will do it.
+
+If allocating additional extension instances per interpreter is expensive, consider using aggregation as a "has a"
+relationship with the expensive part.
+
+## Not all exceptions are propagated into the target languages
+
+Only exceptions raised during the following methods are propagated into the target language:
+
+    Interpreter::fromXML
+    Interpreter::fromURI
+    Interpreter::step
+    Interpreter::interpret
+
+If you dig around in the exposed APIs, there are other methods that may raise exceptions (e.g.
+<tt>interpreter.getDataModel().eval()</tt>). Be careful when calling these. Ultimately, all exceptions ought to be
+propagated into the target language to be handled accordingly. We are currently evaluating different approaches to
+do so.
+
+## Where is the Android Port?
+
+When I originally tried to compile the required libraries for uSCXML on Android (libevent, curl, libxml2), it would
+not work out of the box and I postponed. If there is a demand for an Android port, I can have another look. uSCXML
+itself is written in a subset of C++99 and ought to compile just fine.
+
+## UTF8 support
+
+Currently, we use <tt>std::string</tt> to represent all strings. This is not a problem as e.g. the ECMAScript
+datamodels will just interpret these as character arrays and handle Unicode respectively. Though it is a problem if
+you like to use non-ASCII characters e.g. in the <tt>id</tt> attribute of states.
+
+## Performance
+
+The performance of uSCXML depends on many things like the employed datamodel and the platform it runs on. Using a
+MacBook Pro with an Intel i7 @2.4Ghz and the ECMAScript datamodel (<tt>test/uscxml/test-performance.scxml</tt>), we
+achieve about 20.000 events/sec. On a Raspberry Pi, however, only 350 events/sec are achieved.
+
+If performance ought to be increased further, the first place to look would be most likely the employed DOM
+implementation, which uses the rather expensive <tt>dynamic_cast</tt> somewhat too liberally. For a real
+performance boost, the explicit SCXML DOM representation at runtime might be dropped in favor of some simple
+structs representing the states and transitions. This has been no priority for us so far as even 350 events/sec is
+plenty for our use-cases.
+
+## What about some code documentation?
+
+Up until recently, the APIs of uSCXML were still subject to rather substantial changes. If there is one thing worse
+than no documentation, it is wrong documentation, so we did not document the source. Another stumbling block was the
+fact that documentation would not show up in the language bindings.
+
+Both issues are resolved by now: The APIs have not changed substantially in about 8 month and the new version of SWIG
+will allow doxygen comments to be show up in various target languages; so we will document somewhen soon.
+
 # 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).
\ No newline at end of file
diff --git a/docs/BUILDING.md b/docs/BUILDING.md
index 4a16aad..d31b28e 100644
--- a/docs/BUILDING.md
+++ b/docs/BUILDING.md
@@ -11,6 +11,7 @@
     - [Linux](#linux)
     - [Windows](#windows)
     - [iOS](#ios)
+    - [Raspberry Pi](#raspberry-pi)
 - [Language Bindings](#language-bindings)
     - [Java](#java)
     - [CSharp](#csharp)
@@ -318,6 +319,38 @@ If you just want a specific configuration for e.g. the simulator, you can invoke
 <b>Note</b>: We did not compile the prebuilts for iOS with 64Bit yet. As such, you will not get binaries build for
 arm64. The main culprit is, again, curl which assumes the size of an int to be the identical.
 
+## Raspberry Pi
+
+To compile uSCXML on Raspberry Pi you will need to, at a minimum, install the following packages. This assumes that
+you run Raspberry, the Debian variant.
+
+	$ sudo apt-get install cmake libxml2-dev libcurl4-gnutls-dev
+
+Now you can compile uSCXML like on any other platform:
+
+	$ git clone --depth 1 https://github.com/tklab-tud/uscxml.git
+	$ mkdir -p uscxml/build/raspberry && cd uscxml/build/raspberry
+	$ cmake ../..
+	$ make
+
+If you want an ECMAScript datamodel or LUA, you will need to install additional packages:
+
+	# additional datamodels: ECMAScript, LUA, Prolog
+	$ sudo apt-get install libjavascriptcoregtk-3.0-dev liblua5.2-dev swi-prolog-nox   
+
+	# additional invokers
+	$ sudo apt-get install libical-dev libpurple-dev libopenal-dev libsndfile1-dev libopenscenegraph-dev
+
+Lastly, to get the language bindings install SWIG and the developer kits of the respective language. Older Java
+versions will work as well (>= 1.5), just make sure <tt>JAVA_HOME</tt> is set correctly.
+
+	# language bindings: Java, CSharp
+	$ sudo apt-get install swig ant oracle-java8-jdk mono-mcs
+	$ echo $JAVA_HOME
+	/usr/lib/jvm/jdk-8-oracle-arm-vfp-hflt
+
+<b>Note:</b> The version of the V8 JavaScript engine in Raspbian is not compatible with uSCXML.
+
 ## Language Bindings
 
 In order to build any language bindings, you will need to have SWIG and the development kit of your target language
diff --git a/embedding/java/src/org/uscxml/tests/TestExceptions.java b/embedding/java/src/org/uscxml/tests/TestExceptions.java
new file mode 100644
index 0000000..95242b8
--- /dev/null
+++ b/embedding/java/src/org/uscxml/tests/TestExceptions.java
@@ -0,0 +1,36 @@
+package org.uscxml.tests;
+
+import org.uscxml.Interpreter;
+import org.uscxml.InterpreterException;
+
+public class TestExceptions {
+
+	public static void main(String[] args) throws InterpreterException {
+		System.load("/Users/sradomski/Documents/TK/Code/uscxml/build/cli/lib/libuscxmlNativeJava64.jnilib");
+		
+		String xml =
+		"<scxml datamodel=\"ecmascript\">" +
+		"	<state id=\"start\">" +
+		"		<transition target=\"done\" />" +
+		" </state>" +
+		" <final id=\"done\" />" +
+		"</scxml>";
+
+		if (false) {
+			// datamodel not available before first step -> dies with segfault
+			Interpreter interpreter = Interpreter.fromXML(xml);
+			System.out.println(interpreter.getDataModel().evalAsString("'FOO'"));
+		}
+
+		if (false) {
+			// datamodel is available but syntactic ecmascript exception is not propagated
+			Interpreter interpreter = Interpreter.fromXML(xml);
+			interpreter.step();
+			System.out.println(interpreter.getDataModel().evalAsString("'FOO' / qwer"));
+		}
+
+		
+		
+	}
+
+}
diff --git a/src/uscxml/messages/Data.h b/src/uscxml/messages/Data.h
index eb765db..818b26e 100644
--- a/src/uscxml/messages/Data.h
+++ b/src/uscxml/messages/Data.h
@@ -53,6 +53,7 @@ public:
 	Data(unsigned int atom) : atom(toStr(atom)), type(INTERPRETED) {}
 	Data(long atom) : atom(toStr(atom)), type(INTERPRETED) {}
 	Data(unsigned long atom) : atom(toStr(atom)), type(INTERPRETED) {}
+	Data(long long int atom) : atom(toStr(atom)), type(INTERPRETED) {}
 	Data(float atom) : atom(toStr(atom)), type(INTERPRETED) {}
 	Data(double atom) : atom(toStr(atom)), type(INTERPRETED) {}
 	Data(bool atom) : type(INTERPRETED) {