The Shale Dialog Manager defines a generic API by which an application may utilize a Dialog Manager implementation to manage conversations with the user of that application. A user may have (at most) one active conversation in each window or frame that he or she is using.
This module contains the SCXML (State Chart XML) Implementation of the Shale Dialog Manager facilities. It uses the Commons SCXML library for the dialog state machine execution under the covers, and the dialogs are described using SCXML documents.
This section maps these types to the corresponding SCXML snippets appropriate for the Shale dialogs SCXML implementation. The example dialog from the Shale usecases sample application is captured here as a UML state machine diagram and forms the basis of the snippets below.
<onentry> (and may be chained similarly).
<!-- An "action" state -->
<state id="checkCookie">
<!-- Execute the method binding expression in the onentry block,
method must take no arguments and return a String. These
method binding expressions must use the #{...} syntax -->
<onentry>
<var name="cookieOutcome" expr="#{profile$logon.check}" />
</onentry>
<!-- Check the return value, and conditionally transition
to the appropriate state. Arbitrary EL expressions must use
the ${...} syntax. Since transitions are not guarded by
events, the transitions are "immediate" -->
<transition cond="${cookieOutcome eq 'authenticated'}"
target="exit"/>
<transition cond="${cookieOutcome eq 'unauthenticated'}"
target="logon"/>
</state>
id and the
JavaServer Faces view identifier is pluggable.
The default mapping is an identity transform i.e. the state
identifier is reused as the view identifier. See the
DialogStateMapper
Javadocs for details. This mapping may be overridden by using
the <shale:view> custom Commons SCXML action. See the
Shale dialogs custom Commons SCXML actions section
for details. Also note the associated
best practices
when authoring view <state>s.
<!-- A "view" state, the default convention maps this state to
to the JSF view identifier "/logon" -->
<state id="logon">
<!-- Wait for postback event, which is named "faces.outcome"
The reserved variable "outcome" contains the logical
outcome, which is used to conditionally transition
to the next state -->
<transition event="faces.outcome"
cond="${outcome eq 'authenticated'}"
target="exit"/>
<transition event="faces.outcome"
cond="${outcome eq 'create'}"
target="createProfile"/>
</state>
<!-- A "subdialog" state, the "src" attribute points to the SCXML
document describing the subdialog. -->
<state id="createProfile" src="edit-profile.xml">
<!-- Wait for <state_id>.done event, which lets us know
the subdialog has run to completion. This subdialog uses the
the "outcome" variable to convey its logical outcome to the
parent dialog (the SCXML <assign> element can be used
to assign values to existing variables) -->
<transition event="createProfile.done"
cond="${outcome eq 'success' or outcome eq 'cancel'}"
target="exit"/>
<transition event="createProfile.done"
cond="${outcome eq 'failure'}"
target="fail"/>
</state>
<!-- An "end" state, signifies that the dialog has run to
completion, the default convention maps this state to
to the JSF view identifier "/exit". -->
<state id="exit" final="true"/>
ViewController beans,
if you are also using the
Shale View Controller Support functionality)
that comprise your dialog, using standard JavaServer Faces and
(optional) Shale ViewController facilities./WEB-INF/dialog-config.xml, that conforms to the
required DTD:
<!DOCTYPE dialogs PUBLIC
"-//Apache Software Foundation//DTD Shale SCXML Dialog Configuration 1.0//EN"
"http://shale.apache.org/dtds/dialog-scxml-config_1_0.dtd">
<dialogs>
<dialog name="FirstDialogName"
scxmlconfig="firstdialog.xml"
dataclassname="org.apache.shale.examples.FirstDialogData"
/>
<dialog name="SecondDialogName"
scxmlconfig="seconddialog.xml"
dataclassname="org.apache.shale.examples.SecondDialogData"
/>
...
</dialogs>
<context-param> <param-name>org.apache.shale.dialog.scxml.CONFIGURATION</param-name> <param-value>/WEB-INF/foo.xml,/WEB-INF/bar.xml</param-value> </context-param>
/WEB-INF/dialog-config.xml will be automatically
processed, if it exists, and has not already been loaded./WEB-INF/lib will be scanned for configuration
documents at META-INF/dialog-config.xml. Such
resources will be automatically processed, making it easy to
define JAR files with dialog configurations and corresponding
Java classes and resources, which are recognized simply by
including this JAR file in the application.<onentry> <shale:redirect/> </onentry>
<onentry> <shale:view viewId="/faces/wizardpage3" /> </onentry>
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
xmlns:shale="http://shale.apache.org/dialog-scxml"
initialstate="...">
It is possible for application developers to define additional custom actions per dialog definition. For example, a developer may define a custom Commons SCXML action via a class my.actions.Foo (which must extend org.apache.commons.scxml.model.Action, see background reading link above) and make it available in the namespace URI http://foo.bar/actions to the dialog named "wizard" by defining it in the dialog-config.xml like so:
<dialog name="wizard" scxmlconfig="wizard.xml"
dataclassname="wizard.Data">
<scxmlaction name="foo" uri="http://foo.bar/actions"
actionclassname="my.actions.Foo" />
</dialog>
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
xmlns:shale="http://shale.apache.org/dialog-scxml"
xmlns:my="http://foo.bar/actions"
initialstate="...">
...
<state id="state1">
<onentry>
<my:foo .../>
</onentry>
...
</state>
The particular usecase of SCXML within Shale dialogs implies certain restrictions on the SCXML document used to describe the dialog. In particular, best practices for SCXML documents used to describe Shale dialogs include: