commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/web package.html
Date Fri, 30 Nov 2001 02:02:16 GMT
craigmcc    01/11/29 18:02:16

  Modified:    workflow/src/java/org/apache/commons/workflow/core
                        package.html
               workflow/src/java/org/apache/commons/workflow/io
                        package.html
               workflow/src/java/org/apache/commons/workflow/web
                        package.html
  Log:
  Finish updating the basic documentation for existing Step implementations.
  
  Revision  Changes    Path
  1.6       +1 -0      jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/core/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/core/package.html,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- package.html	2001/11/25 06:20:58	1.5
  +++ package.html	2001/11/30 02:02:16	1.6
  @@ -19,6 +19,7 @@
   as in the following example:</p>
   <pre>
     &lt;base:activity id="Demonstration Activity"
  +    xmlns:base="http://jakarta.apache.org/commons/workflow/base"
       xmlns:core="http://jakarta.apache.org/commons/workflow/core"
     &gt;
   
  
  
  
  1.3       +1 -0      jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/io/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/io/package.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- package.html	2001/11/25 06:20:58	1.2
  +++ package.html	2001/11/30 02:02:16	1.3
  @@ -17,6 +17,7 @@
   as in the following example:</p>
   <pre>
     &lt;base:activity id="Demonstration Activity"
  +    xmlns:base="http://jakarta.apache.org/commons/workflow/base"
       xmlns:core="http://jakarta.apache.org/commons/workflow/core"
       xmlns:io="http://jakarta.apache.org/commons/workflow/io"
     &gt;
  
  
  
  1.2       +202 -17   jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/web/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/web/package.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- package.html	2001/08/13 21:18:26	1.1
  +++ package.html	2001/11/30 02:02:16	1.2
  @@ -1,21 +1,206 @@
   <body>
  -<p>Implementations of <code>Steps</code> in the <code>web</code>
  -namespace, and web layer <code>Context</code> and <code>Scope</code>
  -implementations.</p>
  -
  -<p>This package contains the following sets of classes:</p>
  -<ul>
  -<li><strong>WebContext</strong> - Implementation of <code>Context</code>
  -    that is suitable for use in a web application based on the Servlet 2.2
  -    or later APIs.</li>
  -<li><strong>XxxxxScope</strong> - Implementations of <code>Scope</code>
  -    that map to the attributes associated with a <code>ServletRequest</code>,
  -    <code>HttpSession</code>, and <code>ServletContext</code>.</li>
  -<li><strong>XxxxxStep</strong> - Implementations of <code>Step</code>
  -    for tasks that are useful in web applications, and rely on the APIs
  -    defined in Servlet 2.2 (or later) and/or JSP 1.1 (or later).</li>
  +<p>Implementations of <code>Steps</code> in the <em>web</em>
library.</p>
  +
  +<div align="center">
  +<h2>Web Step Library - Overview</h2>
  +</div>
  +
  +<p>This package contains
  +<a href="../Step.html">org.apache.commons.workflow.Step</a> implementations
  +for the <em>web</em> library.  This library includes Steps for that are
  +executed in a web application, utilizing the
  +<code>org.apache.commons.workflow.web.WebContext</code> implementation
  +of Context.  Utilizing this feature makes the request, session, and
  +application scope attributes of the servlet API available to workflows
  +as Scopes named "request", "session", and "application", respectively.</p>
  +
  +<p>The sections below define each of the Step definitions included in this
  +library, utilizing the XML syntax that is recognized by the Digester used to
  +process your Activity definition files.  Although you can use any namespace
  +prefix, the convention is to declare <code>io</code> as the namespace prefix,
  +as in the following example:</p>
  +<pre>
  +  &lt;base:activity id="Demonstration Activity"
  +    xmlns:base="http://jakarta.apache.org/commons/workflow/base"
  +    xmlns:core="http://jakarta.apache.org/commons/workflow/core"
  +    xmlns:web="http://jakarta.apache.org/commons/workflow/web"
  +  &gt;
  +
  +    &lt;web:forward page="/mainMenu.jsp"/&gt;
  +
  +  &lt;/base:activity&gt;
  +</pre>
  +
  +<p><em>NOTE</em> - It is <strong>not</strong> required that
you use the XML
  +syntax, processed with a Digester, to initialize the Steps associated with
  +each Activity.  However, this usage is very convenient, and is likely to be
  +the most common case, so the Steps are documented from that perspective.  To
  +use the underlying implementation classes directly, see the Javadocs for each
  +Step implementation class, just as you would for any other Java class.</p>
  +
  +<div align="center">
  +[<a href="#web:forward">web:forward</a>]
  +[<a href="#web:goto">web:goto</a>]
  +[<a href="#web:include">web:include</a>]
  +[<a href="#web:populate">web:populate</a>]
  +</div>
  +
  +<div align="center">
  +<h2>Web Step Library - Step Definitions</h2>
  +</div>
  +
  +<a name="web:forward"></a>
  +<h3>web:forward</h3>
  +
  +<p>The <em>web:forward</em> Step performs a RequestDispatcher.forward()
  +call to the specified context-relative URL, and then tells our
  +Context to suspend execution until the application calls
  +<code>context.execute()</code> again.  This is useful in MVC-based
  +application architectures using a controller servlet to receive and
  +process all events.</p>
  +
  +<p>The <em>web:forward</em> element recognizes the following attributes:</p>
  +<ul>
  +<li><strong>id</strong> - Optional identifier of this Step, which can
be used
  +    as the destination for control transfers.  If specified, must be unique
  +    within the current Activity.</li>
  +<li><strong>page</strong> - Context-relative URL (starting with a slash)
  +    of the application resource to be forwarded to.  If not specified,
  +    the top value on the evaluation stack is popped, converted to a String
  +    (if necessary), and used as the context-relative URL value.</li>
  +</ul>
  +
  +
  +<a name="web:goto"></a>
  +<h3>web:goto</h3>
  +
  +<p>The <em>web:goto</em> Step unconditionally transfers control to the
  +Step that is identified by a request parameter with the specified name.</p>
  +
  +<p>The <em>web:goto</em> element recognizes the following attributes:</p>
  +<ul>
  +<li><strong>id</strong> - Optional identifier of this Step, which can
be used
  +    as the destination for control transfers.  If specified, must be unique
  +    within the current Activity.</li>
  +<li><strong>step</strong> - Name of a request parameter, which must be
  +    included in the current request, whose value is the identifier of the
  +    Step (within the current Activity) to which control should be transferred.
  +    If not specified, a request parameter named <code>step</code> is used.</li>
  +</ul>
  +
  +<a name="web:include"></a>
  +<h3>web:include</h3>
  +
  +<p>The <em>web:include</em> Step performs a
  +<code>RequestDispatcher.include()</code> operation on the specified
  +context-relative path, and pushes the response data (as a String) on to
  +the evaluation stack.  <strong>WARNING</strong> - This Step is only available
  +on servlet contiainers implementing the Servlet 2.3 (or later) specification,
  +because it uses the new response wrapper facilities.</p>
  +
  +<p>The <em>web:include</em> element recognizes the following attributes:</p>
  +<ul>
  +<li><strong>id</strong> - Optional identifier of this Step, which can
be used
  +    as the destination for control transfers.  If specified, must be unique
  +    within the current Activity.</li>
  +<li><strong>page</strong> - Context-relative URL (starting with a slash)
  +    of the application resource to be included.  If not specified,
  +    the top value on the evaluation stack is popped, converted to a String
  +    (if necessary), and used as the context-relative URL value.</li>
  +</ul>
  +
  +
  +<a name="web:populate"></a>
  +<h3>web:populate</h3>
  +
  +<p>The <em>web:populate</em> Step, for each nested Descriptor, populates
the
  +properties of the bean specified by that Descriptor from the request parameters
  +of the current request.</p>
  +
  +<p>The <em>web:populate</em> element recognizes the following attributes:</p>
  +<ul>
  +<li><strong>id</strong> - Optional identifier of this Step, which can
be used
  +    as the destination for control transfers.  If specified, must be unique
  +    within the current Activity.</li>
  +</ul>
  +
  +<p>You may nest any number of <a href="#web:descriptor">io:descriptor</a>
  +elements within a <em>web:populate</em> element.  All of them will be evaluated
  +and displayed in order specified.</p>
  +
  +<p>In the example below, the request parameters included with the current
  +request are used to populate the properties of an OrderBean stored under
  +the identifier "order".</p>
  +<pre>
  +  <strong>&lt;web:populate&gt;</strong>
  +    &lt;web:descriptor xpath="order"/&gt;
  +  <strong>&lt;/web:populate&gt;</strong>
  +</pre>
  +
  +
  +<div align="center">
  +<h2>Web Step Library - Nested Elements</h2>
  +</div>
  +
  +<a name="web:descriptor"></a>
  +<h3>web:descriptor</h3>
  +
  +<p>An <em>web:descriptor</em> element is a description of the mechanism
  +by which an arbitrary Java object (typically a JavaBean) in some Scope, is
  +referenced.  This element recognizes the following attributes:</p>
  +<ul>
  +<li><strong>name</strong> - The name under which this bean is stored,
  +    optionally located in the Scope specified by the <code>scope</code>
  +    attribute.</li>
  +<li><strong>scope</strong> - The name of the Scope within which to
  +    search for the bean named by the <code>name</code> attribute.  If
  +    not specified, the corresponding bean will be searched for in all Scopes,
  +    in ascending numeric order.</li>
  +<li><strong>type</strong> - Fully qualified Java class name that is expected
  +    (or set) via this descriptor.  If not specified, the actual Java class of the
  +    corresponding bean will be used.  This is useful, for example, when
  +    specifying the arguments to a <a href="#web:invoke">web:invoke</a>
  +    Step, and the invoked method expects a Java interface that is implemented
  +    by the actual object being passed as a parameter.</li>
  +<li><strong>xpath</strong> - An alternative method (to the <code>name</code>
  +    and <code>scope</code> attributes) for specifying the bean instance to
be
  +    accessed by this descriptor.</li>
   </ul>
  +
  +<p>The syntax for XPath expressions is a sequence of one or more
  +identifier strings, separated by forward slash ("/") characters.  The expression
  +is evaluated as follows:</p>
  +<ul>
  +<li>If no slashes are present, the expression is assumed to be the name
  +    of an object that is stored in the "local" scope.</li>
  +<li>If one slash is present, the value before the slash is assumed to be the
  +    name of the scope in which to locate the bean, while the value after the
  +    slash is the name under which the bean is stored in that scope.  For
  +    example, the WebContext implementation of Context (commonly used
  +    when implementing Workflow in a servlet based environment), the scope
  +    names "request", "session", and "application" correspond to the
  +    request attributes, session attributes, and servlet context attributes
  +    provided by the underlying servlet container.</li>
  +<li>If more than one slash is present, the value before the first slash
  +    is interpreted as a scope name, as above.  The remainder of the
  +    expression accessed nested properties of beans, according to the
  +    syntax specified by the Commons JXPath package.</li>
  +</ul>
  +
  +<p>When deciding what bean a particular descriptor applies to, the following
  +rules are applied, in this priority order:</p>
  +<ul>
  +<li>If the <em>xpath</em> attribute is set, it is used as an
  +    XPath expression identifying the requested object.</li>
  +<li>If the <em>name</em> (and optional <em>scope</em>) attributes
are
  +    specified, they are used to select a particular named bean,
  +    optionally found in a particular named scope.</li>
  +<li>If none of the conditions above are satisfied, the top object on the
  +    evaluation stack of our current <code>Context</code> is popped off the
  +    stack and consumed.</li>
  +</ul>
  +
  +<p><strong>FIXME</strong> - Support the <code>property</code>
attribute
  +for access to bean properties via the Commons Beanutils package.</p>
   
  -<p>By convention, the <code>Steps</code> in this package are exposed
as part
  -of the <code>web</code> namespace in configuration files.</p>
   </body>
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message