You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2013/05/16 11:16:20 UTC
svn commit: r862147 - in /websites/staging/sling/trunk/content: ./
documentation/the-sling-engine/resources.html
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