##### Commons SCXML Resources

- Overview
- User Guide
- Javadoc
- FAQ
- Usecases
  - SCXML Stopwatch
  - SCXML in RDC group container
  - SCXML in Shale dialogs
- Building
- Dependencies
- Mailing lists
- Team
- SVN repository
- Nightly snapshots

##### Project Documentation

- About
- Project Info
- Project Reports
- Development Process

##### Commons

- Home
- Components
- Sandbox
- Dormant
- Volunteering
- Contributing Patches
- Building Components
- Releasing Components
- Wiki

##### Legend

- External Link
- Opens in a new window

## SCXML documents to describe Shale dialogs

Shale is "a proposal for a modern web application framework, fundamentaly based on JavaServer Faces". The Shale Framework includes a Dialog Manager, to describe "conversations" or "dialogs" (involving multiple views) with the user. Such a dialog is described using a state-machine like declarative notation defined by the Shale Framework. An alternative is using SCXML to describe the Shale dialogs by introducing a `DialogNavigationHandler` that uses the Commons SCXML engine.

### Motivation

- SCXML semantics support parallelism, allowing multiple dialogs to execute at the same time (a.k.a regions), and interact with each other. This will be useful as Shale Dialog Managers evolve.
- The Commons SCXML implementation allows for registering listeners that get notified as the state machine executes (onentry, onexit, ontransition).
- Those developing multi-channel applications, or using frameworks that use SCXML for the controller bits in other contexts (e.g. RDC framework), may be inclined towards SCXML-based authoring for Shale dialogs.

## Proof of concept

There are two war files below, the first one uses SCXML documents to describe the Shale dialogs, and the second one is the Shale source distro as-is, built locally (use cases of interest are the log on / create profile dialogs).

- struts-shale-usecases-scxml.war - Shale usecases war file with SCXML dialogs (note absence of `dialog-config.xml` in `WEB-INF/`, since SCXML documents are used to describe the Shale dialogs instead)
- struts-shale-usecases.war - Shale usecases war file (09/28/05 snapshot, not an official nightly build)

### UML Diagrams

Here are the UML state machine diagrams for the two dialogs in the usecases examples:

- Log on dialog
- Edit Profile dialog

### Building

For the proof of concept, we delegate the SCXML documents based Shale Dialog Management to a "`SCXMLDialogNavigationHandler`", instead of the `DialogNavigationHandler` in `shale-core`.

Some of the Javadoc is reproduced here:

Recipe for using SCXML documents to drive Shale dialogs:

1. Build the `SCXMLDialogNavigationHandler` (available below, use a Commons SCXML nightly build 10/09/05 or later) and make it available to your web application classpath (`WEB-INF/classes`).
2. Update the "`WEB-INF/faces-config.xml`" for your web application such that the "`faces-config/application/navigation-handler`" entry points to "`org.apache.commons.scxml.usecases.SCXMLDialogNavigationHandler`" (with the appropriate package name, if you changed it).
3. As an alternative to (1) and (2), you can place a jar in the `WEB-INF/lib` directory which contains the `SCXMLDialogNavigationHandler` and a `META-INF/faces-config.xml` with just the entry in (2).
4. Use SCXML documents to describe Shale dialog flows (details below) in your application. You may have multiple mappings from transition targets to JSF views to support multi-channel applications.
5. The SCXML-based dialog is entered when `handleNavigation()` is called with a logical outcome of the form "`dialog:xxx`" and there is no current dialog in progress, where "`xxx`" is the URL pointing to the SCXML document.

Using SCXML documents to define the Shale dialog "flows":

- ActionState instances may be mapped to executable content in UML `<onentry>` (and may be chained similarly).
- ViewState instances may be mapped to UML transition targets.
- SubdialogState instances may be mapped to external SCXML documents.
- EndState instances may be mapped to SCXML final states.
- The SCXMLDialogNavigationHandler defines a `"faces.outcome"` event which the relevant SCXML transitions from a "view state" can wait for.

### Artifacts

Relevant artifacts:

1. SCXMLDialogNavigationHandler.java
2. SCXMLDialogNavigationHandler.java.txt (for browsers that insist of enforcing mime-type by filename extension)
3. dialog-config.xml (from Shale distro, 09/28/05 snapshot)
4. log-on-config.xml (SCXML document describing the "Log On" dialog)
5. edit-profile-config.xml (SCXML document describing the "Edit Profile" dialog)
6. dialogstate2view.xml (Map UML states and activities)