Author: buildbot
Date: Thu May 16 09:16:20 2013
New Revision: 862147
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu May 16 09:16:20 2013
@@ -1 +1 @@
-1482608
+1483268
Modified:
websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html
==============================================================================
---
websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html
(original)
+++
websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html
Thu May 16 09:16:20 2013
@@ -108,22 +108,28 @@
<h2 id="what-is-a-resource">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 id="how-to-get-a-resource">How to get a Resource</h2>
-<p>To get at Resources, you need a <code>ResourceResolver</code>. This
interface defines four kinds of methods to access resources:
-<em> Absolute Path Mapping Resource Resolution: The
<code>resolve(HttpServletRequest, String)</code> and
<code>resolve(String)</code> 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
<code>map(String)</code> is defined, which allows for round-tripping.
-</em> Absolute or Relative Path Resolution (including search path): The
<code>getResource(String path)</code> and <code>getResource(Resource base,
String path)</code> 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 <code>getSearchPath()</code> is used to retrieve the
resource. This mechanism is similar to resolving a programm with the
<code>PATH</code> environment variable in your favourite operating system.
-<em> Resource Enumeration: To enumerate resources and thus iterate the
resource tree, the <code>listChildren(Resource)</code> method may be used. This
method returns an <code>Iterator<Resource></code> listing all resources
whose path prefix is the path of the given Resource. This method will of course
also cross boundaries of registered <code>ResourceProvider</code> instances to
enable iterating the complete resource tree.
-</em> Resource Querying: Querying resources is currently only supported for
JCR Resources through the <code>findResources(String query, String
language)</code> and <code>queryResources(String query, String language)</code>
methods. For more information see the section on <a
href="#querying-resources">Querying Resources</a> below.</p>
+<p>To get at Resources, you need a <code>ResourceResolver</code>. This
interface defines four kinds of methods to access resources:</p>
+<ul>
+<li>Absolute Path Mapping Resource Resolution: The
<code>resolve(HttpServletRequest, String)</code> and
<code>resolve(String)</code> 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
<code>map(String)</code> is defined, which allows for round-tripping.</li>
+<li>Absolute or Relative Path Resolution (including search path): The
<code>getResource(String path)</code> and <code>getResource(Resource base,
String path)</code> 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 <code>getSearchPath()</code> is used to retrieve the
resource. This mechanism is similar to resolving a programm with the
<code>PATH</code> environment variable in your favourite operating system.</li>
+<li>Resource Enumeration: To enumerate resources and thus iterate the resource
tree, the <code>listChildren(Resource)</code> method may be used. This method
returns an <code>Iterator<Resource></code> listing all resources whose
path prefix is the path of the given Resource. This method will of course also
cross boundaries of registered <code>ResourceProvider</code> instances to
enable iterating the complete resource tree.</li>
+<li>Resource Querying: Querying resources is currently only supported for JCR
Resources through the <code>findResources(String query, String language)</code>
and <code>queryResources(String query, String language)</code> methods. For
more information see the section on <a href="#querying-resources">Querying
Resources</a> below.</li>
+</ul>
<h3 id="absolute-path-mapping">Absolute Path Mapping</h3>
<p>As has been said, the absolute path mapping methods
<code>resolve(HttpServletRequest, String)</code> and
<code>resolve(String)</code> 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 <code>HttpServletRequest</code> 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:
-1. Call <code>HttpServletRequest.getScheme(), .getServerName(),
getServerPort</code> to get an absolute path out of the request URL:
[scheme]()/[host].[port][path] (<code>resolve(HttpServletRequest,
String)</code> method only, which)
-1. Check whether any virtual path matches the absolute path. If such a match
exists, the next step is entered with the match.
-1. 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.
-1. If no mapping created a mapped path addressing an existing Resource, the
method fails and returns:</p>
-<ul>
-<li>The <code>resolve(String)</code> and
<code>resolve(HttpServletRequest,String)</code> methods return a
<code>NonExistingResource</code></li>
+<p>The general algorithm of the two methods is as follows:</p>
+<ol>
+<li>Call <code>HttpServletRequest.getScheme(), .getServerName(),
getServerPort</code> to get an absolute path out of the request URL:
[scheme]()/[host].[port][path] (<code>resolve(HttpServletRequest,
String)</code> 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>
+<p>If no mapping created a mapped path addressing an existing Resource, the
method fails and returns:</p>
+</li>
+<li>
+<p>The <code>resolve(String)</code> and
<code>resolve(HttpServletRequest,String)</code> methods return a
<code>NonExistingResource</code></p>
+</li>
<li>The <code>getResource(String path)</code> and <code>getResource(Resource
base, String path)</code> methods return null</li>
-</ul>
+</ol>
<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 <code>/content</code> subtree. To hide this fact from the users, a
mapping may be defined to prefix all incoming paths with <code>/content</code>
to get at the actual Resource.</p>
<p>The <code>map(String)</code> 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 <code>/content/sample</code> might be
mapped <code>/sample</code> to revers the <code>/content</code> prefixing. Or
the main administrative page - say <code>/system/admin/main.html</code> - may
be mapped to the virtual URL <code>/</code>.</p>
@@ -133,18 +139,22 @@
<p>Of course the search path is not used for absolute path arguments.</p>
<h3 id="querying-resources">Querying Resources</h3>
<p>For convenience the <code>ResourceResolver</code> provides two Resource
querying methods <code>findResources</code> and <code>queryResources</code>
both methods take as arguments a JCR query string and a query language name.
These parameters match the parameter definition of the
<code>QueryManager.createQuery(String statement, String language)</code> method
of the JCR API.</p>
-<p>The return value of these two methods differ in the use case:
-<em> <code>findResources</code> returns an
<code>Iteratory<Resource></code> of all Resources matching the query.
This method is comparable to calling <code>getNodes()</code> on the
<code>QueryResult</code> returned from executing the JCR query.
-</em> <code>queryResources</code> returns an <code>Iterator<Map<String,
Object>></code>. Each entry in the iterator is a <code>Map<String,
Object</code> representing a JCR result <code>Row</code> in the
<code>RowIterator</code> 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.</p>
+<p>The return value of these two methods differ in the use case:</p>
+<ul>
+<li><code>findResources</code> returns an
<code>Iteratory<Resource></code> of all Resources matching the query.
This method is comparable to calling <code>getNodes()</code> on the
<code>QueryResult</code> returned from executing the JCR query.</li>
+<li><code>queryResources</code> returns an <code>Iterator<Map<String,
Object>></code>. Each entry in the iterator is a <code>Map<String,
Object</code> representing a JCR result <code>Row</code> in the
<code>RowIterator</code> 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
<code>ResourceProvider</code> interface used to inject non-repository Resources
into the Resource tree.</p>
<h2 id="providing-resources">Providing Resources</h2>
<p>The virtual Resource tree to which the the Resource accessor methods
<code>resolve</code> and <code>getResource</code> provide access is implemented
by a collection of registered <code>ResourceProvider</code> instances. The main
Resource provider is of course the repository based
<code>JcrResourceProvider</code> 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 <code>provider.roots</code>. 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 <code>provider.roots</code>
set to <em>/some/root</em>, all paths starting with <code>/some/root</code> are
first looked up in the given Resource Provider.</p>
-<p>When looking up a Resource in the registered Resource providers, the
<code>ResourceResolver</code> applies a longest prefix matching algorithm to
find the best match. For example consider three Resource provider registered as
follows:
-<em> JCR Resource provider as <code>/</code>
-</em> Resource provider R1 as <code>/some</code>
-* Resource provider R2 as <code>/some/path</code></p>
+<p>When looking up a Resource in the registered Resource providers, the
<code>ResourceResolver</code> 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 <code>/</code></li>
+<li>Resource provider R1 as <code>/some</code></li>
+<li>Resource provider R2 as <code>/some/path</code></li>
+</ul>
<p>When accessing a Resource with path <code>/some/path/resource</code> 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 id="jcr-based-resources">JCR-based Resources</h3>
<p>JCR-based Resources are provided with the default
<code>JcrResourceProvider</code>. 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>
@@ -160,7 +170,7 @@
<h2 id="wrapdecorate-resources">Wrap/Decorate Resources</h2>
<p>The Sling API provides an easy way to wrap or decorate a resource before
returning. Details see <a
href="/documentation/the-sling-engine/wrap-or-decorate-resources.html">Wrap or
Decorate Resources</a>.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1475862 by dklco on Thu, 25 Apr 2013 17:28:38 +0000
+ Rev. 1483268 by bdelacretaz on Thu, 16 May 2013 09:16:08 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
