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 Basic Implementation of the Shale Dialog Manager facilities. It is designed to be as simple as possible to configure and use, while encapsulating advanced state management capabilities. It is fundamentally similar in in configuration and use with the legacy Dialog Manager support in Shale versions up through 1.0.3, but many bugs and limitations of the original code have been corrected.
Conceptually, a dialog can be thought of as a set of labelled states, connected by labelled transitions between those states. Indeed, a UML State Diagram is a popular way to represent the architecture of such a dialog. Each dialog has a specified starting state (with an automatic transition to this state when the dialog is first started), and one or more ending states.
Shale supports four state types, with specific implementations realized as described below.
ViewController
bean that you've associated with
the current page) is used to drive the transition to the next
state, as described below.It is not required that all JavaServer Faces
interactions be organized into dialogs -- you can have a mix of
dialog and standard navigation processing. Indeed, to enter a
dialog in the first place, simply have one of your standard action
methods return a logical outcome of dialog:xxxxx,
which will cause the dialog named xxxxx
to be entered
at its starting state. Once that dialog completes, standard
JavaServer Faces navigation will resume.
The configuration of a Dialog is represented as a tree of
JavaBeans defined in the org.apache.shale.dialog.model
package, rooted at an instance Dialog
. The set of
all known Dialog
instances is stored in a Map
,
keyed by dialog identifier, which is stored in an application scope
attribute named by symbolic constant Globals.DIALOGS
.
The Dialog
instances may be configured by any desired
mechanism; however, the most commonly used will likely be an XML
document that conforms to a DTD provided by Shale.
To use the Dialog Manager facilities in Shale, take the following steps:
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, which defines all the state transitions:
<!DOCTYPE dialogs PUBLIC "-//Apache Software Foundation//DTD Shale Dialog Configuration 1.1//EN" "http://shale.apache.org/dtds/dialog-config_1_1.dtd"> <dialogs> <dialog name="First Dialog Name" start="Start State Id"> ... <action/>, <view/>, <subdialog/>, and <exit/> elements for states ... </dialog> <dialog name="Second Dialog Name" start="Start State Id"> ... <action/>, <view/>, <subdialog/>, and <exit/> elements for states ... </dialog> ... </dialogs>
<context-param> <param-name>org.apache.shale.dialog.basic.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.<context-param> <param-name>org.apache.shale.dialog.basic.STRATEGY</param-name> <param-value>xxxxx</param-value> </context-param>
The possible strategy values, and the use cases under which they are appropriate, are as follows:
data
object associated with
this dialog instance is not saved and restored.
This works best in cases like a multi-page wizard dialog that
is collecting data, where resubmitting the same page again only
mutates the state within the data
object, and does
not cause any undesireable changes to the model state of the
application (such as submitting a credit card order more than
once). This strategy can not effectively deal with cases where
the user has navigated across the start or end of a subdialog,
so an exception will be thrown in that scenario.Position
information for the current dialog instance,
including any changes to the data
object. This
strategy is best used when you want, when the user presses the
back arrow, to "unwind" any changes that the previous form submit
did to the data
object. This strategy stores the
maximum amount of information in the JSF component tree state,
so it might have significant memory or network traffic impacts
if the size of your data
object is large.immediate
attribute set to
true
, to allow the user to get out of a dialog where they
have mistakenly tried to submit the same form more than once.