SCXML - Commons SCXML Usage - API notes

Commons SCXML - Reading SCXML documents for Commons SCXML

Commons SCXML provides its own implementation of the Java object model for SCXML and a dedicated SCXMLReader that can read SCXML documents into that object model.

Usage

The primary convenience method exposed by the SCXMLReader is:

        //import java.io.IOException;
        //import java.net.URL;
        //import org.apache.commons.scxml2.io.SCXMLReader;
        //import org.apache.commons.scxml2.model.ModelException;
        //import org.apache.commons.scxml2.model.SCXML;
        //import org.xml.sax.ErrorHandler;
        //import org.xml.sax.SAXException;

        //import java.io.IOException;
        //import java.net.URL;
        //import java.util.List;

        //import javax.xml.stream.XMLReporter;
        //import javax.xml.stream.XMLStreamException;

        //import org.apache.commons.scxml2.PathResolver;
        //import org.apache.commons.scxml2.io.SCXMLReader;
        //import org.apache.commons.scxml2.io.SCXMLReader.Configuration;
        //import org.apache.commons.scxml2.model.CustomAction;
        //import org.apache.commons.scxml2.model.ModelException;
        //import org.apache.commons.scxml2.model.SCXML;

        SCXML scxml = null;

        try {
          // Through a Configuration object the reading of a SCXML document can be configured and customized.
          Configuration configuration = new Configuration(<XMLReporter>, <PATHResolver>, <List<CustomAction>>);
          // scxml = SCXMLReader.read(<URL>);
          // scxml = SCXMLReader.read(<URL> new Configuration());
          scxml = SCXMLReader.read(<URL>, configuration);
        } catch (IOException e) {
          // IOException while reading
        } catch (ModelException e) {
          // ModelException while reading
        } catch (XMLStreamException e) {
          // XMLStreamException while reading
        }

        if (scxml == null) {
          // Reading failed
        }

It returns an SCXML object, which is the state machine / chart represented in the Commons SCXML Java object model. This method uses the URL of the initial SCXML document to resolve any relative URLs referenced by the document, such as src attributes of State SCXML elements.

Commons SCXML provides convenience implementations of most of the interfaces such as XMLReporter.

The SCXMLReader exposes other convenience methods which can handle a SCXML document specified using its "real path" on the local system, in which case an additional org.apache.commons.scxml2.PathResolverparameter needs to be supplied through an SCXMLReader.Configuration instance for resolving relative document references or as an InputSource, in which case there is no path resolution, so the document must be a standalone document.

The SCXMLReader Javadoc is available here.

API notes set

The next note in this set describes the SCXML engine.