org.apache.commons.scxml.io
Class SCXMLParser

java.lang.Object
  org.apache.commons.scxml.io.SCXMLParser

public final class SCXMLParser
extends Object

The SCXMLParser provides the ability to parse a SCXML document into the Java object model provided in the model package.

The SCXMLParser can be used for:

1. Parse a SCXML file into the Commons SCXML Java object model.
2. Obtain a SCXML Parser for further customization of the default ruleset.

If switching from SCXMLDigester, changes need to be made to the SCXML documents, such as:

• A <parallel> should not be wrapped in a <state> element unless otherwise necessary
• <var> and <exit> elements continue to be supported by Commons SCXML, but in the Commons SCXML namespace: http://commons.apache.org/scxml
• <event> is now supported

See latest version of the SCXML Working Draft for more details.

NOTE: The SCXMLParser assumes that the SCXML document to be parsed is well-formed and correct. If that assumption does not hold, any subsequent behavior is undefined.

Since:

0.7

Method Summary

static org.apache.commons.digester.Digester	newInstance() Obtain a SCXML digester instance for further customization.
static org.apache.commons.digester.Digester	newInstance(PathResolver pr) Obtain a SCXML digester instance for further customization.
static org.apache.commons.digester.Digester	newInstance(SCXML scxml, PathResolver pr) Obtain a SCXML digester instance for further customization.
static org.apache.commons.digester.Digester	newInstance(SCXML scxml, PathResolver pr, List customActions) Obtain a SCXML digester instance for further customization.
static SCXML	parse(InputSource documentInputSource, ErrorHandler errHandler) API for standalone usage where the SCXML document is an InputSource.
static SCXML	parse(InputSource documentInputSource, ErrorHandler errHandler, List customActions) API for standalone usage where the SCXML document is an InputSource.
static SCXML	parse(String documentRealPath, ErrorHandler errHandler, PathResolver pathResolver) API for standalone usage where the SCXML document is a URI.
static SCXML	parse(String documentRealPath, ErrorHandler errHandler, PathResolver pathResolver, List customActions) API for standalone usage where the SCXML document is a URI.
static SCXML	parse(URL scxmlURL, ErrorHandler errHandler) API for standalone usage where the SCXML document is a URL.
static SCXML	parse(URL scxmlURL, ErrorHandler errHandler, List customActions) API for standalone usage where the SCXML document is a URL, and the document uses custom actions.
static void	updateSCXML(SCXML scxml) Update the SCXML object model and make it SCXMLExecutor ready.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

parse

public static SCXML parse(URL scxmlURL,
                          ErrorHandler errHandler)
                   throws IOException,
                          SAXException,
                          ModelException

API for standalone usage where the SCXML document is a URL.

Parameters:

scxmlURL - a canonical absolute URL to parse (relative URLs within the top level document are to be resovled against this URL).

errHandler - The SAX ErrorHandler

Returns:

SCXML The SCXML object corresponding to the file argument

Throws:

IOException - Underlying Digester parsing threw an IOException

SAXException - Underlying Digester parsing threw a SAXException

ModelException - If the resulting document model has flaws

See Also:

ErrorHandler, PathResolver

parse

public static SCXML parse(String documentRealPath,
                          ErrorHandler errHandler,
                          PathResolver pathResolver)
                   throws IOException,
                          SAXException,
                          ModelException

API for standalone usage where the SCXML document is a URI. A PathResolver must be provided.

Parameters:

pathResolver - The PathResolver for this context

documentRealPath - The String pointing to the absolute (real) path of the SCXML document

errHandler - The SAX ErrorHandler

Returns:

SCXML The SCXML object corresponding to the file argument

Throws:

IOException - Underlying Digester parsing threw an IOException

SAXException - Underlying Digester parsing threw a SAXException

ModelException - If the resulting document model has flaws

See Also:

ErrorHandler, PathResolver

parse

public static SCXML parse(InputSource documentInputSource,
                          ErrorHandler errHandler)
                   throws IOException,
                          SAXException,
                          ModelException

API for standalone usage where the SCXML document is an InputSource. This method may be used when the SCXML document is packaged in a Java archive, or part of a compound document where the SCXML root is available as a org.w3c.dom.Element or via a java.io.Reader.

Note: Since there is no path resolution, the SCXML document must not have external state sources.

Parameters:

documentInputSource - The InputSource for the SCXML document

errHandler - The SAX ErrorHandler

Returns:

SCXML The SCXML object corresponding to the file argument

Throws:

IOException - Underlying Digester parsing threw an IOException

SAXException - Underlying Digester parsing threw a SAXException

ModelException - If the resulting document model has flaws

See Also:

ErrorHandler

parse

public static SCXML parse(URL scxmlURL,
                          ErrorHandler errHandler,
                          List customActions)
                   throws IOException,
                          SAXException,
                          ModelException

API for standalone usage where the SCXML document is a URL, and the document uses custom actions.

Parameters:

scxmlURL - a canonical absolute URL to parse (relative URLs within the top level document are to be resovled against this URL).

errHandler - The SAX ErrorHandler

customActions - The list of CustomActions this digester instance will process, can be null or empty

Returns:

SCXML The SCXML object corresponding to the file argument

Throws:

IOException - Underlying Digester parsing threw an IOException

SAXException - Underlying Digester parsing threw a SAXException

ModelException - If the resulting document model has flaws

See Also:

ErrorHandler, PathResolver

parse

public static SCXML parse(String documentRealPath,
                          ErrorHandler errHandler,
                          PathResolver pathResolver,
                          List customActions)
                   throws IOException,
                          SAXException,
                          ModelException

API for standalone usage where the SCXML document is a URI. A PathResolver must be provided.

Parameters:

pathResolver - The PathResolver for this context

documentRealPath - The String pointing to the absolute (real) path of the SCXML document

errHandler - The SAX ErrorHandler

customActions - The list of CustomActions this digester instance will process, can be null or empty

Returns:

SCXML The SCXML object corresponding to the file argument

Throws:

IOException - Underlying Digester parsing threw an IOException

SAXException - Underlying Digester parsing threw a SAXException

ModelException - If the resulting document model has flaws

See Also:

ErrorHandler, PathResolver

parse

public static SCXML parse(InputSource documentInputSource,
                          ErrorHandler errHandler,
                          List customActions)
                   throws IOException,
                          SAXException,
                          ModelException

API for standalone usage where the SCXML document is an InputSource. This method may be used when the SCXML document is packaged in a Java archive, or part of a compound document where the SCXML root is available as a org.w3c.dom.Element or via a java.io.Reader.

Note: Since there is no path resolution, the SCXML document must not have external state sources.

Parameters:

documentInputSource - The InputSource for the SCXML document

errHandler - The SAX ErrorHandler

customActions - The list of CustomActions this digester instance will process, can be null or empty

Returns:

SCXML The SCXML object corresponding to the file argument

Throws:

IOException - Underlying Digester parsing threw an IOException

SAXException - Underlying Digester parsing threw a SAXException

ModelException - If the resulting document model has flaws

See Also:

ErrorHandler

newInstance

public static org.apache.commons.digester.Digester newInstance()

Obtain a SCXML digester instance for further customization.

API Notes:

• Use the digest() convenience methods if you do not need a custom digester.
• After the SCXML document is parsed by the customized digester, the object model must be made executor-ready by calling updateSCXML(SCXML) method in this class.

Returns:

Digester A newly configured SCXML digester instance

See Also:

updateSCXML(SCXML)

newInstance

public static org.apache.commons.digester.Digester newInstance(PathResolver pr)

Obtain a SCXML digester instance for further customization.

API Notes:

• Use the digest() convenience methods if you do not need a custom digester.
• After the SCXML document is parsed by the customized digester, the object model must be made executor-ready by calling updateSCXML(SCXML) method in this class.

Parameters:

pr - The PathResolver, may be null for standalone documents

Returns:

Digester A newly configured SCXML digester instance

See Also:

updateSCXML(SCXML)

newInstance

public static org.apache.commons.digester.Digester newInstance(SCXML scxml,
                                                               PathResolver pr)

Obtain a SCXML digester instance for further customization.

API Notes:

• Use the digest() convenience methods if you do not need a custom digester.
• After the SCXML document is parsed by the customized digester, the object model must be made executor-ready by calling updateSCXML(SCXML) method in this class.

Parameters:

scxml - The parent SCXML document if there is one (in case of state templates for example), null otherwise

pr - The PathResolver, may be null for standalone documents

Returns:

Digester A newly configured SCXML digester instance

See Also:

updateSCXML(SCXML)

newInstance

public static org.apache.commons.digester.Digester newInstance(SCXML scxml,
                                                               PathResolver pr,
                                                               List customActions)

Obtain a SCXML digester instance for further customization.

API Notes:

• Use the digest() convenience methods if you do not need a custom digester.
• After the SCXML document is parsed by the customized digester, the object model must be made executor-ready by calling updateSCXML(SCXML) method in this class.

Parameters:

scxml - The parent SCXML document if there is one (in case of state templates for example), null otherwise

pr - The PathResolver, may be null for standalone documents

customActions - The list of CustomActions this digester instance will process, can be null or empty

Returns:

Digester A newly configured SCXML digester instance

See Also:

updateSCXML(SCXML)

updateSCXML

public static void updateSCXML(SCXML scxml)
                        throws ModelException

Update the SCXML object model and make it SCXMLExecutor ready. This is part of post-digester processing, and sets up the necessary object references throughtout the SCXML object model for the parsed document. Should be used only if a customized digester obtained using the newInstance() methods is needed.

Parameters:

scxml - The SCXML object (output from Digester)

Throws:

ModelException - If the document model has flaws