Shale Dialog2 Framework

Introduction

The Shale Dialog2 Framework is designed to allow configuration of a "dialog" or "conversation" with a user, which may span multiple HTTP requests. While such a dialog is in progress, the framework will also maintain a "data" object representing the state of the current computation, and throw that data object away when the conversation is completed, without waiting for the user to log off so that the user's session will be cleaned out.

Design goals for the framework include the following:

• Since Shale presumes the use of JavaServer Faces, utilize concepts and functionality that will be familiar to JSF application developers.
• Support a general abstraction of a "dialog", identified by a logical name, that represents a particular interaction with the application user.
• It MUST NOT be required that all interactions with the user be under the management of a dialog. Outside of the Dialog2 Framework, standard JSF functionality must operate as usual.
• It must be possible to associate a "context" representing the active execution of a particular dialog, with a particular user, in a particular JSF view. At most one context can be associated with any single view (i.e. a single frame or window).
• The context is used by the framework to maintain the state of the computation (such as which "state" is currently being executed, if the dialog is modelled as a state machine), and also by the application to maintain application data related to the dialog across requests.
• It must be possible for the application to cause a new instance of a context (for a particular named dialog) to be created and associated with a JSF view that did not previously have such an association.
• The framework must ensure that the context associated with a particular view will be maintained across requests while the corresponding dialog is active, and clean it up when the dialog completes.
• In the special case of a popup window associated with a main window, it must be possible to for the context instances of the two views to be associated with each other, such that the popup window's context can pull information from the main window, perform computations, and then store results back into the main window's context.
• To the maximum degree feasible, the framework should deal gracefully with browser "back" and "forward" buttons. IMPLEMENTATION NOTE - this requirement has not yet been addressed.

The remaining sections below provide more details about the generic framework APIs and functionality exposed to application developers. However, many details of the actual functionality (including configuration resource formats) will be specific to the particular implementation of the Dialog2 Framework that you select for your application, so be sure to consult the JavaDocs for that particular package as well.

Fundamental Concepts

The Shale Dialog2 framework operates on the following primary abstractions:

• A "dialog" is a logical name for some structured interaction with the user of a web application that typically lasts longer than a single HTTP request. The details of configuration and functionality are dependent upon the Dialog Framework implementation that is selected, but typically a dialog is configured as some sort of state machine that is driven by internal transitions. When interaction with the user is required, the framework can save the current state of an executing instance, display a specified JSF view, process the response (up through and including Invoke Application phase, and use the logical outcome specified by the application to drive further transitions.
• DialogContext - Contains the current state for a particular executing instance of a dialog, associated with a particular JavaServer Faces view. The dialog framework promises to save and restore this instance across requests, and expose it as a request scoped attribute specified by Constants.CONTEXT_BEAN (literal value is dialog2). At most one DialogContext may be associated with a JSF view at any time.
• DialogContextManager - Contains management methods to create new DialogContext instances, or retrieve existing ones, associated with a particular user session. During runtime execution of the application, the manager for a particular user is stored as a session scope attribute specified by Constants.MANAGER_BEAN (literal value is org.apache.shale.dialog2.MANAGER).

While a DialogContext instance is active for a particular JavaServer Faces view, it takes over the usual implementation of the JavaServer Faces NavigationHandler. After the Invoke Application phase completes, a custom navigation handler will call the advance() on the active DialogContext instance. This method is presumed to advance the state of the underlying dialog until a JavaServer Faces view needs to be displayed to the user. At that point, the advanced() method returns the required view identifier (or null to redisplay the current view, consistent with standard JavaServer Faces navigation), and the requested view is rendered to the user.

If there is no active DialogContext for the current view, the custom NavigationHandler delegates to the standard JavaServer Faces NavigationHandler. Because of this, you may freely intermix views managed by the dialog framework and views managed by standard JavaServer Faces navigation rules, in the same application.

It is quite often useful to maintain a set of information about the state of the current dialog's computation, across multiple requests to the server. When a particular dialog instance is completed, the corresponding information can be thrown away. The Dialog2 Framework supports these requirements by supporting a general purpose data property (of type Object) on the DialogContext instance. The data type of this object can be anything useful for the dialog being executed, but will typically be either a JavaBean containing properties for each individual information item comprising the state of the computation for this dialog, or a Map where key/value pairs can easily be stored. When the dialog instance has completed its computation, the data object will have all references to it removed, so that it can be garbage collected.

Of particular note is the fact that JavaServer Faces value binding expressions can be used to bind visual components to values in the data object. For example, assume that the dialog is managing a wizard dialog for updating a user profile, and one of the properties that can be edited is the user's full name. One can bind an input text component directly to the corresponding property like this, with no need for intermediate copying as the various pages of the wizard dialog are navigated:

    <h:inputText id="fullName" value="#{dialog2.data.fullName}"/>

Creating A New DialogContext Instance

If the current view does not have an active DialogContext instance associated with it, there are several approaches available to creating a new instance and associating it with the current view:

• Via Navigation - If the action method executed by the Invoke Application phase returns a logical outcome that begins with the prefix specified by Constants.DIALOG_PREFIX (literal value is dialog2:), a new DialogContext instance for a dialog named by the remainder of the logical outcome string will be created and associated with the current view. To start a dialog named "wizard", the action method could execute:

  return "dialog2:wizard";
          

• Programmatically - If the action method acquires a reference to the DialogContextManager for the user, it can programmatically create a new instance by executing code like this:

  // Create a new DialogContext instance for a dialog named "wizard"
  FacesContext context = FacesContext.getCurrentInstance();
  DialogContextManager manager = (DialogContextManager)
    context.getApplication().getVariableResolver().
    resolveVariable(context, Constants.MANAGER_BEAN);
  DialogContext dcontext = manager.create(context, "wizard");
  
  // Advance the state of this dialog until it needs to display a view
  String viewId = dcontext.advance(context, null);
  
  // Navigate to the specified view and return
  ViewHandler vh = context.getApplication().getViewHandler();
  UIViewRoot view = vh.createView(context, viewId);
  view.setViewId(viewId);
  context.setViewRoot(view);
  context.renderResponse();
  return null;
          

• Via Request Parameter - If the request URI for a JSF request includes a request parameter specified by Constants.DIALOG_NAME (literal value is org.apache.shale.dialog2.DIALOG_NAME), a new DialogContext instance for this dialog name will be created and associated with the current view. For example, a request for view editCustomer.faces could also request starting the EditCustomerInfo dialog by submitting a request URL like this:

  http://localhost:8080/myapp/editCustomer.faces?org.apache.shale.dialog2.DIALOG_NAME=EditCustomerInfo
          

In the latter case, there is an additional option to cause the newly created dialog instance to be associated with a parent dialog instance for the same user. This is accomplished by specifying an additional request parameter specified by Constants.PARENT_ID (literal value is org.apache.shale.dialog2.PARENT_ID), whose value is the dialog id of an active dialog for this user.

The most common use case for this special parent/child relationship is where the main page that a user is executing is under control of a named dialog, and the application wishes to display a popup window (under the control of its own dialog, and therefore its own DialogContext intsance) that can access the data of the parent dialog instance, via a value binding expression like #{dialog2.parent.data.fullName} from within the popup dialog's execution. In this way, you can easily create popup dialogs that can pull initial state information from the main window, perform arbitrary operations on it, and push results back to the main window ... with the only coupling being agreement on the names of properties in the parent dialog's data object to be used for communication.

Removing An Existing DialogContext Instance

The precise mechanism by which a DialogContext is removed is dependent upon the implementation selected, but typically an implementation will allow the application developer to specify an "end state" that, when advance() reaches that state, will cause the remove() method on the DialogContextManager instance for the current user to be called. This will trigger any necessary cleanup, including releasing all references to the data object for the removed DialogContext instance so that it can be garbage collected.

Packaging a Dialog2 Implementation

Any implementation of the Shale Dialog2 APIs should conform to the following requirements:

• Package all of the required implementation classes into a JAR file (or declare dependencies on specified external JAR files for some of the functionality).
• Provide a META-INF/faces-config.xml resource in the JAR file, so that the JavaServer Faces implementation will process the included configuration metadata at application startup time.
• At a minimum, include a managed bean definition for your implementation of org.apache.shale.dialog2.DialogContextManager. The managed bean definition must:
  • Declare the managed bean name to be the value specified by Constants.MANAGER_BEAN (literal value is org.apache.shale.dialog2.MANAGER).
  • Declare the bean to be placed in session scope, because it will be created once per user in a running application.
• Ensure that your DialogContextManager implementation will configure itself on demand, upon the first call to its processing methods.

If these requirements are met, an application developer may select a particular implementation simply by dropping its corresponding JAR file (and any external dependencies that the implementation also requires) into the /WEB-INF/lib directory of a web application, and the implementation will be self configured.

Available Implementations

The Shale Sandbox currently contains two implementations of the Dialog2 Framework:

• Legacy - So named because it supports a superset of the original Shale Dialog framework functionality available through version 1.0.3, with dialogs configured in an XML document that represents a simple state machine with transitions driven by logical outcomes.
• SCXML - So named because it represents dialogs as a state machine configured according to the schema for State Chart XML, a general purpose framework for defining advanced state machines. This implementation depends on the Commons SCXML implementation from Apache.