2009/05/20 - Apache Shale has been retired.

For more information, please explore the Attic.

Shale Dialog Manager


One of the frustrating aspects of organizing the flow of control in a web based application is that fact that it is composed of completely disconnected interactions with the client (via the HTTP protocol). The popularity of application frameworks based on model-view-controller (MVC) principles, and particularly the emergence of the front controller design pattern, have become the de facto standard architectural approach.

Like other frameworks, JavaServer Faces supports a mechanism to define navigation rules for transitions between views. The actual processing is performed by an implementation of the javax.faces.application.NavigationHandler. The standard implementation provided by the framework (which can be customized via a pluggable API) performs transitions from one view to another based on three inputs:

  • What view is currently processing this form submit?
  • Which of the potentially several actions were invoked? (This allows you to support different "submit" buttons with different functionality, or share actions between, say, a "Save" button at the top and bottom of a table.)
  • What "logical outcome" was returned by the action that was invoked?
Basing navigation on outcomes, by the way, assists in reducing the coupling between pages, because the developer that writes the action method is only focused on reporting "what happened" rather than worrying about "where do I go next". This concept is also found in the way Struts has Action.execute() methods that return a logical ActionForward describing the outcome of performing the action.

However, it is still difficult to reuse individual views in more than one "conversation" or "dialog" with the user, nor to treat one dialog as a "black box" subroutine that can be called by more than one calling dialog. To address these needs, Shale offers Dialog Manager support.

The functionality of this feature was heavily inspired by the implementation of Spring Webflow (Preview 2), whose home page is:


Services Provided

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.

  • ActionState - Represents a call to a public method, taking no parameters, and returning a String that will be treated as the logical outcome. The method to be called is configured with a JavaServer Faces method binding expression, which means you can leverage the managed beans facility to instantiate your processing classes on demand. The logical outcome is used to drive the transition to the next state, as described below.
  • ViewState - Represents the rendering of a JavaServer Faces view, followed by a wait for the subsequent form submit. The logical outcome returned by the action method (typically on the ViewController bean that you've associated with the current page) is used to drive the transition to the next state, as described below.
  • SubdialogState - Represents pushing the state of the current dialog onto a stack, and starting a specified new dialog at its starting state. When the subordinate dialog returns, the calling dialog is resumed, with the logical outcome returned by the subordinate dialog is used to drive the transition to the next state, as described below.
  • EndState - Terminates the current dialog (popping the stack if we are inside a subdialog), and returns a logical outcome (to drive transition) in one of two ways:
    • If a view identifier was configured, cause that view to be rendered and return the logical outcome from the application action that is invoked (just like a ViewState, but also terminates the dialog).
    • If no view identifier was configured (meaning that the parent dialog will be responsible for rendering the response to the current request), simply return the logical outcome that caused this EndState to be selected.
Transitions between states are performed by consulting the set of Transitions that have been defined (either locally for this State, or globally for the entire Dialog), matching on logical outcome. The matching Transition is then used to select the identifier of the next state to be performed (which can be of any type).

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 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.

Using Dialog Manager

To use the Dialog Manager facilities in Shale, take the following steps:

  • Model your dialog as a series of States with transitions between them labelled with the logical outcome that selects that particular transition. A UML State Diagram is a very useful mechanism for visualizing such a model.
  • Build the views (and corresponding ViewController beans) that comprise your dialog, using standard JavaServer Faces and (optional) Shale ViewController facilities.
  • Define your dialogs in an XML document, conventionally named /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.0//EN"
      <dialog name="First Dialog Name" start="Start State Id">
        ... <action/>, <view/>, <subdialog/>, and <exit/> elements for states ...
      <dialog name="Second Dialog Name" start="Start State Id">
        ... <action/>, <view/>, <subdialog/>, and <exit/> elements for states ...
  • If you have more than one dialog configuration file, or you have defined your only dialog configuration file as a web application resource with a name different than the one described above, use a context initiaization parameter to define a comma-delimited list of context-relative paths to configuration resources to be loaded:
  • In addition to the dialog configuration resources defined by this context initialization parameter, a resource named /WEB-INF/dialog-config.xml will be automatically processed, if it exists.
  • To initiate a dialog named "xxxxx", configure one of your standard JavaServer Faces actions to return a logical outcome of dialog:xxxxx