Package org.apache.shale.dialog

Simple dialog management for Shale.

See:
Description

Interface Summary

ActionState	An ActionState represents the execution of an action method (typically delegating behavior to appropriate business logic).
Dialog	Overall configuration of an individual dialog.
EndState	EndState is a spacialized ViewState that also marks this as the final State to be executed in the owning Dialog.
State	A State is an executable entity, within the scope of an owning Dialog.
Status	Status represents the current status of executing a Dialog, plus parent Dialogs that have executing subordinate Dialogs as part of their own processing.
SubdialogState	A SubdialogState represents the execution of a separate Dialog, after which processing proceeds within the current Dialog based upon the logical outcome returned by the EndState of the subordinate dialog.
Transition	Description of a transition from the owning State to another State with a specified identifier.
ViewState	A ViewState encapsulates the rendering of a JavaServer Faces view, identified by a specified view identifier.

Class Summary

Globals	Manifest constants that are global to the dialog implementation.
Status.Position	A Position represents a specific current State in a specific current Dialog.

Package org.apache.shale.dialog Description

Simple dialog management for Shale.

Introduction

This package contains the configuration beans and processing support for Shale dialogs. It was heavily inspired by the implementation of Spring Webflow (Preview 2), whose home page is:

http://opensource.atlassian.com/confluence/spring/display/WEBFLOW/Home

In addition, this package should currently be considered somewhere between a learning experiment for understanding what a dialog controller has to do and a very simplified version of what Spring WebFlow does for the use cases that do not require full blown flow support. It is NOT intended to be a replacement for a complete integration with Spring WebFlow.

Theory of Operation

Conceptually, a dialog can be thought of as a set of labelled states connected by labelled transitions between those states. A dialog has a specified starting state (with an automatic transition to this state when the dialog is entered), and one or more ending states.

This package supports the following state types:

• ActionState - Represents a call to a public method (taking no arguments, and returning a String) that is represented as a JavaServer Faces method binding expression.
• ViewState - Represents the rendering of a JavaServer Faces view, identified by a specified view identifier. Typically, a view corresponds to a JSP page, but any templating technology supported by your JSF implementation is supported transparently. If the specified view identifier has a corresponding ViewController managed bean, it receives the standard lifecycle callback services provided by Shale.
• SubdialogState - Represents pushing the state of the current dialog onto a stack and starting a specified dialog at its starting state. When the subordinate dialog returns, execution of the calling dialog continues.
• EndState - A specialized version of a ViewState that also marks the final state of a particular dialog. If the end state specifies a view identifier, it is rendered (as with a view state); however, this is not required if the parent dialog that invoked this dialog takes responsibility for producing the response to the current request.

Transitions between states are defined by logical outcome values returned by the execution of a particular state. The outcome is used to choose from among a set of potential successor states (one target state per outcome value). The state types generate logical outcome values as follows:

• ActionStates use the String return value of the method that was executed as the logical outcome.
• ViewStates wait until the rendered view is submitted. When the JSF action method that is executed (typically as the result of activating a particular submit button) returns an outcome, this value is used to select the appropriate transition, rather than using the standard JSF support for navigation rules. (This is only true during execution of a dialog - at all other times, the standard JSF navigation rules are processed as usual.)
• SubdialogStates wait for the subordinate dialog to complete, and perform a transition based on the logical outcome returned by the ending state of that dialog.
• EndStates return a logical outcome in one of two different ways, depending on whether a view identifier was specified:
  • If a view identifier was specified, the view is rendered, and the logical outcome returned by the action method that is executed on the subsequent submit is returned to the parent dialog as the logical outcome of the subdialog state that invoked this dialog.
  • IF no view identifier was specified (indicating that the parent dialog will be responsible for rendering the response for this request), the logical outcome that caused this ending state to be entered is returned to the caller. (FIXME - this doesn't seem quite right, but it is not clear what other value might be returned.)

A particular State has a set of Transitions owned by it that are always consulted first when a transition is being processed. However, it is also possible to associate global Transitions with the owning Dialog so that transition definitions do not have to be repeated for every state. This is analogous to the way that Struts 1.x supports both local and global ActionForward definitions.

In addition to managing state transitions, the dialog management framework maintains a variable of type Status, stored in session scope under a key that defaults to dialog (but is configurable via a context initialization parameter). In addition to maintaining the set of positions for all nested dialogs that are currently active, this object has a general purpose property (data) into which the application can store an object representing the "dialog scope" state information for this dialog. This allows straightforwards use of value binding expressions like #{dialog.data.foo} to reference the foo property of the current dialog's state. When a dialog is ended (i.e. the pop() method on the Status object is called), the reference to the state information will be thrown away, avoiding the need for the application to expicitly manage this behavior.

A Dialog must be specifically entered in order to trigger the behavior described above. Until that happens, the standard JSF request processing lifecycle occurs (supplemented by the value added features Shale provides). To cause a particular dialog to be entered, have one of your existing JSF action methods return a string of the form dialog:xxxxx, which will be intercepted by the dialog machinery and cause a dialog named xxxxx to be entered (at its starting state). Navigation and state transitions will be managed by the dialog feature until an ending state for dialog xxxxx is reached, after which standard JSF navigation processing is resumed.

As a side note, a dialog as configured here will tend to have fewer action states than a corresponding flow configured with Spring Web Flow for other web application frameworks. This is because the prerender() method support automatically provided by the Shale ViewController facility gives you an easy place to acquire model data that is needed to render the corresponding view. However, it is perfectly reasonable to intersperse action states between view states if you prefer to separate such data acquisition activities into methods that are separate from the view tier logic in a backing bean corresponding to the view.

Configuring the Runtime Environment

The bulk of the processing performed by this package is performed by DialogNavigationHandler, an implementation of javax.faces.application.NavigationHandler that leverages the pluggability features of JavaServer Faces to customize and specialize the standard behavior.

At runtime, the set of defined Dialogs is represented as a Map of Dialog instances, keyed by dialog name. This Map is stored in an application scope attribute named by the DIALOGS manifest constant in the Globals class. In addition, the current state of execution for a particular user (including a stack of dialogs if the Subdialog state has been utilized) is stored in a session scope attribute named by the STATUS manifest constant in the Globals class. This object will be of type Status.

You may configure the Map of Dialog instances in any manner you find convenient. However, most developers will find the XML-based configuration file support that is automatically provided will be the most convenient. You must provide zero or more XML documents that conform to the dialog.dtd DTD that is provided with Shale. You specify which documents you want to utilize by specifying a comma-separated list of context-relative paths (starting with a "/") of resources within your web application, as a context initiaization parameter named by the CONFIGURATION manifest constant in the Globals class. After all specified documents have been loaded, a resource named /WEB-INF/dialog-config.xml will be processed (if it exists), providing a mechanism to define dialogs by simply including a particular resource -- no modification to the web application deployment descriptor is required.

WARNING - The runtime environment assumes that the internal data structures describing the configured dialogs will be immutable for the life of the application, so no synchronization locks will be imposed. If you make dynamic modifications to this information, you are likely to cause corruption and race condition problems that are very difficult to reproduce and diagnose. To be safe, your application logic should contain NO functionality that directly accesses these data structures.

UML Class Diagrams