incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r862147 - in /websites/staging/sling/trunk/content: ./ documentation/the-sling-engine/resources.html
Date Thu, 16 May 2013 09:16:20 GMT
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&lt;Resource&gt;</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&lt;Resource&gt;</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&lt;Resource&gt;</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&lt;Map&lt;String,
Object&gt;&gt;</code>. Each entry in the iterator is a <code>Map&lt;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&lt;Resource&gt;</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&lt;Map&lt;String,
Object&gt;&gt;</code>. Each entry in the iterator is a <code>Map&lt;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



Mime
View raw message