Author: craigmcc
Date: Mon Nov 21 14:51:42 2005
New Revision: 348006
URL: http://svn.apache.org/viewcvs?rev=348006&view=rev
Log:
Flesh out description of the Application Manager feature.
Modified:
struts/shale/trunk/xdocs/features-application-manager.xml
Modified: struts/shale/trunk/xdocs/features-application-manager.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/features-application-manager.xml?rev=348006&r1=348005&r2=348006&view=diff
==============================================================================
--- struts/shale/trunk/xdocs/features-application-manager.xml (original)
+++ struts/shale/trunk/xdocs/features-application-manager.xml Mon Nov 21
14:51:42 2005
@@ -10,7 +10,168 @@
<section name="Shale Application Manager">
<a name="application"/>
- <p>FIXME - Describe application manager feature.</p>
+ <a name="application-introduction"/>
+ <subsection name="Introduction">
+
+ <p>Much has been made of the fact that JavaServer Faces promotes
+ a <em>page oriented</em> architecture for applications, typically
+ associating a request scoped "backing bean" with each page to contain
+ event handlers and/or submitted values. Indeed, Shale itself offers
+ extended support for this paradigm by virtue of its
+ <a href="features-view-controller.html">View Controller</a> feature.
+ This is in contrast to the <em>action oriented</em> architecture
+ typically found in web application frameworks ike
+ <a href="http://struts.apache.org/";>Struts 1.x</a>.</p>
+
+ <p>A second aspect of action oriented frameworks, however, is also
+ useful. They typically implement an application level
+ <em>controller</em> (in the sense of the Model/View/Controller
+ design pattern) through which <strong>all</strong> HTTP requests to
+ the application are funneled. Various frameworks offer mechanisms
+ to customize the lifecycle processing that is performed, for example:
+ </p>
+ <ul>
+ <li>In Struts 1.1-1.2, you subclass <code>RequestProcessor</code>
+ and override the processXxx() series of methods that perform the
+ actual processing of the request.</li>
+ <li>In Struts 1.3, you customize the Commons Chain command pipeline
+ that implements the standard request processing lifecycle.</li>
+ <li>In JavaServer Faces, you can insert <code>PhaseListener</code>
+ instances that receive control before or after the standard
+ phases of the request processing lifecycle, which can exert
+ control over what happens next.</li>
+ </ul>
+
+ <p>Shale, being based upon JavaServer Faces, supports the standard
+ <code>PhaseListener</code> approach to customizing the request
+ processing lifecycle. However, it also supports <em>Application
+ Manager</em> functionality that can customize processing before
+ or after the standard JavaServer Faces lifecycle, as described below.
+ </p>
+
+ </subsection>
+
+ <a name="application-services"/>
+ <subsection name="Services Provided">
+
+ <p>The <em>Application Manager</em> feature of Shale
+ provides application wide services as described below:</p>
+
+ <h4>(A) Standard Per-Request Processing</h4>
+
+ <p>As described in <a href="using.html#using-configuring">Configuring
+ Your Application For Shale</a>, you are requested to configure a
+ <em>Servlet Filter</em>
+ (<code>org.apache.shale.faces.ShaleApplicationFilter</code>) and
+ map it to process incoming URLs (typically using the URL pattern
+ <code>/*</code> to process all requests to this application).
+ This filter receives control both <strong>before</strong> and
+ <strong>after</strong> the standard JavaServer Faces request
+ processing lifecycle (which is implemented as a servlet).</p>
+
+ <p><code>ShaleApplicationFilter</code> imposes a standard request
+ processing lifecycle using
+ <a href="http://jakarta.apache.org/commons/chain/";>Commons Chain</a>
+ technology, which provides both preprocessing and postprocessing
+ hooks where the application developer can plug in additional
+ behavior at these two points in time. The following processing
+ is performed for each request:</p>
+ <ul>
+ <li>Construct an instance of <code>ShaleWebContext</code> (which
+ implements the Commons Chain <code>Context</code> interface)
+ to represent the current request. This instance will be passed
+ in to any Commons Chain commands involved in processing
+ the current request.</li>
+ <li>Store the <code>ShaleWebContext</code> instance as a request
+ scope attribute under the key identified by manifest constant
+ <code>ShaleApplicationFilter.CONTEXT_ATTR</code> so that it
+ is available to later processing stages.</li>
+ <li>Check for a Commons Chain <code>Command</code> instance named
+ <code>preprocess</code> in the <code>shale</code> catalog. If
+ such a command (or chain) exists:
+ <ul>
+ <li>Execute the command or chain, rethrowing any
+ exception that might occur.</li>
+ <li>If the executed command or chain returned <code>true</code>
+ (indicating that processing for the entire request should
+ be considered complete), remove the request scope attribute
+ that was added and earlier, and exit.</li>
+ </ul></li>
+ <li>Call <code>doFilter()</code> on the <code>FilterChain</code>
+ argument passed in, which will ultimately trigger the standard
+ JavaServer Faces processing when the incoming URL is mapped to
+ <code>FacesServlet</code>.</li>
+ <li>Check for a Commons Chain <code>Command</code> instance named
+ <code>postprocess</code> in the <code>shale</code> catalog.
+ If such a command (or chain) exists, execute it.</li>
+ <li>Clean up the request scope attribute stored earlier.</li>
+ </ul>
+
+ <h4>(B) Preprocess and Postprocess Basic Implementations</h4>
+
+ <p>In addition to the standard request processing lifecycle described
+ in the previous section, Shale offers an abstract base class
+ <a
href="shale-core/apidocs/org/apache/shale/application/AbstractRegExpFilter.html">
+ org.apache.shale.application.AbstractReqExpFilter</a>
+ suitable for developing <code>preprocess</code> commands that perform
+ request filtering based on matching incoming request values to
+ regular expressions. See the Javadocs for this class for more
+ information.</p>
+
+ <p>Three concrete implementations based on this abstract base class
+ are also provided:</p>
+ <ul>
+ <li><a
href="shale-core/apidocs/org/apache/shale/application/ContextRelativePathFilter.html">
+ ContextRelativePathFilter</a> - Filters requests by matching the
+ context relative portion of the path (i.e. starting with the slash
+ after the context path itself) against one or more regular
+ expressions.</li>
+ <li><a
href="shale-core/apidocs/org/apache/shale/application/RemoteAddrFilter.html">
+ RemoteAddrFilter</a> - Filters requests by matching the IP address
+ of the remote client against one or more regular expressions.</li>
+ <li><a
href="shale-core/apidocs/org/apache/shale/application/RemoteHostFilter.html">
+ RemoteHostFilter</a> - Filters requests by matching the hostname
+ of the remote client against one or more regular expressions.</li>
+ </ul>
+
+ </subsection>
+
+ <a name="application-using"/>
+ <subsection name="Using Application Manager">
+
+ <p>The <em>Use Cases</em> example application incorporates the
+ <code>ContextRelativePathFilter</code> described above, using it
+ to disallow direct access to JSP pages by URLs manually typed in
+ to the browser. This is accomplished by the following configuration
+ stored in the <code>WEB-INF/chain-config.xml</code> resource:</p>
+
+<source>
+ <catalogs>
+
+ <catalog name="shale">
+
+ ...
+
+ <command
className="org.apache.shale.application.ContextRelativePathFilter"
+ includes="\S*\.xml,\S*\.faces,\S*\.html,\S*\.gif,\S*\.jpg,index\.jsp"
+ excludes="\S*\.jsp,\S*\.jspf"/>
+
+ ...
+
+ </catalog>
+
+ </catalogs>
+</source>
+
+<p>The <code>ContextRelativePathFilter</code> instance is configured to pass
+through context relative paths that match one of the regular expressions in
+the <code>includes</code> attribute, while disallowing access for context
+relative paths that match one of the regular expressions in the
+<code>excludes</code> list. With these settings, direct access to any URL
+ending in <code>.jsp</code> or <code>.jspf</code> (other than to a resource
+named <code>index.jsp</code>) will be prevented.</p>
+
+ </subsection>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
