| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| --> |
| |
| <document> |
| |
| <properties> |
| <title>Commons SCXML Usage - API notes - Reader</title> |
| <author email="dev@commons.apache.org">Commons Documentation Team</author> |
| </properties> |
| |
| <body> |
| |
| <section name="Commons SCXML - Reading SCXML documents for Commons SCXML"> |
| <p>Commons SCXML provides its own implementation of the |
| <a href="https://commons.apache.org/scxml/apidocs/org/apache/commons/scxml2/model/package-summary.html"> |
| Java object model for SCXML</a> |
| and a dedicated <a href="https://commons.apache.org/scxml/apidocs/org/apache/commons/scxml2/io/SCXMLReader"> |
| SCXMLReader</a> that can read SCXML documents into that object model.</p> |
| |
| <subsection name="Usage"> |
| <p>The primary convenience method exposed by the <code>SCXMLReader</code> |
| is:</p> |
| <pre> |
| //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 |
| } |
| </pre> |
| |
| <p>It returns an <code>SCXML</code> object, which is the state machine / |
| chart represented in the Commons SCXML Java object model. This method |
| uses the <code>URL</code> of the initial SCXML document to resolve any |
| relative URLs referenced by the document, such as <code>src</code> |
| attributes of <code>State</code> SCXML elements.</p> |
| |
| <p>Commons SCXML provides convenience implementations of most of the |
| interfaces such as <code>XMLReporter</code>.</p> |
| |
| <p>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 |
| <code>org.apache.commons.scxml2.PathResolver</code>parameter needs to be |
| supplied through an SCXMLReader.Configuration instance for resolving relative |
| document references or as an |
| <code>InputSource</code>, in which case there is no path resolution, |
| so the document must be a standalone document.</p> |
| |
| <p>The <code>SCXMLReader</code> Javadoc is available |
| <a href="../apidocs/org/apache/commons/scxml2/io/SCXMLReader.html"> |
| here</a>. |
| </p> |
| </subsection> |
| |
| <subsection name="API notes set"> |
| <p>The next note in this set describes the |
| <a href="core-engine.html">SCXML engine</a>.</p> |
| </subsection> |
| |
| </section> |
| |
| </body> |
| |
| </document> |
