incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Sling Website > Mappings for Resource Resolution
Date Fri, 11 Dec 2009 10:41:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Mappings+for+Resource+Resolution">Mappings
for Resource Resolution</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <h1><a name="MappingsforResourceResolution-MappingsforResourceResolution"></a>Mappings
for Resource Resolution</h1>


<h2><a name="MappingsforResourceResolution-Configuration"></a>Configuration</h2>


<h3><a name="MappingsforResourceResolution-Properties"></a>Properties</h3>

<p>The mapping of request URLs to resources is mainly configured in a configuration
tree which is (by default) located below <tt>/etc/map</tt>. The actual location
can be configured with the <tt>resource.resolver.map.location</tt> property of
the <tt>org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl</tt>
configuration.</p>


<p>When dealing with the new resource resolution we have a number of properties influencing
the process:</p>
<ul>
	<li><tt>sling:match</tt> &#8211; This property when set on a node in
the <tt>/etc/map</tt> tree (see below) defines a partial regular expression which
is used instead of the node's name to match the incoming request. This property is only needed
if the regular expression includes characters which are not valid JCR name characters. The
list of invalid characters for JCR names is: /, :, [, ], &#42;, ', ", &#124; and any
whitespace except blank space. In addition a name without a name space may not be <tt>.</tt>
or <tt>..</tt> and a blank space is only allowed inside the name.</li>
	<li><tt>sling:redirect</tt> &#8211; This property when set on a node
in the <tt>/etc/map</tt> tree (see below) causes a redirect response to be sent
to the client, which causes the client to send in a new request with the modified location.
The value of this property is applied to the actual request and sent back as the value of
<tt>Location</tt> response header.</li>
	<li><tt>sling:status</tt> &#8211; This property defines the HTTP status
code sent to the client with the <tt>sling:redirect</tt> response. If this property
is not set, it defaults to 302 (Found). Other status codes supported are 300 (Multiple Choices),
301 (Moved Permanently), 303 (See Other), and 307 (Temporary Redirect).</li>
	<li><tt>sling:internalRedirect</tt> &#8211; This property when set
on a node in the <tt>/etc/map</tt> tree (see below) causes the current path to
be modified internally to continue with resource resoltion.</li>
	<li><tt>sling:alias</tt> &#8211; The property may be set on any resource
to indicate an alias name for the resource. For example the resource <tt>/content/visitors</tt>
may have the <tt>sling:alias</tt> property set to <tt>besucher</tt>
allowing the resource to be addressed in an URL as <tt>/content/besucher</tt>.</li>
</ul>


<h3><a name="MappingsforResourceResolution-NodeTypes"></a>Node Types</h3>

<p>To ease with the definition of redirects and aliases, the following node types are
defined:</p>
<ul>
	<li><tt>sling:ResourceAlias</tt> &#8211; This mixin node type defines
the <tt>sling:alias</tt> property and may be attached to any node, which does
not otherwise allow setting a property named <tt>sling:alias</tt></li>
	<li><tt>sling:MappingSpec</tt> &#8211; This mixin node type defines
the <tt>sling:match</tt>, <tt>sling:redirect</tt>, <tt>sling:status</tt>,
and <tt>sling:internaleRedirect</tt> properties to define a matching and redirection
inside the <tt>/etc/map</tt> hierarchy.</li>
	<li><tt>sling:Mapping</tt> &#8211; Primary node type which may be used
to easily construct entries in the <tt>/etc/map</tt> tree. The node type extends
the <tt>sling:MappingSpec</tt> mixin node type to allow setting the required matching
and redirection. In addition the <tt>sling:Resource</tt> mixin node type is extended
to allow setting a resource type and the <tt>nt:hierarchyNode</tt> node type is
extended to allow locating nodes of this node type below <tt>nt:folder</tt> nodes.</li>
</ul>


<p>Note, that these node types only help setting the properties. The implementation
itself only cares for the properties and their values and not for any of these node types.</p>

<h2><a name="MappingsforResourceResolution-NamespaceMangling"></a>Namespace
Mangling</h2>

<p>There are systems accessing Sling, which have a hard time handling URLs containing
colons &#8211; <tt>:</tt> &#8211; in the path part correctly. Since URLs
produced and supported by Sling may colons because JCR Item based resources may be namespaced
(e.g. <tt>jcr:content</tt>), a special namespace mangling feature is built into
the <tt>ResourceResolver.resolve</tt> and <tt>ResourceResolver(map)</tt>
methods.</p>

<p>Namespace mangling operates such, that any namespace prefix identified in resource
path to be mapped as an URL in the <tt>map</tt> methods is modfied such that the
prefix is enclosed in underscores and the colon removed.</p>

<p><em>Example</em>: The path <tt>/content/_a_sample/jcr:content/jcr:data.png</tt>
is modified by namespace mangling in the <tt>map</tt> method to get at <tt>/content/_a_sample/_jcr_content/_jcr_data.png</tt>.</p>

<p>Conversely the <tt>resolve</tt> methods must undo such namespace mangling
to get back at the resource path. This is simple done by modifying any path such that segments
starting with an underscore enclosed prefix are changed by removing the underscores and adding
a colon after the prefix. There is one catch, tough: Due to the way the SlingPostServlets
automatically generates names, there may be cases where the actual name would be matching
this mechanism. Therefore only prefixes are modified which are actually namespace prefixes.</p>

<p><em>Example</em>: The path <tt>/content/_a_sample/<em>jcr_content/_jcr_data.png</em></tt>
<em>is modified by namespace mangling in the</em> <tt><em>resolve</em></tt>
<em>method to get</em> <tt><em>/content/_a_sample/jcr:content/jcr:data.png</em></tt><em>.
The prefix</em> <tt><em>&#95;a</em></tt><tt>}} is
not modified because there is no registered namespace with prefix {{a</tt>. On the other
hand the prefix <tt><em>jcr</em></tt> is modified because there is
of course a registered namespace with prefix <tt>jcr</tt>.</p>

<h2><a name="MappingsforResourceResolution-RootLevelMappings"></a>Root Level
Mappings</h2>

<p>Root Level Mappings apply to the request at large including the scheme, host.port
and uri path. To accomplish this a path is constructed from the request as {<tt>scheme}/{host.port}/{uri_path</tt>}.
This string is then matched against mapping entries below <tt>/etc/map</tt> which
are structured in the content analogously. The longest matching entry string is used and the
replacement, that is the redirection property, is applied.</p>

<h3><a name="MappingsforResourceResolution-MappingEntrySpecification"></a>Mapping
Entry Specification</h3>

<p>Each entry in the mapping table is a regular expression, which is constructed from
the resource path below <tt>/etc/map</tt>. If any resource along the path has
a <tt>sling:match</tt> property, the respective value is used in the corresponding
segment instead of the resource name. Only resources either having a <tt>sling:redirect</tt>
or <tt>sling:internalRedirect</tt> property are used as table entries. Other resources
in the tree are just used to build the mapping structure.</p>

<p><b>Example</b></p>

<p>Consider the following content</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>/etc/map
      +-- http
           +-- example.com.80
                +-- sling:redirect = "http://www.example.com/"
           +-- www.example.com.80
                +-- sling:internalRedirect = "/example"
           +-- any_example.com.80
                +-- sling:match = ".+\.example\.com\.80"
                +-- sling:redirect = "http://www.example.com/"
           +-- localhost_any
                +-- sling:match = "localhost\.\d*"
                +-- sling:internalRedirect = "/content"
                +-- cgi-bin
                     +-- sling:internalRedirect = "/scripts"
                +-- gateway
                     +-- sling:internalRedirect = "http://gbiv.com"
                +-- (stories)
                     +-- sling:internalRedirect = "/anecdotes/$1"
</pre>
</div></div>
<p>This would define the following mapping entries:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Regular Expression </th>
<th class='confluenceTh'> Redirect </th>
<th class='confluenceTh'> Internal </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> http/example.com.80 </td>
<td class='confluenceTd'> <a href="http://www.example.com" rel="nofollow">http://www.example.com</a>
</td>
<td class='confluenceTd'> no </td>
<td class='confluenceTd'> Redirect all requests to the Second Level Domain to www </td>
</tr>
<tr>
<td class='confluenceTd'> http/www.example.com.80 </td>
<td class='confluenceTd'> /example </td>
<td class='confluenceTd'> yes </td>
<td class='confluenceTd'> Prefix the URI paths of the requests sent to this domain with
the string <tt>/example</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> http/.+\.example\.com\.80 </td>
<td class='confluenceTd'> <a href="http://www.example.com" rel="nofollow">http://www.example.com</a>
</td>
<td class='confluenceTd'> no </td>
<td class='confluenceTd'> Redirect all requests to sub domains to www. The actual regular
expression for the host.port segment is taken from the <tt>sling:match</tt> property.
</td>
</tr>
<tr>
<td class='confluenceTd'> http/localhost\.\d&#42; </td>
<td class='confluenceTd'> /content </td>
<td class='confluenceTd'> yes </td>
<td class='confluenceTd'> Prefix the URI paths with <tt>/content</tt> for
requests to localhost, regardless of actual port the request was received on. This entry only
applies if the URI path does not start with <tt>/cgi-bin</tt>, <tt>gateway</tt>
or <tt>stories</tt> because there are longer match entries. The actual regular
expression for the host.port segment is taken from the <tt>sling:match</tt> property.
</td>
</tr>
<tr>
<td class='confluenceTd'> http/localhost\.\d*/cgi-bin </td>
<td class='confluenceTd'> /scripts </td>
<td class='confluenceTd'> yes </td>
<td class='confluenceTd'> Replace the <tt>/cgi-bin</tt> prefix in the URI
path with <tt>/scripts</tt> for requests to localhost, regardless of actual port
the request was received on. </td>
</tr>
<tr>
<td class='confluenceTd'> http/localhost\.\d*/gateway </td>
<td class='confluenceTd'> <a href="http://gbiv.com" rel="nofollow">http://gbiv.com</a>
</td>
<td class='confluenceTd'> yes </td>
<td class='confluenceTd'> Replace the <tt>/gateway</tt> prefix in the URI
path with <tt><a href="http://gbiv.com" rel="nofollow">http://gbiv.com</a></tt>
for requests to localhost, regardless of actual port the request was received on. </td>
</tr>
<tr>
<td class='confluenceTd'> http/localhost\.\d*/(stories) </td>
<td class='confluenceTd'> /anecdotes/stories </td>
<td class='confluenceTd'> yes </td>
<td class='confluenceTd'> Prepend the URI paths starting with <tt>/stories</tt>
with <tt>/anecdotes</tt> for requests to localhost, regardless of actual port
the request was received on. </td>
</tr>
</tbody></table>

<h3><a name="MappingsforResourceResolution-RegularExpressionmatching"></a>Regular
Expression matching</h3>

<p>As said above the mapping entries are regular expressions which are matched against
path. As such these regular expressions may also contain capturing groups as shown in the
example above: <tt>http/localhost\.\d*/(stories)</tt>. After matching the path
against the regular expression, the replacement pattern is applied which allows references
back to the capturing groups.</p>

<p>To illustrate the matching and replacement is applied according to the following
pseudo code:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> path = request.getScheme + <span class="code-quote">"/"</span>
+ request.getServerName() + <span class="code-quote">"."</span> + request.getServerPort()
+ <span class="code-quote">"/"</span> + request.getPathInfo();
<span class="code-object">String</span> result = <span class="code-keyword">null</span>;
<span class="code-keyword">for</span> (MapEntry entry: mapEntries) {
    Matcher matcher = entry.pattern.matcher(path);
    <span class="code-keyword">if</span> (matcher.find()) {
        <span class="code-object">StringBuffer</span> buf = <span class="code-keyword">new</span>
<span class="code-object">StringBuffer</span>();
        matcher.appendReplacement(buf, entry.getRedirect());
        matcher.appendTail(buf);
        result = buf.toString();
        <span class="code-keyword">break</span>;
    }
}
</pre>
</div></div>
<p>At the end of the loop, <tt>result</tt> contains the mapped path or <tt>null</tt>
if no entry matches the request <tt>path</tt>.</p>

<p><b>NOTE:</b> Since the entries in the <tt>/etc/map</tt> are
also used to reverse map any resource paths to URLs, using regular expressions in the Root
Level Mappings prevent the respective entries from being used for reverse mappings. Therefor,
it is strongly recommended to not use regular expression matching, unless you have a strong
need.</p>

<h3><a name="MappingsforResourceResolution-RedirectionValues"></a>Redirection
Values</h3>

<p>The result of matching the request path and getting the redirection is either a path
into the resource tree or another URL. If the result is an URL, it is converted into a path
again and matched against the mapping entries. This may be taking place repeatedly until an
absolute or relative path into the resource tree results.</p>

<p>The following pseudo code summarizes this behaviour:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> path = ....;
<span class="code-object">String</span> result = path;
<span class="code-keyword">do</span> {
    result = applyMapEntries(result);
} <span class="code-keyword">while</span> (isURL(result));
</pre>
</div></div>
<p>As soon as the result of applying the map entries is an absolute or relative path
(or no more map entries match), Root Level Mapping terminates and the next step in resource
resolution, resource tree access, takes place.</p>

<h2><a name="MappingsforResourceResolution-ResourceTreeAccess"></a>Resource
Tree Access</h2>

<p>The result of Root Level Mapping is an absolute or relative path to a resource. If
the path is relative &#8211; e.g. <tt>myproject/docroot/sample.gif</tt> &#8211;
the resource resolver search path (<tt>ResourceResolver.getSearchPath()</tt> is
used to build absolute paths and resolve the resource. In this case the first resource found
is used. If the result of Root Level Mapping is an absolute path, the path is used as is.</p>

<p>Accessing the resource tree after applying the Root Level Mappings has four options:</p>
<ul>
	<li>Check whether the path addresses a so called Star Resource. A Star Resource is
a resource whose path ends with or contains <tt>/&#42;</tt>. Such resources
are used by the <tt>SlingPostServlet</tt> to create new content below an existing
resource. If the path after Root Level Mapping is absolute, it is made absolute by prepending
the first search path entry.</li>
	<li>Check whether the path exists in the repository. if the path is absolute, it is
tried directly. Otherwise the search path entries are prepended  to the path until a resource
is found or the search path is exhausted without finding a resource.</li>
	<li>Drill down the resource tree starting from the root, optionally using the search
path until a resource is found.</li>
	<li>If no resource can be resolved, a Missing Resource is returned.</li>
</ul>


<h3><a name="MappingsforResourceResolution-DrillingDowntheResourceTree"></a>Drilling
Down the Resource Tree</h3>

<p>Drilling down the resource tree starts at the root and for each segement in the path
checks whether a child resource of the given name exists or not. If not, a child resource
is looked up, which has a <tt>sling:alias</tt> property whose value matches the
given name. If neither exists, the search is terminated and the resource cannot be resolved.</p>

<p>The following pseudo code shows this algorithm assuming the path is absolute:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> path = ...; <span class="code-comment">//
the absolute path
</span>Resource current = getResource(<span class="code-quote">"/"</span>);
<span class="code-object">String</span>[] segements = path.split(<span class="code-quote">"/"</span>);
<span class="code-keyword">for</span> (<span class="code-object">String</span>
segment: segments) {
    Resource child = getResource(current, segement);
    <span class="code-keyword">if</span> (child == <span class="code-keyword">null</span>)
{
        Iterator&lt;Resource&gt; children = listChildren(current);
        current = <span class="code-keyword">null</span>;
        <span class="code-keyword">while</span> (children.hasNext()) {
            child = children.next();
            <span class="code-keyword">if</span> (segment.equals(getSlingAlias(child)))
{
                current = child;
                <span class="code-keyword">break</span>;
            }
        }
        <span class="code-keyword">if</span> (current == <span class="code-keyword">null</span>)
{
            <span class="code-comment">// fail
</span>            <span class="code-keyword">break</span>;
        }
    } <span class="code-keyword">else</span> {
        current = child;
    }
}
</pre>
</div></div>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Mappings+for+Resource+Resolution">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=121245&revisedVersion=3&originalVersion=2">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Mappings+for+Resource+Resolution?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message