Author: craigmcc
Date: Wed Oct 18 20:46:51 2006
New Revision: 465459
URL: http://svn.apache.org/viewvc?view=rev&rev=465459
Log:
Up-to-date documentation for Shale Dialog Manager (Basic Implementation).
SHALE-300
Added:
shale/framework/trunk/shale-dialog-basic/src/site/
shale/framework/trunk/shale-dialog-basic/src/site/site.xml (with props)
shale/framework/trunk/shale-dialog-basic/src/site/xdoc/
shale/framework/trunk/shale-dialog-basic/src/site/xdoc/index.xml (with
props)
Added: shale/framework/trunk/shale-dialog-basic/src/site/site.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog-basic/src/site/site.xml?view=auto&rev=465459
==============================================================================
--- shale/framework/trunk/shale-dialog-basic/src/site/site.xml (added)
+++ shale/framework/trunk/shale-dialog-basic/src/site/site.xml Wed Oct 18
20:46:51 2006
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="Apache Shale Framework - Core Library">
+
+ <body>
+
+ <menu name="Shale Taglib Resources">
+ <item name="Tag Reference" href="/tagreference.html"/>
+ <item name="Taglibdoc" href="/tlddoc/index.html"/>
+ </menu>
+
+ <menu name="Quick Links">
+ <item name="JavaServer Faces"
+ href="http://java.sun.com/javaee/javaserverfaces/"/>
+ <item name="MyFaces"
+ href="http://myfaces.apache.org"/>
+ <item name="Shale"
+ href="http://shale.apache.org"/>
+ <item name="Shale Sandbox"
+ href="http://shale.apache.org/sandbox"/>
+ <item name="Struts"
+ href="http://struts.apache.org"/>
+ <item name="Struts-Faces Integration Library"
+ href="http://struts.apache.org/1.x/struts-faces"/>
+ </menu>
+
+ <menu name="Sub-Project Documentation">
+ <item name="Application Controller"
+
href="../shale-application/index.html"/>
+ <item name="Clay Plug-In" href="../shale-clay/index.html"/>
+ <item name="Core Library" href="../shale-core/index.html"/>
+ <item name="Dialog Manager" href="../shale-dialog/index.html"/>
+ <item name="Dialog Manager (Basic Implementation)"
+
href="../shale-dialog-basic/index.html"/>
+ <item name="Dialog Manager (SCXML Implementation)"
+
href="../shale-dialog-scxml/index.html"/>
+ <item name="Spring Integration" href="../shale-spring/index.html"/>
+ <item name="Test Framework" href="../shale-test/index.html"/>
+ <item name="Tiles Integration" href="../shale-tiles/index.html"/>
+ <item name="Tiger Extensions" href="../shale-tiger/index.html"/>
+ <item name="Validator Support" href="../shale-validator/index.html"/>
+ <item name="View Controller" href="../shale-view/index.html"/>
+ </menu>
+
+ <menu name="Sample Apps Documentation">
+ <item name="Blank Starter"
href="../shale-apps/shale-blank/index.html"/>
+ <item name="Clay Use Cases"
href="../shale-apps/shale-clay-usecases/index.html"/>
+ <item name="Mail Reader"
href="../shale-apps/shale-mailreader/index.html"/>
+ <item name="SQL Browser"
href="../shale-apps/shale-sql-browser/index.html"/>
+ <item name="Use Cases"
href="../shale-apps/shale-usecases/index.html"/>
+ </menu>
+
+ ${reports}
+
+ </body>
+
+</project>
+
+
+
+
+
Propchange: shale/framework/trunk/shale-dialog-basic/src/site/site.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: shale/framework/trunk/shale-dialog-basic/src/site/site.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Added: shale/framework/trunk/shale-dialog-basic/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog-basic/src/site/xdoc/index.xml?view=auto&rev=465459
==============================================================================
--- shale/framework/trunk/shale-dialog-basic/src/site/xdoc/index.xml (added)
+++ shale/framework/trunk/shale-dialog-basic/src/site/xdoc/index.xml Wed Oct 18
20:46:51 2006
@@ -0,0 +1,181 @@
+<?xml version="1.0"?>
+<document>
+
+ <properties>
+ <title>Shale Dialog Manager (Basic Implementation)</title>
+ </properties>
+
+ <body>
+
+ <section name="Shale Dialog Manager (Basic Implementation)">
+ <a name="dialog-basic"/>
+
+ <a name="dialog-basic-introduction"/>
+ <subsection name="Introduction">
+
+ <p>The <a href="../shale-dialog/index.html">Shale Dialog Manager</a>
+ 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.</p>
+
+ <p>This module contains the <em>Basic Implementation</em> 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.</p>
+
+ </subsection>
+
+ <a name="dialog-basic-services"/>
+ <subsection name="Services Provided">
+
+ <p>Conceptually, a <em>dialog</em> can be thought of as a set of
labelled
+ states, connected by labelled transitions between those states.
Indeed,
+ a UML <em>State Diagram</em> 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.</p>
+
+ <p>Shale supports four state types, with specific implementations
+ realized as described below.</p>
+
+ <ul>
+ <li><em>ActionState</em> - 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 <em>method binding expression</em>, 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.</li>
+ <li><em>ViewState</em> - Represents the rendering of a JavaServer Faces
+ <em>view</em>, followed by a wait for the subsequent form submit.
+ The logical outcome returned by the action method (typically on
+ the <code>ViewController</code> bean that you've associated with
+ the current page) is used to drive the transition to the next
+ state, as described below.</li>
+ <li><em>SubdialogState</em> - 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.</li>
+ <li><em>EndState</em> - 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:
+ <ul>
+ <li>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).</li>
+ <li>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.</li>
+ </ul></li>
+ </ul>
+
+ <p>Transitions between states are performed by consulting the set of
+ <em>Transition</em>s 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).</p>
+
+ <p>It is <strong>not</strong> 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 <strong>dialog:xxxxx</strong>,
+ which will cause the dialog named <code>xxxxx</code> to be entered
+ at its starting state. Once that dialog completes, standard
+ JavaServer Faces navigation will resume.</p>
+
+ <p>The configuration of a Dialog is represented as a tree of
+ JavaBeans defined in the <code>org.apache.shale.dialog.model</code>
+ package, rooted at an instance <code>Dialog</code>. The set of
+ all known <code>Dialog</code> instances is stored in a
<code>Map</code>,
+ keyed by dialog identifier, which is stored in an application scope
+ attribute named by symbolic constant <code>Globals.DIALOGS</code>.
+ The <code>Dialog</code> 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.</p>
+
+ </subsection>
+
+ <a name="dialog-basic-using"/>
+ <subsection name="Using Dialog Manager (Basic Implementation)">
+
+ <p>To use the Dialog Manager facilities in Shale, take the following
+ steps:</p>
+
+ <ul>
+ <li>Model your dialog as a series of <em>State</em>s 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.</li>
+ <li>Build the views (and corresponding <code>ViewController</code>
beans,
+ if you are also using the <a href="../shale-view/index.html">
+ Shale View Controller Support</a> functionality)
+ that comprise your dialog, using standard JavaServer Faces and
+ (optional) Shale <code>ViewController</code> facilities.</li>
+ <li>Define your dialogs in an XML document, conventionally named
+ <code>/WEB-INF/dialog-config.xml</code>, that conforms to the
+ required DTD, which defines all the state transitions:
+<source>
+<!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>
+</source></li>
+ <li>Note that the <a
href="http://shale.apache.org/dtds/dialog-config_1_1.dtd";>
+ DTD referenced above</a> has thorough documentation on all of the
+ supported XML elements and attributes.</li>
+ <li>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:
+<source>
+<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>
+</source></li>
+ <li>In addition to the dialog configuration resources defined by this
+ context initialization parameter, a resource named
+ <code>/WEB-INF/dialog-config.xml</code> will be automatically
+ processed, if it exists, and has not already been loaded.</li>
+ <li>Alternatively, or in addition to the above, any JAR file in
+ <code>/WEB-INF/lib</code> will be scanned for configuration
+ documents at <code>META-INF/dialog-config.xml</code>. 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.</li>
+ <li>To initiate a dialog named "xxxxx", use one of the techniques
+ defined by the <a
href="../shale-dialog/index.html#dialog-using">
+ Shale Dialog Manager</a>.</li>
+ </ul>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
Propchange: shale/framework/trunk/shale-dialog-basic/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: shale/framework/trunk/shale-dialog-basic/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
