You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shale.apache.org by cr...@apache.org on 2006/10/13 22:58:00 UTC
svn commit: r463822 - in /shale/framework/trunk/shale-dialog/src/site: ./
site.xml xdoc/ xdoc/index.xml
Author: craigmcc
Date: Fri Oct 13 13:57:59 2006
New Revision: 463822
URL: http://svn.apache.org/viewvc?view=rev&rev=463822
Log:
Begin documenting the new Dialog Manager functionality.
SHALE-300
Added:
shale/framework/trunk/shale-dialog/src/site/
shale/framework/trunk/shale-dialog/src/site/site.xml (with props)
shale/framework/trunk/shale-dialog/src/site/xdoc/
shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml (with props)
Added: shale/framework/trunk/shale-dialog/src/site/site.xml
URL: http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog/src/site/site.xml?view=auto&rev=463822
==============================================================================
--- shale/framework/trunk/shale-dialog/src/site/site.xml (added)
+++ shale/framework/trunk/shale-dialog/src/site/site.xml Fri Oct 13 13:57:59 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/src/site/site.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: shale/framework/trunk/shale-dialog/src/site/site.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Added: shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml?view=auto&rev=463822
==============================================================================
--- shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml (added)
+++ shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml Fri Oct 13 13:57:59 2006
@@ -0,0 +1,213 @@
+<?xml version="1.0"?>
+<document>
+
+ <properties>
+ <title>Shale Dialog Manager</title>
+ </properties>
+
+ <body>
+
+ <section name="Shale Dialog Manager">
+ <a name="dialog"/>
+
+ <a name="dialog-introduction"/>
+ <subsection name="Introduction">
+
+ <p>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 <em>front controller</em> design pattern, have
+ become the de facto standard architectural approach.</p>
+
+ <p>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 <code>javax.faces.application.NavigationHandler</code>. 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:</p>
+
+ <ul>
+ <li>What view is currently processing this form submit?</li>
+ <li>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.)</li>
+ <li>What "logical outcome" was returned by the action that was
+ invoked?</li>
+ </ul>
+
+ <p>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 <code>Action.execute()</code> methods
+ that return a logical <code>ActionForward</code> describing the
+ outcome of performing the action.</p>
+
+ <p>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.</p>
+
+ <p>The functionality of this feature 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>
+
+ </subsection>
+
+ <a name="dialog-api"/>
+ <subsection name="API and Implementations">
+
+ <p>The Shale <em>Dialog Manager</em> defines an API that supports
+ access to an abstract "execution engine" that manages the processing
+ flow through a dialog. In addition, multiple implementations of this
+ API are provided that offer different sets of unique features:</p>
+
+ <ul>
+ <li><a href="../shale-dialog-basic/index.html">Basic Implementation</a>
+ A relatively simple implementation that models a dialog as a
+ state diagram with four types of states:
+ <ul>
+ <li><em>Action</em> - Execute an arbitrary method</li>
+ <li><em>Exit</em> - Terminate execution of this dialog</li>
+ <li><em>Subdialog</em> - Execute another dialog as a
+ subroutine</li>
+ <li><em>View</em> - Display a JSF view (page) and wait
+ for the following submit to execute an application
+ action method</li>
+ </ul>
+ This implementation supports a superset of the functionality
+ that was present in versions of Shale up through 1.0.3.</li>
+ <li><a href="../shale-dialog-scxml/index.html">State Chart XML
+ Implementation</a> A more sophisticated implementation based
+ on state charts modelled with <a href="http://www.w3.org/TR/scxml/">
+ State Chart XML</a>, which is currently a Working Draft published
+ by the W3C. This technology has grown out of the use of similar
+ techniques in the telephony industry, and Shale uses the
+ <a href="http://jakarta.apache.org/commons/scxml">Jakarta
+ Commons SCXML</a> library to provide the required execution
+ engine.</li>
+ </ul>
+
+ <p>The remainder of this document describes services that are available
+ no matter which implementation you choose. See the module descriptions
+ for the implementation modules for details of configuration, as well as
+ the unique features provided by that implementation.</p>
+
+ </subsection>
+
+ <a name="dialog-services"/>
+ <subsection name="Services Provided">
+
+ <p>The fundamental APIs that an application interacts with are
+ simple and straightforward:</p>
+ <ul>
+ <li><a href="apidocs/org/apache/shale/dialog/DialogContext.html">
+ DialogContext</a> - Represents the state of an active dialog
+ with the user. There will be one such instance for each
+ window or frame running a dialog, stored in session scope.</li>
+ <li><a href="apidocs/org/apache/shale/dialog/DialogContextManager.html">
+ DialogContextFactory</a> - Factory for creating new
+ <code>DialogContext</code> instances. The Shale Dialog implementation
+ that you select will provide a suitable factory as a session scope
+ managed bean under a well-known key. At most one active
+ <code>DialogContext</code> instance can be associated with
+ each window or frame that the user is operating, in association
+ with the same session.</li>
+ <li><a href="apidocs/org/apache/shale/dialog/DialogListener">
+ DialogListener.html</a> - An active <code>DialogContext</code>
+ fires events that document interesting changes in the state of
+ the dialog. Interested objects can ask to be notified of such
+ events by implementing this interface, and registering themselves
+ with the <code>DialogContext</code> using standard JavaBeans
+ event listener design patterns.</li>
+ </ul>
+
+ <p><a href="apidocs/org/apache/shale/dialog/DialogContextManager.html">
+ DialogContextManager</a> provides public methods that support the
+ following functionality:</p>
+ <ul>
+ <li>Create and return a new <code>DialogContext</code> instance,
+ optionally associated with a parent <code>DialogContext</code>
+ (useful for popup windows that need to coordinate their
+ behavior with the underlying page).</li>
+ <li>Retrieve an active <code>DialogContext</code> for the current
+ user, based on a specified dialog identifier.</li>
+ <li>Remove an active <code>DialogContext</code> instance,
+ denoting that this instance is no longer active. As a
+ side effect, the content of the <code>data</code> property
+ of this <code>DialogContext</code> will be made available
+ for garbage collection, as long as the application does not
+ maintain any other references to the data object.</li>
+ </ul>
+
+ <p><a href="apidocs/org/apache/shale/dialog/DialogContext.html">
+ DialogContext</a> provides the following public properties:</p>
+ <ul>
+ <li><code>active</code> - Flag indicating that this
+ <code>DialogContext</code> instance has been started
+ but not yet stopped.</li>
+ <li><code>data</code> - General purpose object made available
+ for storing state information related to a particular
+ active dialog instance. Details of how this property
+ is implemented are specific to the implementation you
+ choose, but will generally default to being an instance
+ of <code>java.util.Map</code>. You can also replace
+ this object at runtime with an object that contains
+ state properties specific to a particular use case.</li>
+ <li><code>id</code> - An identifier, unique within the scope
+ of the current user, for this particular instance.
+ The Dialog Manager framework promises to transport
+ this identifier along with the JSF component tree,
+ and will use it to regain access to the corresponding
+ <code>DialogContext</code> instance on a postback.</li>
+ <li><code>name</code> - The logical name of the dialog
+ definition being executed by this instance. This
+ will typically map to configuration information that
+ is specific to the implementation you select.</li>
+ <li><code>parent</code> - Optional reference to a parent
+ <code>DialogContext</code> instance that we were
+ associated with when this instance was created.</li>
+ </ul>
+
+ <p><a href="apidocs/org/apache/shale/dialog/DialogContext.html">
+ DialogContext</a> provides public methods to support the following
+ functionality:</p>
+ <ul>
+ <li>Start the active execution represented by this instance,
+ advancing until the instance has displayed a JSF view
+ and needs to wait for the user to fill out a form and
+ submit it.</li>
+ <li>Advance the state of the computation represented by
+ this instance, passing in the logical outcome that
+ was returned by the application's action method.</li>
+ <li>Stop the execution of the computation represented by
+ this instance, which will cause it to be passed to
+ the <code>remove()</code> method on the
+ <code>DialogContextManager</code> instance for this user.</li>
+ </ul>
+
+ <p>FIXME - document the events stuff.</p>
+
+ </subsection>
+
+ <a name="dialog-using"/>
+ <subsection name="Using Dialog Manager">
+
+ <p>FIXME - document idioms for using Dialog Manager.</p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
Propchange: shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL