Author: craigmcc
Date: Sat Dec 2 11:49:06 2006
New Revision: 481613
URL: http://svn.apache.org/viewvc?view=rev&rev=481613
Log:
Update the package summary javadocs to document configuring the new
"include" and "exclude" constraints on resource identifiers, including
the default values. Added pointers to this from the website page.
SHALE-344
Modified:
shale/framework/trunk/shale-remoting/src/main/java/org/apache/shale/remoting/package.html
shale/framework/trunk/shale-remoting/src/site/xdoc/index.xml
Modified:
shale/framework/trunk/shale-remoting/src/main/java/org/apache/shale/remoting/package.html
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-remoting/src/main/java/org/apache/shale/remoting/package.html?view=diff&rev=481613&r1=481612&r2=481613
==============================================================================
---
shale/framework/trunk/shale-remoting/src/main/java/org/apache/shale/remoting/package.html
(original)
+++
shale/framework/trunk/shale-remoting/src/main/java/org/apache/shale/remoting/package.html
Sat Dec 2 11:49:06 2006
@@ -30,7 +30,9 @@
<a href="Processor.html">Processor</a> instance, which can take complete
responsibility for creating the response for this request (and then
calling <code>FacesContext.responseComplete()</code> to tell JSF this has been
-done).</p>
+done). In addition, <a href="Processor.html">Processor</a> instances can be
+configured to limit the set of resource identifiers which they provide access
+to, by pattern matching against "include" and "exclude" pattern lists.</p>
<h3>Concrete Processor Implementations</h3>
@@ -68,9 +70,11 @@
<p>The static resource serving <a href="Processor.html">Processor</a>
implentations
share the following features:</p>
<ul>
- <li>Disallow access to prohibited resources (web application resources
- under <code>/WEB-INF</code> or <code>/META-INF</code>, Java class
+ <li>Unconditionally disallow access to prohibited resources (web
application
+ resources under <code>/WEB-INF</code> or <code>/META-INF</code>, Java
class
files, and JSP source files).</li>
+ <li>Conditionally allow or disallow access to other resources based on
+ include and exclude pattern lists.</li>
<li>Set the content type of the response based on the extension portion
of the resource identifier. This is done by first consulting the
servlet or portlet container (which supports mapping of extensions
@@ -182,6 +186,126 @@
</context-param>
</pre></blockquote>
</p>
+
+<p>Conditional access controls for a specific <a
href="Processor.html">Processor</a>
+implementation are described by configuring comma-delimited lists of patterns
+(either "/foo/*" style or "*.foo" style) that are matched against the
+<em>resource id</em> part of the request URL. The standard algorithm applied
+by the provided implementations (via base class <a
href="FilteringProcessor.html">
+FilteringProcessor</a>) works as follows:</p>
+<ul>
+<li>If there is an "excludes" list for this processor, and the resource id
+ portion of the request URL matches one of these patterns, reject the
+ request by returning an HTTP 404 (not found) status.</li>
+<li>If there is an "includes" list for this processor, and the resource id
+ portion of the request URL matches one of these patterns, perform the
+ processing required to deliver the requested response.</li>
+<li>If there is an "includes" list for this processor, and we reached this
+ point, reject the request by returning an HTTP 404 (not found) status,
+ because the resource URL did not match one of the "include" patterns.</li>
+<li>Because we did not reject the resource id for an "excludes" list match,
+ and there was no "includes" list, perform the processing required to
+ deliver the requested response.</li>
+</ul>
+
+<p>Unless explicitly configured differently, the context init parameters shown
+below contain default values that will be used for include and exclude
patterns:</p>
+<p><blockquote><pre>
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.CLASS_RESOURCES_EXCLUDES
+ </param-name>
+ <param-value>
+ *.class,*.jsp,*.properties
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.CLASS_RESOURCES_INCLUDES
+ </param-name>
+ <param-value>
+ *.css,*.gif,*.html,*.jpg,*.js,*.png,*.xml
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.DYNAMIC_RESOURCES_EXCLUDES
+ </param-name>
+ <param-value>
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.DYNAMIC_RESOURCES_INCLUDES
+ </param-name>
+ <param-value>
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.DYNAMIC_RESOURCES_EXCLUDES
+ </param-name>
+ <param-value>
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.DYNAMIC_RESOURCES_INCLUDES
+ </param-name>
+ <param-value>
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.OTHER_RESOURCES_EXCLUDES
+ </param-name>
+ <param-value>
+ *.class,*.jsp,*.properties
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.OTHER_RESOURCES_INCLUDES
+ </param-name>
+ <param-value>
+ *.css,*.gif,*.html,*.jpg,*.js,*.png,*.xml
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.WEBAPP_RESOURCES_EXCLUDES
+ </param-name>
+ <param-value>
+ *.class,*.jsp,*.properties
+ </param-value>
+</context-param>
+
+<context-param>
+ <param-name>
+ org.apache.shale.remoting.WEBAPP_RESOURCES_INCLUDES
+ </param-name>
+ <param-value>
+ *.css,*.gif,*.html,*.jpg,*.js,*.png,*.xml
+ </param-value>
+</context-param>
+
+</pre></blockquote></p>
+
+<p><strong>SECURITY NOTE</strong> - Note that, by default, no conditional
+restrictions are placed on the managed bean names and public zero-argument
+method names referenced by the method binding processor. You will generally
+want to restrict access to methods only on those managed beans explicitly
+designed to retrieve such callbacks. So, if your application has managed beans
+"foo" and "bar" that should allow access, you might set the
DYNAMIC_RESOURCES_INCLUDES
+parameter to <code>/foo/*,/bar/*</code> to enforce these restrictions.</p>
<p>In addition, you can configure the following additional context
initialization
parameters:</p>
Modified: shale/framework/trunk/shale-remoting/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-remoting/src/site/xdoc/index.xml?view=diff&rev=481613&r1=481612&r2=481613
==============================================================================
--- shale/framework/trunk/shale-remoting/src/site/xdoc/index.xml (original)
+++ shale/framework/trunk/shale-remoting/src/site/xdoc/index.xml Sat Dec 2
11:49:06 2006
@@ -52,12 +52,29 @@
</li>
</ul>
+ <p>Complete information on the functionality provided by Shale
Remoting
+ may be found in the
+ <a href="apidocs/org/apache/shale/remoting/package-summary.html">
+ Javadoc package summary</a> for this module.</p>
+
</subsection>
- <a name="remoting-static-resources"/>
- <subsection name="Accessing Static Resources">
- FIXME
+ <a name="remoting-static"/>
+ <subsection name="Remotely Accessing Static Resources">
+
+ <p>Shale can map URLs to "classpath" resources (those found in
+ <code>/WEB-INF/classes</code>, or in a JAR file found in
+ <code>/WEB-INF/lib</code>. This makes it very easy, for example,
+ for a JSF component library to embed JavaScript and CSS stylesheet
+ resources required by its components, within the same JAR file,
+ without requiring the application developer to explicitly configure
+ anything, or place component resources at any particular point in
+ the web application's document hierarchy. In addition, Shale can
+ map directly to webapp resources (equivalent to the static resource
+ serving capability of most servlet containers), if desired.</p>
+
</subsection>
+
<a name="remoting-methods"/>
<subsection name="Remotely Calling Managed Bean Methods">
