incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r841833 [22/28] - in /websites/staging/sling/trunk/content: ./ site/ site/46-line-blog.data/ site/authentication.data/ site/documentation.data/ site/first-steps.data/ site/getting-and-building-sling.data/ site/how-to-manage-events-in-sling....
Date Wed, 12 Dec 2012 09:17:17 GMT
Added: websites/staging/sling/trunk/content/site/repository-based-development.html
==============================================================================
--- websites/staging/sling/trunk/content/site/repository-based-development.html (added)
+++ websites/staging/sling/trunk/content/site/repository-based-development.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,196 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <HEAD>
+    <TITLE>Apache Sling - Repository Based Development</TITLE>
+    <LINK rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <LINK rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <META http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </HEAD>
+  <BODY>
+    <DIV class="title">
+      <DIV class="logo">
+        <A href="http://sling.apache.org/site/index.html">
+          <IMG border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </A>
+      </DIV>
+      <DIV class="header">
+        <A href="http://www.apache.org/">
+          <IMG border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </A>
+      </DIV>
+    </DIV>
+    <DIV class="menu">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="apache-sling.html" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="apache-sling.html" title="Apache Sling">Apache Sling</A>&nbsp;&gt;&nbsp;<A href="documentation.html" title="Documentation">Documentation</A>&nbsp;&gt;&nbsp;<A href="development.html" title="Development">Development</A>&nbsp;&gt;&nbsp;<A href="" title="Repository Based Development">Repository Based Development</A>
+        </DIV>
+<H1><A name="RepositoryBasedDevelopment-RepositoryBasedDevelopment"></A>Repository Based Development</H1>
+
+<DIV>
+<UL>
+    <LI><A href="#RepositoryBasedDevelopment-WebDAVSupport">WebDAV Support</A></LI>
+<UL>
+    <LI><A href="#RepositoryBasedDevelopment-Configuration">Configuration</A></LI>
+</UL>
+    <LI><A href="#RepositoryBasedDevelopment-EclipsepluginforJCR">Eclipse plugin for JCR</A></LI>
+</UL></DIV>
+
+<H2><A name="RepositoryBasedDevelopment-WebDAVSupport"></A>WebDAV Support</H2>
+
+<P>WebDAV support in Sling is based on the <A href="http://jackrabbit.apache.org/doc/components/jcr-server.html" class="external-link" rel="nofollow">Simple WebDAV</A> implementation of Apache Jackrabbit which is integrated in the <TT>jcr/webdav</TT> project. This bundle provides WebDAV access to Sling's repository in two flavours: (1) Access to all workspaces of the repository on a separate URL space &ndash; by default rooted at <TT>/dav</TT> in the Sling context &ndash; and (2) access to the workspace used by Sling itself at the root of the Sling context.</P>
+
+
+<H4><A name="RepositoryBasedDevelopment-Example"></A>Example</H4>
+
+<P>Consider Sling be installed on a Servlet container in the <TT>/sling</TT> context on <TT>some.host.net:8080</TT>. Here you would access the Sling workspace by directing your WebDAV client to the URL <TT><A href="http://some.host.net:8080/sling" class="external-link" rel="nofollow">http://some.host.net:8080/sling</A></TT>. To access the <TT>sample</TT> workspace, which is not used by Sling itself, you would direct your WebDAV client to the URL <TT><A href="http://some.host.net:8080/sling/dav/sample" class="external-link" rel="nofollow">http://some.host.net:8080/sling/dav/sample</A></TT>.</P>
+
+<P>Please note that accessing the repository in the separate URI space is actually faster, since requests do not pass the Sling resource and script resolution framework but instead hit the Jackrabbit Simple WebDAV Servlet directly.</P>
+
+
+<H4><A name="RepositoryBasedDevelopment-SeparateURISpaceWebDAV"></A>Separate URI Space WebDAV </H4>
+
+<P>When accessing the repository through WebDAV in its separate URI Space, the URLs have the following generic structure:</P>
+
+<DIV class="panel" style="border-width: 1px;"><DIV class="panelContent">
+<P>slingroot/prefix/workspace/item</P>
+</DIV></DIV>
+
+<UL>
+	<LI><TT><B>slingroot</B></TT> is the URL of the Sling web application context. In the above example, this would <TT><A href="http://some.host.net:8080/sling" class="external-link" rel="nofollow">http://some.host.net:8080/sling</A></TT>.</LI>
+	<LI><TT><B>prefix</B></TT> is the URL prefix to address the WebDAV servlet. By default this is set to <TT>/dav</TT> but may be configured to any valid path.</LI>
+	<LI><TT><B>workspace</B></TT> is the name of the workspace to be accessed through WebDAV.</LI>
+	<LI><TT><B>item</B></TT> is the path to the JCR Item to access.</LI>
+</UL>
+
+
+<P>If you access the WebDAV server at the prefix path &ndash; e.g. <TT>!http://localhost:8080/dav</TT> &ndash; you will be redirected to the default workspace with a temporary redirect status 302. Some clients, such as the Linux <EM>davfs</EM>, do not like this redirection and must be configured to explicitly address the default workspace.</P>
+
+
+<H3><A name="RepositoryBasedDevelopment-Configuration"></A>Configuration</H3>
+
+<P>The Jackrabbit Simple WebDAV support in Sling has the following configuration options:</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> Property </TH>
+<TH class="confluenceTh"> Default </TH>
+<TH class="confluenceTh"> Description </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> Root Path </TD>
+<TD class="confluenceTd"> <TT>/dav</TT> </TD>
+<TD class="confluenceTd"> The root path at which the Simple WebDAV Servlet is accessible. Access to the repository is provided in two ways. You may connect your WebDAV client directly to the root of the Sling web application to access the workspace of Sling directly. The other way is required if you want to connect your WebDAV client to any other workspace besides the Sling workspace. In this case you connect your WebDAV client to another a path comprised of this root path plus the name of the workspace. For example to connect to the <TT>some_other</TT> workspace, you might connect to {{
+<A href="http://slinghost/dav/some_other" class="external-link" rel="nofollow">http://slinghost/dav/some_other</A>
+<P>}}. </P></TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Authentication Realm	</TD>
+<TD class="confluenceTd"> <TT>Sling WebDAV</TT> </TD>
+<TD class="confluenceTd"> The name of the HTTP Basic Authentication Realm presented to the client to ask for authentication credentials to access the repository. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Non Collection Node Typee </TD>
+<TD class="confluenceTd"> [ <TT>nt:file</TT>, <TT>nt:resource</TT> ] </TD>
+<TD class="confluenceTd"> The JCR Node Types considered being non-collection resouces by WebDAV. Any node replying <TT>true</TT> to <TT>Node.isNodeType()</TT> for one of the listed types is considered a non-collection resource. Otherwise the respective node is considered a colleciton resource. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Filter Prefixes </TD>
+<TD class="confluenceTd"> [ <TT>jcr</TT>, <TT>rep</TT> ] </TD>
+<TD class="confluenceTd"> A list of namespace prefixes indicating JCR items filtered from being reported as collection members or properties. The default list includes jcr and rep (Jackrabbit internal namespace prefix) items. Do not modify this setting unless you know exactly what you are doing. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Filter Node Types </TD>
+<TD class="confluenceTd"> &ndash; </TD>
+<TD class="confluenceTd"> Nodetype names to be used to filter child nodes. A child node can be filtered if the declaring nodetype of its definition is one of the nodetype names specified in the nodetypes Element. E.g. defining rep:root as filtered nodetype whould result in jcr:system being hidden but no other child node of the root node, since those are defined by the nodetype nt:unstructered. The default is empty. Do not modify this setting unless you know exactly what you are doing. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Filter URIs </TD>
+<TD class="confluenceTd"> &ndash; </TD>
+<TD class="confluenceTd"> A list of namespace URIs indicating JCR items filtered from being reported as collection members or properties. The default list is empty. Do not modify this setting unless you know exactly what you are doing. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Collection Primary Type </TD>
+<TD class="confluenceTd"> <TT>sling:Folder</TT> </TD>
+<TD class="confluenceTd"> The JCR Primary Node Type to assign to nodes created to reflect WebDAV collections. You may name any primary node type here, provided it allows the creation of nodex of this type and the defined Non-Collection Primary Type below it. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Non-Collection Primary Type </TD>
+<TD class="confluenceTd"> <TT>nt:file</TT> </TD>
+<TD class="confluenceTd"> The JCR Primary Node Type to assign to nodes created to reflect WebDAV non-collection resources. You may name any primary node type here, provided the node type is allowed to be created below nodes of the type defined for the Collection Primary Type and that a child node with the name &quot;jcr:content&quot; may be created below the non-collection resource whose type is defined by the Content Primary Type. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Content Primary Type </TD>
+<TD class="confluenceTd"> <TT>nt:resource</TT> </TD>
+<TD class="confluenceTd"> The JCR Primary Node Type to assign to the jcr:content child node of a WebDAV non-collection resource. You may name any primary node type here, provided the node type is allowed to be created as the jcr:content child node of the node type defined by the Non-Collection Primary Type. In addition the node type must allow at least the following properties: jcr:data (binary), jcr:lastModified (date), and jcr:mimeType (string). </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<H4><A name="RepositoryBasedDevelopment-AdvancedTechnicalDetails"></A>Advanced Technical Details</H4>
+
+<P>Since the Jackrabbit Simple WebDAV Servlet is originally configured using an XML configuration file, which provides a great deal of flexibility, the integration into Sling had to assume some simplifications, of which some of the above parameters are part:</P>
+
+<P><B>IOManager</B></P>
+
+<P>This implementation uses the standard <TT>org.apache.jackrabbit.server.io.IOManagerImpl</TT> class and adds the <TT>org.apache.jackrabbit.server.io.DirListingExportHandler</TT> and <TT>org.apache.jackrabbit.server.io.DefaultHandler</TT> IO handlers as its only handlers. The <TT>DefaultHandler</TT> is configured from the three node types listed as configuration parameters above (collection, non-collection, and content primary node types).</P>
+
+<P><B>PropertyManager</B></P>
+
+<P>This implementation uses the standard <TT>org.apache.jackrabbit.server.io.PropertyManagerImpl</TT> and adds the same <TT>DirListingExportHandler</TT> and <TT>DefaultHanlder</TT> instances as its own handlers as are used by the IO Manager.</P>
+
+<P><B>ItemFilter</B></P>
+
+<P>This implementation uses the standard <TT>org.apache.jackrabbit.webdav.simple.DefaultItemFilter</TT> implementation as its item filter and configures the filter with the namespace prefixes and URIs as well as the node types configured as parameters.</P>
+
+<P><B>Collection Node Types</B></P>
+
+<P>This implementation only supports listing node types which are considered representing non-collection resources. All nodes which are instances of any of the configured node types are considered non-collection resources. All other nodes are considere collection resources.</P>
+
+
+<H2><A name="RepositoryBasedDevelopment-EclipsepluginforJCR"></A>Eclipse plugin for JCR</H2>
+
+<P>TBD</P>
+        <DIV class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by fmeschbe on 2008-12-11 06:16:49.0
+        </DIV>
+        <DIV class="trademarkFooter">
+Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+        </DIV>
+    </DIV>
+  </BODY>
+</HTML>
+

Added: websites/staging/sling/trunk/content/site/request-listeners.html
==============================================================================
--- websites/staging/sling/trunk/content/site/request-listeners.html (added)
+++ websites/staging/sling/trunk/content/site/request-listeners.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,114 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <HEAD>
+    <TITLE>Apache Sling - Request Listeners</TITLE>
+    <LINK rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <LINK rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <META http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </HEAD>
+  <BODY>
+    <DIV class="title">
+      <DIV class="logo">
+        <A href="http://sling.apache.org/site/index.html">
+          <IMG border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </A>
+      </DIV>
+      <DIV class="header">
+        <A href="http://www.apache.org/">
+          <IMG border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </A>
+      </DIV>
+    </DIV>
+    <DIV class="menu">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="apache-sling.html" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="apache-sling.html" title="Apache Sling">Apache Sling</A>&nbsp;&gt;&nbsp;<A href="documentation.html" title="Documentation">Documentation</A>&nbsp;&gt;&nbsp;<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A>&nbsp;&gt;&nbsp;<A href="" title="Request Listeners">Request Listeners</A>
+        </DIV>
+<H1><A name="RequestListeners-RequestListenersupport"></A>Request Listener support</H1>
+
+<P>Sling provides the possibility to &quot;listen&quot; to a request processed by the Sling Engine (<TT>SlingMainServlet</TT>). To get notified you implement the service interface <TT>org.apache.sling.api.request.SlingRequestListener</TT>.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>SlingRequestListener</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">interface</SPAN> SlingRequestListener {
+	
+	<SPAN class="code-keyword">static</SPAN> <SPAN class="code-keyword">final</SPAN> <SPAN class="code-object">String</SPAN> SERVICE_NAME = <SPAN class="code-quote">&quot;org.apache.sling.api.request.SlingRequestListener&quot;</SPAN>;	
+
+	/**
+	 * This method is called from the Sling application <SPAN class="code-keyword">for</SPAN> every
+	 * &lt;code&gt;EventType&lt;/code&gt; appearing during the dispatching of
+	 * a Sling request  
+	 * 
+	 * @param sre the object representing the event
+	 * 
+	 * @see org.apache.sling.api.request.SlingRequestEvent.EventType
+	 */
+	<SPAN class="code-keyword">public</SPAN> void onEvent( SlingRequestEvent sre );
+}
+</PRE>
+</DIV></DIV>
+
+<P>There are no special properties to set. </P>
+
+<H2><A name="RequestListeners-Supportedtypesofevents"></A>Supported types of events</H2>
+
+<P>At the moment you will get two different types of <TT>SlingRequestEvent</TT>:</P>
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> events types (<TT>SlingRequestEvent.EventType</TT>) </TH>
+<TH class="confluenceTh"> point in time </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> EVENT_INIT </TD>
+<TD class="confluenceTd"> after entering the <TT>service</TT> method in <TT>SlingMainServlet</TT>. Note that this will be <B>after</B> the <TT>handleSecurity</TT> call. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> EVENT_DESTROY </TD>
+<TD class="confluenceTd"> at the end of the <TT>service</TT> method in <TT>SlingMainServlet</TT> </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+        <DIV class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by mykee on 2010-07-09 03:46:21.0
+        </DIV>
+        <DIV class="trademarkFooter">
+Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+        </DIV>
+    </DIV>
+  </BODY>
+</HTML>
+

Added: websites/staging/sling/trunk/content/site/request-parameters.html
==============================================================================
--- websites/staging/sling/trunk/content/site/request-parameters.html (added)
+++ websites/staging/sling/trunk/content/site/request-parameters.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,181 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <HEAD>
+    <TITLE>Apache Sling - Request Parameters</TITLE>
+    <LINK rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <LINK rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <META http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </HEAD>
+  <BODY>
+    <DIV class="title">
+      <DIV class="logo">
+        <A href="http://sling.apache.org/site/index.html">
+          <IMG border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </A>
+      </DIV>
+      <DIV class="header">
+        <A href="http://www.apache.org/">
+          <IMG border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </A>
+      </DIV>
+    </DIV>
+    <DIV class="menu">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="apache-sling.html" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="apache-sling.html" title="Apache Sling">Apache Sling</A>&nbsp;&gt;&nbsp;<A href="documentation.html" title="Documentation">Documentation</A>&nbsp;&gt;&nbsp;<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A>&nbsp;&gt;&nbsp;<A href="" title="Request Parameters">Request Parameters</A>
+        </DIV>
+<H1><A name="RequestParameters-RequestParameterHandlinginSling"></A>Request Parameter Handling in Sling</H1>
+
+
+
+<H2><A name="RequestParameters-ServletAPI"></A>Servlet API</H2>
+
+<P>The Servlet API specification provides the following methods to access the parameters of a request</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TD class="confluenceTd"> <TT>HttpServletRequest.getQueryString()</TT> </TD>
+<TD class="confluenceTd"> Returns the query part of the request URL </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <TT>ServletRequest.getParameter(String)</TT> </TD>
+<TD class="confluenceTd"> Returns the (first) named parameter </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <TT>ServletRequest.getParameterValues(String)</TT> </TD>
+<TD class="confluenceTd"> Returns all parameters of that name </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <TT>ServletRequest.getParameterMap()</TT> </TD>
+<TD class="confluenceTd"> Returns all parameters as a map of <TT>String[]</TT> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <TT>ServletRequest.getParameterNames()</TT> </TD>
+<TD class="confluenceTd"> Returns an enumeration of the names of the parameters </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<P>As a special restriction only two kinds of parameters are supported: (1) Query String parameters and (2) parameters contained in the request data of content type <TT>application/x-www-form-encoded</TT>. That is file uploads using request data of type <TT>multipart/form-data</TT> are not directly supported by the servlet specification. Finally the actual encoding of the parameters is all but safe because the encoding of URLs is not very well defined and browsers do not set the character encoding when sending post data. Fortunately, they use the same character encoding for sending back form content as was used by the server to send the form.</P>
+
+
+<H2><A name="RequestParameters-SlingAPI"></A>Sling API</H2>
+
+<P>To overcome these restrictions and to provide uniform access to request parameters the Sling API in addition to the Servlet API methods to access parameters provides an abstraction of parameters which is applicable to all parameters sent by clients, the <TT>RequestParameter</TT> interface. Through this interface, each parameter may be analyzed for these topics:</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TD class="confluenceTd"> Raw Content </TD>
+<TD class="confluenceTd"> Byte array and <TT>InputStream</TT> representation of the request parameter values. You will generally use the <TT>InputStream</TT> to handle uploaded files. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> String Content </TD>
+<TD class="confluenceTd"> Access the values as strings is some given encoding (see below) or by requesting the conversion using an explicit encoding. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> File Uploads </TD>
+<TD class="confluenceTd"> Find out whether a parameter is a file upload, get the size in bytes of the parameter value and client side file name as sent by the browser. </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<P>To accomodate this new interface as well as to provide easy access in the traditional way the <TT>SlingHttpServletRequest</TT> interface adds following methods to the standard Servlet API parameter access methods:</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TD class="confluenceTd"> <TT>getRequestParameter(String)</TT> </TD>
+<TD class="confluenceTd"> Returns the (first) named parameter as a <TT>RequestParameter</TT> instance </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <TT>getRequestParameters(String)</TT> </TD>
+<TD class="confluenceTd"> Returns the named parameter as an array of <TT>RequestParameter</TT> instances </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <TT>getRequestParameterMap()</TT> </TD>
+<TD class="confluenceTd"> Returns <TT>RequestParameterMap</TT> being a map of <TT>RequestParameter</TT> arrays indexed by parameter names </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<P>All parameters are handled the same, that is all methods give access to the same parameters regardless of whether the parameters were transmitted in the request query, as part of form encoded data or as part of a <TT>multipart/form-data</TT> request.</P>
+
+<P>As of Sling Engine 2.1.0 the order or request parameters in the <TT>getRequestParameterMap()</TT>, <TT>getParameterMap()</TT>, and <TT>getParameterNams()</TT> is preserved as follows:</P>
+
+<UL>
+	<LI>The first entries are the parameters reported by the servlet container. The order of these parameters amongst each other is not defined. The <TT>SlingHttpServletRequest</TT> provides them in the same order as provided by the servlet container.</LI>
+	<LI>After the servlet container provided parameters are parameters extracted from the request in case <TT>multipart/form-data</TT> POST requests. The order of these parameters is preserved as they are submitted in the request. This conforms to HTML 4.01 spec on forms submitted with multipart/form-data encoding: <EM>A &quot;multipart/form-data&quot; message contains a series of parts, each representing a successful control. The parts are sent to the processing agent in the same order the corresponding controls appear in the document stream. Part boundaries should not occur in any of the data; how this is done lies outside the scope of this specification</EM> (<A href="http://www.w3.org/TR/html401/interact/forms.html" class="external-link" rel="nofollow">17.13.4 Form content types</A>)</LI>
+</UL>
+
+
+<P>Be warned: Only rely on request parameter ordering <TT>multipart/form-data</TT> POST requests without a query part in the request URL.</P>
+
+<H2><A name="RequestParameters-CharacterEncoding"></A>Character Encoding</H2>
+
+<P>Traditionally, the encoding of parameters, especially in text area input forms, has been a big issue. To solve this issue Sling introduces the following convention:</P>
+
+<UL>
+	<LI>All forms should contain a hidden field of the name <TT>&#95;charset&#95;</TT> containing the actual encoding used to send the form from the server to the client</LI>
+	<LI>All forms should be sent with <EM>UTF-8</EM> character encoding</LI>
+</UL>
+
+
+<P>The first rule is essential as it helps decoding the form input correctly. The second rule is not actually a very hard requirement but to enable support for all (or most) character sets used, using <EM>UTF-8</EM> is one of the best choices anyway.</P>
+
+<P>When Sling is now receiving a request and is asked for the parameters, the parameters are parsed in two phases: The first phase just parses the raw input data using an identity transformation of bytes to characters. This identity transformation happens to generate strings as the original data was generated with <TT>ISO-8859-1</TT> encoding. The second phase locates the <TT>&#95;charset&#95;</TT> parameter and fixes the character encodings of the parameters as follows:</P>
+
+<UL>
+	<LI>All names of the parameters are re-encoded</LI>
+	<LI>The parameter values are re-encoded, unless the parameter value is an uploaded file. Actually the parameter (not the files of course) are internally as <TT>byte[]</TT> where the conversion to a string is done on the fly (and yes, the conversion using the <TT>&#95;charset&#95;</TT> character encoding is of course cached for performance reasons)</LI>
+	<LI>If the parameter is an uploaded file, the file name is re-encoded on the fly when accessed</LI>
+</UL>
+
+
+<DIV class="panelMacro"><TABLE class="infoMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>Up to and including Sling Engine 2.2.2 request parameters are always decoded with ISO-8859-1 encoding if the <TT>&#95;charset&#95;</TT> request parameter is missing. As of Sling Engine 2.2.4 the <TT>&#95;charset&#95;</TT> request parameter is optional. As of this version the Sling Main Servlet supports a configuration setting which allows to change the default character encoding used if the <TT>&#95;charset&#95;</TT> request parameter is missing. To enable this functionality set the <TT>sling.default.parameter.encoding</TT> parameter of the Sling Main Servlet (PID <TT>org.apache.sling.engine.impl.SlingMainServlet</TT>) configuration to the desired encoding, which of course must be supported by the actual Java Plat
 form.</TD></TR></TABLE></DIV>
+        <DIV class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by fmeschbe on 2011-02-28 05:07:31.0
+        </DIV>
+        <DIV class="trademarkFooter">
+Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+        </DIV>
+    </DIV>
+  </BODY>
+</HTML>
+

Added: websites/staging/sling/trunk/content/site/request-processing.html
==============================================================================
--- websites/staging/sling/trunk/content/site/request-processing.html (added)
+++ websites/staging/sling/trunk/content/site/request-processing.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,252 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <HEAD>
+    <TITLE>Apache Sling - Request Processing</TITLE>
+    <LINK rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <LINK rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <META http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </HEAD>
+  <BODY>
+    <DIV class="title">
+      <DIV class="logo">
+        <A href="http://sling.apache.org/site/index.html">
+          <IMG border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </A>
+      </DIV>
+      <DIV class="header">
+        <A href="http://www.apache.org/">
+          <IMG border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </A>
+      </DIV>
+    </DIV>
+    <DIV class="menu">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="apache-sling.html" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="apache-sling.html" title="Apache Sling">Apache Sling</A>&nbsp;&gt;&nbsp;<A href="old-stuff.html" title="Old Stuff">Old Stuff</A>&nbsp;&gt;&nbsp;<A href="" title="Request Processing">Request Processing</A>
+        </DIV>
+<H1><A name="RequestProcessing-HTTPRequestProcessing"></A>HTTP Request Processing</H1>
+
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>Page Status</B><BR>2008-02-13: this page is <B>out of sync</B> with the current codebase, needs to be reviewed and updated.</TD></TR></TABLE></DIV>
+
+<P>One of the core problems towards understanding how Sling works is knowing how a Client Request is processed by Sling. This page describes the flow of processing requests inside Sling.</P>
+
+
+<H2><A name="RequestProcessing-CoreRequestProcessing"></A>Core Request Processing</H2>
+
+
+<P>The HTTP request enters Sling in the <TT>org.apache.sling.core.ComponentRequestHandlerImpl.service(ServletRequest req, ServletResponse res)</TT> method as the <TT>ComponentRequestHandlerImpl</TT> is registered as the Servlet handling HTTP requests. This method sets up the initial <TT>ComponentRequest</TT> and <TT>ComponentResponse</TT> objects and hands the request over to the first <TT>ComponentFilterChain</TT>. This first filter chain calls all <TT>ComponentFilter</TT> instances registered as request level filters. After processing all filters in the request level filter chain, the request is handed over to the second <TT>ComponentFilterChain</TT> which calls all <TT>ComponentFilter</TT> instances registered as component level filters. At the end of the second filter chain the <TT>service</TT> method of the actual <TT>Component</TT> to which the request resolved is called.</P>
+
+<P>As the component is now processing the request, it may decide to dispatch the request to some other content such as for example a paragraph system or navigation component. To do this, the component will call the <TT>RequestDispatcher.include</TT> method. If the request dispatcher dispatches to a <TT>Content</TT> object Sling will hand the dispatch request over to the component level filter chain, which at the end will call the <TT>service</TT> method for the <TT>Content</TT> object to dispatched to. This process may be repeated at the component's discretion only limited by processing resources such as available memory.</P>
+
+
+<P>As can be seen Sling itself is absed on the Component API <TT>ComponentFilter</TT> mechanism. As such Sling provides and uses the following filters in the Sling Core bundle:</P>
+
+<TABLE class="wiki-table" cellpadding="0" cellspacing="0" border="0"><TR><TH><TR><TH colspan="2" class="confluenceTh"> Request Level Filters </TH></TR></TH></TR><TR class="table-odd"><TD><TR><TD class="confluenceTd"> <TT>ErrorHandlerFilter</TT> </TD><TD class="confluenceTd"> Handles exceptions thrown while processing the request as well implements the <TT>ComponentResponse.sendError()</TT> method </TD></TR></TD></TR><TR class="table-even"><TD><TR><TD class="confluenceTd"> <TT>AuthenticationFilter</TT> </TD><TD class="confluenceTd"> Implements authentication for the request and provides the JCR Session of the request </TD></TR></TD></TR><TR class="table-odd"><TD><TR><TD class="confluenceTd"> <TT>BurstCacheFilter</TT> </TD><TD class="confluenceTd"> Checks whether the request may be handled by cached response data </TD></TR></TD></TR><TR class="table-even"><TD><TR><TD class="confluenceTd"> <TT>LocaleResolverFilter</TT> </TD><TD class="confluenceTd"> Provides information on the 
 <TT>Locale</TT> to be used for request processing. This filter implements the <TT>ComponentRequest.getLocale()</TT> method </TD></TR></TD></TR><TR class="table-odd"><TD><TR><TD class="confluenceTd"> <TT>ThemeResolverFilter</TT> </TD><TD class="confluenceTd"> Provides the <TT>Theme</TT> for the request. The theme is provided as a request attribute </TD></TR></TD></TR><TR class="table-even"><TD><TR><TD class="confluenceTd"> <TT>URLMapperFilter</TT> </TD><TD class="confluenceTd"> Resolves the request URL to a JCR Node which may be mapped into a <TT>Content</TT> object </TD></TR></TD></TR><TR class="table-odd"><TD><TR><TD class="confluenceTd"> <TT>ZipFilter</TT> </TD><TD class="confluenceTd"> Sample filter showing how the request response might be compressed according to the <EM>Accept-Encoding</EM> request header. This filter is not enabled by default. </TD></TR></TD></TR></TABLE>
+
+
+
+<P>Deducing from these lists of filters, the actual request processing can be refined into the following steps:</P>
+
+<OL>
+	<LI>Extract user authentication information and acquire the JCR session to access content. If the request has no user authentication data the such data may be requested from the user (for example by sending a HTTP 401 status) or an anonymous repository session might be acquired.</LI>
+	<LI>Check whether the request may be handled by data stored in the cache. If the request is cacheable and a cache entry exists for the request URL, the request data is returned to the client and request processing may terminate. Otherwise request processing will continue and optionally ensure that any response data is entered into the cache. Of course, if the request is not cacheable, for example because there are request parameters, or if any of the <TT>Component</TT> instances called during request processing decide to signal non-cacheability for whatever reason, the response data will of course not cached.</LI>
+	<LI>Extract the <TT>java.util.Locale</TT> from the request such that further processing may use properly translated messages. By default, the locale of the underlying Servlet request is used as the request locale. Other possibilities would be to use special cookies or some locale encoding in the path.</LI>
+	<LI>Find the theme (or skin) to use to render the response. This step will add a <TT>org.apache.sling.theme.Theme</TT> object as a request parameter, which may be used by {{Component}}s to decide on specific rendering. For example, the theme may encapsulate information on the CSS to use for responses rendered as HTML.</LI>
+	<LI>Resolve the request URL into a <TT>Content</TT> object.</LI>
+</OL>
+
+
+
+<P>The default request level filter chain setup ends with finding the <TT>Content</TT> object requested by the request URL. After having found this object, the request is handed over to the component level filter chain, which is concerned with handling filtering on a single <TT>Content</TT> instance. As such, the component level filter chain is used for each <TT>Content</TT> object which is to be serviced either on behalf of the HTTP request or on behalf of request dispatcher. Thus the component level filter chain will generally called multiple times during a single request.</P>
+
+
+<TABLE class="wiki-table" cellpadding="0" cellspacing="0" border="0"><TR><TH><TR><TH colspan="2" class="confluenceTh"> Component Level Filters </TH></TR></TH></TR><TR class="table-odd"><TD><TR><TD class="confluenceTd"> <TT>CacheFilter</TT> </TD><TD class="confluenceTd"> Checks whether the request to the current <TT>Content</TT> object may be handled by cached response data </TD></TR></TD></TR><TR class="table-even"><TD><TR><TD class="confluenceTd"> <TT>ComponentResolverFilter</TT> </TD><TD class="confluenceTd"> Resolves the component ID returned by the <TT>Content.getComponentId()</TT> method into a <TT>Component</TT> instances, which will be called to service the request </TD></TR></TD></TR></TABLE>
+
+<P>Again, deducing from the list of filters, the following steps are taking to service a given <TT>Content</TT> object:</P>
+
+<OL>
+	<LI>Check whether the <TT>Content</TT> object processing may be handled from the cache. Same as with request level cache handling, a cache entry may exist for a single <TT>Content</TT> instance depending on whether the request is cacheable at all and on whether a cache entry exists. If a cache entry exists and may be used, the response data is simply spooled into the response and component level processing terminates for the <TT>Content</TT> object. Otherwise processing continues and may optionally lead to a new cache entry for the <TT>Content</TT> object to be reused later.</LI>
+	<LI>Resolve the component ID returned by the <TT>Content.getComponentId()</TT> method into a <TT>Component</TT> object. Of course it is an error, if the component ID cannot be mapped into a <TT>Component</TT> object.</LI>
+</OL>
+
+
+<P>After resolving the <TT>Component</TT> object default component filter chain terminates and control is handed over to the <TT>service</TT> method of the <TT>Component</TT> object resolved in the last step. At the discretion of the component request dispatchers may now be acquired to render other <TT>Content</TT> objects. In this case the component level filter chain is simply kicked of again resulting in the <TT>service</TT> method of another <TT>Component</TT> being called. And so forth.</P>
+
+
+
+<H2><A name="RequestProcessing-ResolvingContent"></A>Resolving Content</H2>
+
+<P>As we have seen, the last step in the request level filter chain is the resolution of the request URL into a <TT>Content</TT> object. The URL Mapper Filter implementing this resolution uses an instance of the <TT>org.apache.sling.content.ContentMapper</TT> interface which is acquired by calling the <TT>org.apache.sling.content.jcr.JcrContentManagerFactory</TT> with the repository session acquired by the authentication filter.</P>
+
+<P>The URL Mapper filter then tries to apply fixed mappings from request URL to destination paths to support shortcut URLs. For example the root path <TT>/</TT> may be mapped into the default landing page at <TT>/default/home</TT>. The list of such mappings is configurable through the Configuration Admin Service.</P>
+
+<P>Next the URL Mapper tries to apply prefix matching patterns. A list of patterns is iterated checking whether the prefix applies and, if so, replacing the prefix with another prefix and trying to resolve the result. This functionality enables relocation of a subtree of the repository. For example, all requests whose prefix is <TT>/here</TT> might be remapped with the new prefix <TT>/content/there</TT>. The result  of this remapping is then resolved.</P>
+
+<P>Resolution (currently) takes place on the last path segment of the request URL containing at least one dot. Parts of that segment are cut off after dots until no more dots exist in the URL. For each resulting substring, the <TT>ContentManager.load(String)</TT> method is called. This processing terminates if a <TT>Content</TT> object is found or if there is nothing to cut off any more.</P>
+
+<P>This resolution is very simple and straight forwards. Future development may add support for the following features:</P>
+
+<UL>
+	<LI><B>Vanity URLs</B> - Map the request URL according to the <TT>Host</TT> request header.</LI>
+	<LI><B>Dynamic Mapping</B> - Add support for a set of variables in path and/or prefix mapping. For example, a prefix mapping  may contain the string <TT>/content/${lang}/${user</TT>} resulting in resolving a prefix according to the language of the current locale and the name of the authenticated used.</LI>
+</UL>
+
+
+
+
+<H2><A name="RequestProcessing-RegisteringComponents"></A>Registering Components</H2>
+
+
+<P>The last step of the component level filter chain is resolving the <TT>Component</TT> from the component ID of the <TT>Content</TT> object. Sling implements this resolution by making use of the OSGi service registry. That is, each component is to be registered as a service with the name <TT>org.apache.sling.component.Component</TT>. The <TT>ComponentResolverFilter</TT> is listening for these components and registers them internally in a map indexed by the IDs of the component as returned by the <TT>Component.getId()</TT> method.</P>
+
+<P>When a component has to be resolved, the component ID returned by the <TT>Content</TT> object is simply looked up in the component map. If found, that component is used. Otherwise a fall back algorithm is applied which is described on the <A href="default-mapping-and-rendering.html" title="Default Mapping and Rendering">Default Content Mapping and Request Rendering</A> page.</P>
+
+
+
+<H2><A name="RequestProcessing-ReqisteringFilters"></A>Reqistering Filters</H2>
+
+<P>Just as <TT>Component</TT> instances used by Sling are expected to be registered as OSGi services, the {{ComponentFilter}}s to be <BR>
+used have to be registered as services under the name <TT>org.apache.sling.component.ComponentFilter</TT>. Sling picks up all registered component filters and adds them to the respective filter chains.</P>
+
+<P>Service properties set upon registration of the filter define the chain to which the filter belongs and the order in which the filters should be processed:</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> Property </TH>
+<TH class="confluenceTh"> Description </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> <TT>filter.scope</TT> </TD>
+<TD class="confluenceTd"> Defines the chain to which the filter is added. Supported values are <TT>component</TT> for component level filters and <TT>request</TT> for request level filters. If this property is missing or set to an unknown value the filter is added to the request level filter chain. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <TT>filter.order</TT> </TD>
+<TD class="confluenceTd"> Defines the weight of the filter to resolve the processing order. This property must be an <TT>java.lang.Integer</TT>. If not set or not an <TT>Integer</TT> the order defaults to <TT>Integer.MAX_VALUE</TT>. The lower the order number the earlier in the filter chain will the filter be inserted. If two filters are registered with the same order value, the filter with the lower <TT>service.id</TT> value is called first. </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+
+
+<H2><A name="RequestProcessing-ContentisaJavaObject"></A>Content is a Java Object</H2>
+
+<P>It is crucial to understand that <TT>Content</TT> is an interface and the request processor of Sling does not actually care, how the <TT>Content</TT> instance comes to live as long as the is such an object and there is a <TT>Component</TT> instance capable of servicing the <TT>Content</TT> object.</P>
+
+<P>By default Sling uses the <EM>URL Mapper</EM> to resolve the request URL into a <TT>Content</TT> object. When a <TT>Component</TT> is tasked with servicing a <TT>Content</TT> object it usually uses the <TT>ComponentRequestDispatcher</TT> to ask Sling to service another content object generally identified by a (relative or absolute) path to a JCR Repository Node from which the <TT>Content</TT> object is loaded.</P>
+
+<P>But instead of having Sling resolve a path into a <TT>Content</TT> object the component may just as well create a <TT>Content</TT> object and hand it over to the <TT>ComponentRequestDispatcher</TT> for service. Consider a request which is handled by a <TT>PageComponent</TT>. This component has to draw a navigation tree somewhere in the response. So the component could of course insist on having a <TT>navigation</TT> child node to dispatch rendering to as follows:</P>
+
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+RequestDispatcher rd = request.getRequestDispatcher(<SPAN class="code-quote">&quot;navigation&quot;</SPAN>);
+rd.include(request, response);
+</PRE>
+</DIV></DIV>
+
+
+<P>What happens, though, if there is no <TT>navigation</TT> child node ? Probably, the request will fail with some error status. Of course the component could be more clever and do:</P>
+
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Content navigation = request.getContent(<SPAN class="code-quote">&quot;navigation&quot;</SPAN>);
+<SPAN class="code-keyword">if</SPAN> (navigation != <SPAN class="code-keyword">null</SPAN>) {
+    RequestDispatcher rd = request.getRequestDispatcher(navigation);
+    rd.include(request, response);
+}
+</PRE>
+</DIV></DIV>
+
+
+<P>Still, if the <TT>navigation</TT> child node does not exist, there is no navigation drawn; at least there will be now error. Since Sling does not actually care, how a <TT>Content</TT> object comes to live, the component could do the following:</P>
+
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Content navigation = <SPAN class="code-keyword">new</SPAN> Content() {
+    <SPAN class="code-keyword">public</SPAN> <SPAN class="code-object">String</SPAN> getPath() {
+        <SPAN class="code-keyword">return</SPAN> request.getContent().getPath() + <SPAN class="code-quote">&quot;/navigation&quot;</SPAN>;
+    }
+    <SPAN class="code-keyword">public</SPAN> <SPAN class="code-object">String</SPAN> getComponentId() {
+        <SPAN class="code-keyword">return</SPAN> NavigationComponent.getClass().getName();
+    }
+}
+
+RequestDispatcher rd = request.getRequestDispatcher(navigation);
+rd.include(request, response);
+</PRE>
+</DIV></DIV>
+
+
+<P>Of course, the page component now has to have knowledge about the actual <TT>Component</TT> to use.</P>
+
+
+<P>Finally, as a further enhancement, the Component might even decide to first check for a <TT>navigation</TT> child node. If such a node does not exist the navigation <TT>Content</TT> object is just created:</P>
+
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Content navigation = request.getContent(<SPAN class="code-quote">&quot;navigation&quot;</SPAN>);
+<SPAN class="code-keyword">if</SPAN> (navigation == <SPAN class="code-keyword">null</SPAN>) {
+    navigation = <SPAN class="code-keyword">new</SPAN> Content() {
+        <SPAN class="code-keyword">public</SPAN> <SPAN class="code-object">String</SPAN> getPath() {
+            <SPAN class="code-keyword">return</SPAN> request.getContent().getPath() + <SPAN class="code-quote">&quot;/navigation&quot;</SPAN>;
+        }
+        <SPAN class="code-keyword">public</SPAN> <SPAN class="code-object">String</SPAN> getComponentId() {
+            <SPAN class="code-keyword">return</SPAN> NavigationComponent.getClass().getName();
+        }
+    }
+}
+
+RequestDispatcher rd = request.getRequestDispatcher(navigation);
+rd.include(request, response);
+</PRE>
+</DIV></DIV>
+
+
+<P>This could for example be used to fall back to a default navigation setup while providing for specialized navigation configuration in an optional <TT>navigation</TT> child node.</P>
+        <DIV class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by mykee on 2008-02-13 07:10:28.0
+        </DIV>
+        <DIV class="trademarkFooter">
+Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+        </DIV>
+    </DIV>
+  </BODY>
+</HTML>
+

Added: websites/staging/sling/trunk/content/site/resources.html
==============================================================================
--- websites/staging/sling/trunk/content/site/resources.html (added)
+++ websites/staging/sling/trunk/content/site/resources.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,189 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <HEAD>
+    <TITLE>Apache Sling - Resources</TITLE>
+    <LINK rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <LINK rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <META http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </HEAD>
+  <BODY>
+    <DIV class="title">
+      <DIV class="logo">
+        <A href="http://sling.apache.org/site/index.html">
+          <IMG border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </A>
+      </DIV>
+      <DIV class="header">
+        <A href="http://www.apache.org/">
+          <IMG border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </A>
+      </DIV>
+    </DIV>
+    <DIV class="menu">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="apache-sling.html" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="apache-sling.html" title="Apache Sling">Apache Sling</A>&nbsp;&gt;&nbsp;<A href="documentation.html" title="Documentation">Documentation</A>&nbsp;&gt;&nbsp;<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A>&nbsp;&gt;&nbsp;<A href="" title="Resources">Resources</A>
+        </DIV>
+<H1><A name="Resources-Resources"></A>Resources</H1>
+
+<DIV>
+<UL>
+    <LI><A href="#Resources-WhatisaResource">What is a Resource</A></LI>
+    <LI><A href="#Resources-HowtogetaResource">How to get a Resource</A></LI>
+<UL>
+    <LI><A href="#Resources-AbsolutePathMapping">Absolute Path Mapping</A></LI>
+    <LI><A href="#Resources-RelativePathResolution">Relative Path Resolution</A></LI>
+    <LI><A href="#Resources-QueryingResources">Querying Resources</A></LI>
+</UL>
+    <LI><A href="#Resources-ProvidingResources">Providing Resources</A></LI>
+<UL>
+    <LI><A href="#Resources-JCRbasedResources">JCR-based Resources</A></LI>
+    <LI><A href="#Resources-BundlebasedResources">Bundle-based Resources</A></LI>
+    <LI><A href="#Resources-ServletResources">Servlet Resources</A></LI>
+    <LI><A href="#Resources-FileSystemResources">File System Resources</A></LI>
+</UL>
+    <LI><A href="#Resources-Wrap%252FDecorateResources">Wrap/Decorate Resources</A></LI>
+</UL></DIV>
+
+<H2><A name="Resources-WhatisaResource"></A>What is a Resource</H2>
+
+<P>The Resource is one of the central parts of Sling. Extending from JCR's <EM>Everything is Content</EM>, Sling assumes <EM>Everthing is a Resource</EM>. Thus Sling is maintaining a virtual tree of resources, which is a merger of the actual contents in the JCR Repository and resources provided by so called resource providers. By doing this Sling fits very well in the paradigma of the REST architecture.</P>
+
+<H2><A name="Resources-HowtogetaResource"></A>How to get a Resource</H2>
+
+<P>To get at Resources, you need a <TT>ResourceResolver</TT>. This interface defines four kinds of methods to access resources:</P>
+<UL>
+	<LI>Absolute Path Mapping Resource Resolution: The <TT>resolve(HttpServletRequest, String)</TT> and <TT>resolve(String)</TT> methods are called to apply some implementation specific path matching algorithm to find a Resource. These methods are mainly used to map external paths - such as path components of request URLs - to Resources. To support creating external paths usable in an URL a third method <TT>map(String)</TT> is defined, which allows for round-tripping.</LI>
+	<LI>Absolute or Relative Path Resolution (including search path): The <TT>getResource(String path)</TT> and <TT>getResource(Resource base, String path)</TT> methods may be used to access a resource with an absolute path directly. If it can't be found the path is assumed to be relative and the search path retrieved from <TT>getSearchPath()</TT> is used to retrieve the resource. This mechanism is similar to resolving a programm with the <TT>PATH</TT> environment variable in your favourite operating system.</LI>
+	<LI>Resource Enumeration: To enumerate resources and thus iterate the resource tree, the <TT>listChildren(Resource)</TT> method may be used. This method returns an <TT>Iterator&lt;Resource&gt;</TT> listing all resources whose path prefix is the path of the given Resource. This method will of course also cross boundaries of registered <TT>ResourceProvider</TT> instances to enable iterating the complete resource tree.</LI>
+	<LI>Resource Querying: Querying resources is currently only supported for JCR Resources through the <TT>findResources(String query, String language)</TT> and <TT>queryResources(String query, String language)</TT> methods. For more information see the section on <A href="#Resources-QueryingResources">Querying_Resources</A> below.</LI>
+</UL>
+
+
+<H3><A name="Resources-AbsolutePathMapping"></A>Absolute Path Mapping</H3>
+
+<P>As has been said, the absolute path mapping methods <TT>resolve(HttpServletRequest, String)</TT> and <TT>resolve(String)</TT> apply some implementation specific path matching algorithm to find a Resource. The difference between the two methods is that the former may take more properties of the <TT>HttpServletRequest</TT> into account when resolving the Resoure, while the latter just has an absolute path to work on.</P>
+
+<P>The general algorithm of the two methods is as follows:</P>
+<OL>
+	<LI>Call <TT>HttpServletRequest.getScheme(), .getServerName(), getServerPort</TT> to get an absolute path out of the request URL: [scheme]/[host].[port][path] (<TT>resolve(HttpServletRequest, String)</TT> method only, which)</LI>
+	<LI>Check whether any virtual path matches the absolute path. If such a match exists, the next step is entered with the match.</LI>
+	<LI>Apply a list of mappings in order to create a mapped path. The first mapped path resolving to a Resource is assumed success and the Resource found is returned.</LI>
+	<LI>If no mapping created a mapped path addressing an existing Resource, the method fails and returns:</LI>
+</OL>
+
+
+<UL>
+	<LI>The <TT>resolve(String)</TT> and <TT>resolve(HttpServletRequest,String)</TT> methods return a <TT>NonExistingResource</TT></LI>
+	<LI>The <TT>getResource(String path)</TT> and <TT>getResource(Resource base, String path)</TT> methods return null</LI>
+</UL>
+
+
+<P>The virtual path mapping may be used to create shortcut URLs for otherwise long and complicated URLs. An example of such an URL might be the main administrative page of a CMS system. So, administrators may access the root of the web application and directed to the main administrative page.</P>
+
+<P>The path mapping functionality may be used to hide internal resource organization from the request URL space. For example to better control the structure of your repository, you might decide to store all accessible data inside a <TT>/content</TT> subtree. To hide this fact from the users, a mapping may be defined to prefix all incoming paths with <TT>/content</TT> to get at the actual Resource.</P>
+
+<P>The <TT>map(String)</TT> applies the path mapping algorithm in the reverse order. That is, first the path mappings are reversed and then any virtual mappings are checked. So, a path <TT>/content/sample</TT> might be mapped <TT>/sample</TT> to revers the <TT>/content</TT> prefixing. Or the main administrative page - say <TT>/system/admin/main.html</TT> &#45; may be mapped to the virtual URL <TT>/</TT>.</P>
+
+<H3><A name="Resources-RelativePathResolution"></A>Relative Path Resolution</H3>
+
+<P>Sometimes it is required to resolve relative paths to Resources. An example of such a use case is Script and Servlet resolution which starts with a relative path consisting of the Resource type, optional selectors and the request extension or method name. By scanning a search path for these relative paths a system provided Resource may be overwritten with some user defined implementation.</P>
+
+<P>Consider for example, the system would provide a Servlet to render Resources of type <TT>nt:file</TT>. This Servlet would be registered under the path <TT>/libs/nt/file/html</TT>. For a certain web application, this default HTML rendering might not be appropriate, so a Script is created as <TT>/apps/nt/file/html.jsp</TT> with a customized HTML rendering. By defining the search path to be <EM>[</EM> <TT><EM>/apps</EM></TT><EM>,</EM> <TT><EM>/libs</EM></TT> <EM>]</EM> the Servlet resolver would call the <TT>ResourceResolver.getResource(String)</TT> method with the relative path <TT>nt/file/html</TT> and be provided with the first matching resource - <TT>/apps/nt/file/html.jsp</TT> in this example.</P>
+
+<P>Of course the search path is not used for absolute path arguments.</P>
+
+<H3><A name="Resources-QueryingResources"></A>Querying Resources</H3>
+
+<P>For convenience the <TT>ResourceResolver</TT> provides two Resource querying methods <TT>findResources</TT> and <TT>queryResources</TT> both methods take as arguments a JCR query string and a query language name. These parameters match the parameter definition of the <TT>QueryManager.createQuery(String statement, String language)</TT> method of the JCR API.</P>
+
+<P>The return value of these two methods differ in the use case:</P>
+<UL>
+	<LI><TT>findResources</TT> returns an <TT>Iteratory&lt;Resource&gt;</TT> of all Resources matching the query. This method is comparable to calling <TT>getNodes()</TT> on the <TT>QueryResult</TT> returned from executing the JCR query.</LI>
+	<LI><TT>queryResources</TT> returns an <TT>Iterator&lt;Map&lt;String, Object&gt;&gt;</TT>. Each entry in the iterator is a <TT>Map&lt;String, Object</TT> representing a JCR result <TT>Row</TT> in the <TT>RowIterator</TT> returned from executing the JCR query. The map is indexed by the column name and the value of each entry is the value of the named column as a Java Object.</LI>
+</UL>
+
+
+<P>These methods are convenience methods to more easily post queries to the repository and to handle results in very straight forward way using only standard Java functionality.</P>
+
+<P>Please note, that Resource querying is currently only supported for repository based Resources. These query methods are not reflected in the <TT>ResourceProvider</TT> interface used to inject non-repository Resources into the Resource tree.</P>
+
+<H2><A name="Resources-ProvidingResources"></A>Providing Resources</H2>
+
+<P>The virtual Resource tree to which the the Resource accessor methods <TT>resolve</TT> and <TT>getResource</TT> provide access is implemented by a collection of registered <TT>ResourceProvider</TT> instances. The main Resource provider is of course the repository based <TT>JcrResourceProvider</TT> which supports Node and Property based resources. This Resource provider is always available in Sling. Further Resource providers may or may not exist.</P>
+
+<P>Each Resource provider is registered as an OSGi service with a required service registration property <TT>provider.roots</TT>. This is a multi-value String property listing the absolute paths Resource tree entries serving as roots to provided subtrees. For example, if a Resource provider is registered with the service registration property <TT>provider.roots</TT> set to <EM>/some/root</EM>, all paths starting with <TT>/some/root</TT> are first looked up in the given Resource Provider.</P>
+
+<P>When looking up a Resource in the registered Resource providers, the <TT>ResourceResolver</TT> applies a longest prefix matching algorithm to find the best match. For example consider three Resource provider registered as follows:</P>
+<UL>
+	<LI>JCR Resource provider as <TT>/</TT></LI>
+	<LI>Resource provider R1 as <TT>/some</TT></LI>
+	<LI>Resource provider R2 as <TT>/some/path</TT></LI>
+</UL>
+
+
+<P>When accessing a Resource with path <TT>/some/path/resource</TT> the Resource provider <EM>R2</EM> is first asked. If that cannot provide the resource, Resource provider <EM>R1</EM> is asked and finally the JCR Resource provider is asked. The first Resource provider having a Resource with the requested path will be used.</P>
+
+<H3><A name="Resources-JCRbasedResources"></A>JCR-based Resources</H3>
+
+<P>JCR-based Resources are provided with the default <TT>JcrResourceProvider</TT>. This Resource provider is always available and is always asked last. That is Resources provided by other Resource providers may never be overruled by repository based Resources.</P>
+
+<H3><A name="Resources-BundlebasedResources"></A>Bundle-based Resources</H3>
+
+<P>Resources may by provided by OSGi bundles. Providing bundles have a Bundle manifest header <TT>Sling-Bundle-Resources</TT> containing a list of absolute paths provided by the bundle. The path are separated by comma or whitespace (SP, TAB, VTAB, CR, LF).</P>
+
+<P>The <TT>BundleResourceProvider</TT> supporting bundle-based Resources provides directories as Resources of type <TT>nt:folder</TT> and files as Resources of type <TT>nt:file</TT>. This matches the default primary node types intended to be used for directories and files in JCR repositories. For details see <A href="bundle-resources-extensionsbundleresource.html" title="Bundle Resources (extensions.bundleresource)">Bundle Resource.</A></P>
+
+<H3><A name="Resources-ServletResources"></A>Servlet Resources</H3>
+
+<P>Servlet Resources are registered by the Servlet Resolver bundle for Servlets registered as OSGi services. See <A href="servlets.html" title="Servlets">Servlet Resolution</A> for information on how Servlet Resources are provided.</P>
+
+<H3><A name="Resources-FileSystemResources"></A>File System Resources</H3>
+
+<P>The Filesystem Resource Provider provides access to the operating system's filesystem through the Sling ResourceResolver. Multiple locations may be mapped into the resource tree by configuring the filesystem location and the resource tree root path for each location to be mapped. For details see <A href="accessing-filesystem-resources-extensionsfsresource.html" title="Accessing Filesystem Resources (extensions.fsresource)">File System Resources</A>.</P>
+
+<H2><A name="Resources-Wrap%2FDecorateResources"></A>Wrap/Decorate Resources</H2>
+
+<P>The Sling API provides an easy way to wrap or decorate a resource before returning. Details see <A href="wrap-or-decorate-resources.html" title="Wrap or Decorate Resources">Wrap or Decorate Resources</A>.</P>
+        <DIV class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by mykee on 2010-08-25 03:33:22.0
+        </DIV>
+        <DIV class="trademarkFooter">
+Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+        </DIV>
+    </DIV>
+  </BODY>
+</HTML>
+



Mime
View raw message