<?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 - Parser</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>

 <body>

  <section name="Commons SCXML - Parsing SCXML documents for Commons SCXML">
    <p>Commons SCXML provides its own implementation of the
    <a href="http://commons.apache.org/scxml/apidocs/org/apache/commons/scxml/model/package-summary.html">
    Java object model for SCXML</a>
    and a configured <a href="http://commons.apache.org/digester">
    Digester</a> that can parse SCXML documents into that object model.</p>

    <subsection name="Usage">
     <p>The primary convenience method exposed by the <code>SCXMLParser</code>
     is:</p>
     <pre>
        //import java.io.IOException;
        //import java.net.URL;
        //import org.apache.commons.scxml.io.SCXMLParser;
        //import org.apache.commons.scxml.model.ModelException;
        //import org.apache.commons.scxml.model.SCXML;
        //import org.xml.sax.ErrorHandler;
        //import org.xml.sax.SAXException;

        SCXML scxml = null;

        try {
          scxml = SCXMLParser.parse(&lt;URL&gt;, &lt;ErrorHandler&gt;);
        } catch (IOException ioe) {
          // IOException while parsing
        } catch (SAXException se) {
          // SAXException while parsing
        } catch (ModelException me) {
          // ModelException while parsing
        }
          

        if (scxml == null) {
          // Parsing 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>ErrorHandler</code>.</p>

     <p>The SCXMLParser exposes other convenience methods which can handle
     a SCXML document specified using its &quot;real path&quot; on the local
     system, in which case an additional 
     <code>org.apache.commons.SCXML.PathResolver</code>parameter needs to be
     supplied 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>SCXMLParser</code> Javadoc is available
     <a href="../apidocs/org/apache/commons/scxml/io/SCXMLParser.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>
