This page contains notes about changes made before proposing the first release candidate of Commons SCXML. While attempts are made to maintain backwards compatibility even for unreleased code to minimize user inconvenience, some changes are best made before a first release, when the API gets locked (until the next major version atleast). Each change is described in terms of the motivation and the migration path for affected users.

Changes (in reverse chronological order):

SCXMLDigester methods now throw ModelException

Changed since: 05/18/2006

Affected users: All

The SCXMLDigester#digest() methods now throw a ModelException. This was done to provide better error reporting at parsing time, rather than {{NullPointerException}}s or some such.

Here is an example code snippet and the changes needed:

Before:

    SCXML scxml = null;

    try {
        scxml = SCXMLDigester.digest(<URL>, <ErrorHandler>);
    } catch (IOException ioe) {
        // IOException while parsing
    } catch (SAXException se) {
        // SAXException while parsing
    }

After:

    SCXML scxml = null;

    try {
        scxml = SCXMLDigester.digest(<URL>, <ErrorHandler>);
    } catch (IOException ioe) {
        // IOException while parsing
    } catch (SAXException se) {
        // SAXException while parsing
    } catch (ModelException me) {
        // ModelException while parsing
    }

All three exceptions are fatal from a Commons SCXML perspective, and require correcting the root cause (such as a misplaced or malformed document etc.)

Custom actions and the SCXMLDigester

Changed since: 05/18/2006

Affected users: Those who use custom actions

The earlier approach of adding custom actions, one at a time, after a SCXML digester was instantiated has been replaced by an approach where all custom actions are now passed at once while instantiating the SCXML digester. The earlier approach:

  • Was not processing custom actions in external documents (that were pulled in via the <state> "src" attribute, for instance).
  • Had a more error-prone API (needed a call to updateSCXML() method)

Here is an example code snippet and the changes needed (note that the custom action class itself can be reused, so no additional development is needed for custom actions):

Before:

  // (1) Get Digester with "default" rules for parsing SCXML documents
  Digester digester = SCXMLDigester.newInstance(null, null);

  // (2) Register the "custom" action(s)
  SCXMLDigester.addCustomAction(digester,
       "http://my.custom-actions.domain/CUSTOM", "hello", Hello.class);

  // (3) Repeat 2 for other custom actions 

  // (4) Parse the SCXML document containing the custom action(s)
  SCXML scxml = null;
  try {
      scxml = (SCXML) digester.parse(url.toString());
      // url points to SCXML document
  } catch (Exception e) {
      // bad document, take necessary action
  }

  // (5) Wire up the object model for the SCXMLExecutor
  SCXMLDigester.updateSCXML(scxml);

  // (6) Continue creating an SCXMLExecutor etc.

After:

  // (1) Create a list of custom actions, add as many as are needed
  List customActions = new ArrayList();
  CustomAction ca =
        new CustomAction("http://my.custom-actions.domain/CUSTOM",
                         "hello", Hello.class);
  customActions.add(ca);

  // (2) Add other custom actions to list

  // (3) Parse the SCXML document containing the custom action(s)
  SCXML scxml = null;
  try {
      scxml = SCXMLDigester.digest(url, errorHandler, customActions);
      // url points to SCXML document, errorHandler is SAX ErrorHandler
  } catch (Exception e) {
      // bad document, take necessary action
  }

  // (4) Continue creating an SCXMLExecutor etc.
  • No labels