incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [CONF] Apache Sling Website > Resources
Date Tue, 24 Aug 2010 19:06:00 GMT
    <base href="">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="">Resources</a></h2>
    <h4>Page <b>edited</b> by             <a href="">Mike
                         <h4>Changes (1)</h4>
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h2. Wrap/Decorate Resources <br>
            <tr><td class="diff-changed-lines" >The Sling API provides an easy
way to wrap or decorate a resource before returning. Details see <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[Wrap/Decorate</span>
<span class="diff-added-words"style="background-color: #dfd;">[Wrap or Decorate</span>
Resources]. <br></td></tr>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="Resources-Resources"></a>Resources</h1>

    <li><a href='#Resources-WhatisaResource'>What is a Resource</a></li>
    <li><a href='#Resources-HowtogetaResource'>How to get a Resource</a></li>
    <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>
    <li><a href='#Resources-ProvidingResources'>Providing Resources</a></li>
    <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>
    <li><a href='#Resources-Wrap%2FDecorateResources'>Wrap/Decorate Resources</a></li>

<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>
	<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
	<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>

<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>
	<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>

	<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>

<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>
	<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>

<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>
	<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>

<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 absolute path prefixes
provided by the bundle. The list entries 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="/confluence/display/SLINGxSITE/Bundle+Resources+%28extensions.bundleresource%29"
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="/confluence/display/SLINGxSITE/Servlets" 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="/confluence/display/SLINGxSITE/Accessing+Filesystem+Resources+%28extensions.fsresource%29"
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="/confluence/display/SLINGxSITE/Wrap+or+Decorate+Resources" title="Wrap
or Decorate Resources">Wrap or Decorate Resources</a>.</p>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href=""
class="grey">Change Notification Preferences</a>
        <a href="">View
        <a href="">View
        <a href=";showCommentArea=true#addcomment">Add

View raw message