Added: struts/shale/trunk/core-library/src/java/org/apache/shale/dialog/package.html URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/dialog/package.html?view=auto&rev=161626 ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/dialog/package.html (added) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/dialog/package.html Sat Apr 16 22:45:42 2005 @@ -0,0 +1,166 @@ +<!-- + * Copyright 2004-2005 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. +--> + +<!-- $Id$ --> + +<body> + +<p>Simple dialog management for Shale.</p> + +<h3>Introduction</h3> + +<p>This package contains the configuration beans and processing support for +Shale dialogs. It was <strong>heavily</strong> inspired by the implementation +of Spring Webflow (Preview 2), whose home page is:</p> +<blockquote> +<a href="http://opensource.atlassian.com/confluence/spring/display/WEBFLOW/Home";> +http://opensource.atlassian.com/confluence/spring/display/WEBFLOW/Home</a> +</blockquote> + +<p>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 <strong>NOT</strong> intended to +be a replacement for a complete integration with Spring WebFlow.</p> + +<h3>Theory of Operation</h3> + +<p>Conceptually, a <em>dialog</em> 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.</p> + +<p>This package supports the following state types:</p> +<ul> +<li><a href="ActionState.html">ActionState</a> - Represents a call to a + public method (taking no arguments, and returning a String) that is + represented as a JavaServer Faces <em>method binding expression</em>. +<li><a href="ViewState.html">ViewState</a> - Represents the rendering of + a JavaServer Faces <em>view</em>, 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 + <a href="../ViewController.html">ViewController</a> managed bean, it + receives the standard lifecycle callback services provided by Shale.</li> +<li><a href="SubdialogState.html">SubdialogState</a> - 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.</li> +<li><a href="EndState.html">EndState</a> - A specialized version of a + <a href="ViewState.html">ViewState</a> 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.</li> +</ul> + +<p>Transitions between states are defined by logical <em>outcome</em> 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:</p> +<ul> +<li><a href="ActionState.html">ActionState</a>s use the String return value + of the method that was executed as the logical outcome.</li> +<li><a href="ViewState.html">ViewState</a>s 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 <strong>only</strong> + true during execution of a dialog - at all other times, the standard + JSF navigation rules are processed as usual.)</li> +<li><a href="SubdialogState.html">SubdialogState</a>s wait for the subordinate + dialog to complete, and perform a transition based on the logical outcome + returned by the ending state of that dialog.</li> +<li><a href="EndState.html">EndState</a>s return a logical outcome in one of + two different ways, depending on whether a view identifier was specified: + <ul> + <li>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.</li> + <li>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.)</li> + </ul></li> +</ul> + +<p>A <a href="Dialog.html">Dialog</a> 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 +<code>dialog:xxxxx</code>, which will be intercepted by the dialog machinery +and cause a dialog named <code>xxxxx</code> to be entered (at its starting +state). Navigation and state transitions will be managed by the dialog +feature until an ending state for dialog <code>xxxxx</code> is reached, after +which standard JSF navigation processing is resumed.</p> + +<p>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 +<code>prerender()</code> method support automatically provided by the Shale +<a href="../ViewController.html">ViewController</a> 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.</p> + +<h3>Configuring the Runtime Environment</h3> + +<p>The bulk of the processing performed by this package is performed by +<a href="DialogNavigationHandler.html">DialogNavigationHandler</a>, an +implementation of <code>javax.faces.application.NavigationHandler</code> +that leverages the pluggability features of JavaServer Faces to customize +and specialize the standard behavior.</p> + +<p>At runtime, the set of defined <a href="Dialog.html">Dialog</a>s is +represented as a <code>Map</code> of <a href="Dialog.html">Dialog</a> +instances, keyed by dialog name. This <code>Map</code> is stored in an +application scope attribute named by the <code>DIALOGS</code> manifest +constant in the <a href="Globals.html">Globals</a> 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 <code>STATUS</code> manifest constant in the +<a href="Globals.html">Globals</a> class. This object will be of type +<a href="Status.html">Status</a>.</p> + +<p>You may configure the <code>Map</code> of <a href="Dialog.html">Dialog</a> +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 <code>dialog.dtd</code> 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 +<code>CONFIGURATION</code> manifest constant in the +<a href="Globals.html">Globals</a> class. After all specified documents have +been loaded, a resource named <code>/WEB-INF/dialog-config.xml</code> 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.</p> + +<p><strong>WARNING</strong> - 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 +<strong>NO</strong> functionality that directly accesses these data structures.</p> + +</body>
Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/faces/shale-config.xml URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/faces/shale-config.xml?view=diff&r1=161625&r2=161626 ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/faces/shale-config.xml (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/faces/shale-config.xml Sat Apr 16 22:45:42 2005 @@ -38,11 +38,17 @@ <chain name="destroy"> + <!-- Clean up dialogs configuration --> + <command className="org.apache.shale.dialog.ConfigurationDestroy"/> + </chain> <!-- ====================== Appication Startup =========================== --> <chain name="init"> + + <!-- Configure dialogs from specified resources --> + <command className="org.apache.shale.dialog.ConfigurationInit"/> </chain> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
