Added: sling/site/trunk/content/site/request-processing.html
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/site/request-processing.html?rev=1420577&view=auto
==============================================================================
--- sling/site/trunk/content/site/request-processing.html (added)
+++ sling/site/trunk/content/site/request-processing.html Wed Dec 12 09:13:50
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 &
How-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> > <A href="apache-sling.html" title="Apache
Sling">Apache Sling</A> > <A href="old-stuff.html" title="Old
Stuff">Old Stuff</A> > <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">"navigation"</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">"navigation"</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">"/navigation"</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">"navigation"</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">"/navigation"</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>
+
Propchange: sling/site/trunk/content/site/request-processing.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sling/site/trunk/content/site/request-processing.html
------------------------------------------------------------------------------
svn:keywords = Id
Propchange: sling/site/trunk/content/site/request-processing.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: sling/site/trunk/content/site/resources.html
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/site/resources.html?rev=1420577&view=auto
==============================================================================
--- sling/site/trunk/content/site/resources.html (added)
+++ sling/site/trunk/content/site/resources.html Wed Dec 12 09:13:50 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 &
How-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> > <A href="apache-sling.html" title="Apache
Sling">Apache Sling</A> > <A href="documentation.html"
title="Documentation">Documentation</A> > <A
href="the-sling-engine.html" title="The Sling Engine">The Sling
Engine</A> > <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<Resource></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> - 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<Resource></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<Map<String,
Object>></TT>. Each entry in the iterator is a <TT>Map<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>
+
Propchange: sling/site/trunk/content/site/resources.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sling/site/trunk/content/site/resources.html
------------------------------------------------------------------------------
svn:keywords = Id
Propchange: sling/site/trunk/content/site/resources.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
![http://sling.apache.org/site/media.data/logo.png"](http://sling.apache.org/site/media.data/logo.png"){kind=link}
![http://sling.apache.org/site/media.data/apache.png"](http://sling.apache.org/site/media.data/apache.png"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"){kind=link}