This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 7f0161f Automatic website deployment from
https://builds.apache.org/job/Sling/job/sling-site/job/master/422/
7f0161f is described below
commit 7f0161f69b5e4010f7a3ce6224b57635e4cc343b
Author: jenkins <[email protected]>
AuthorDate: Fri Aug 7 05:55:55 2020 +0000
Automatic website deployment from
https://builds.apache.org/job/Sling/job/sling-site/job/master/422/
---
.../mappings-for-resource-resolution.html | 117 ++++++++-------------
1 file changed, 46 insertions(+), 71 deletions(-)
diff --git
a/documentation/the-sling-engine/mappings-for-resource-resolution.html
b/documentation/the-sling-engine/mappings-for-resource-resolution.html
index baa3d85..088a6a9 100644
--- a/documentation/the-sling-engine/mappings-for-resource-resolution.html
+++ b/documentation/the-sling-engine/mappings-for-resource-resolution.html
@@ -125,40 +125,17 @@
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to
flexmark-java -->
</p>
<h2><a href="#configuration" id="configuration">Configuration</a></h2>
-<h3><a href="#properties" id="properties">Properties</a></h3>
-<p>The mapping of request URLs to resources is mainly configured in a
configuration tree which is (by default) located below <code>/etc/map</code>.
The actual location can be configured with the
<code>resource.resolver.map.location</code> property of the
<code>org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl</code>
configuration. That way you can even make it run mode specific, by taking
advantage of the Sling OSGi Installer's run mode awareness.</p>
-<p>When dealing with the new resource resolution we have a number of
properties influencing the process:</p>
+<p>The resource resolution (mapping a request path to a resource in Sling's
resource tree) can be influenced in different ways: - Root Level Mappings -
Alias Configurations - Vanity Path Configurations - Namespace Mangling</p>
+<h2><a href="#root-level-mappings" id="root-level-mappings">Root Level
Mappings</a></h2>
+<p>The mapping of request URLs to resources is mainly configured in a
configuration tree which is (by default) located below <code>/etc/map</code>.
While the actual location can be configured with the property
<code>resource.resolver.map.location</code> of the OSGi configuration
<code>org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl</code>,
it is suggested to leave the default value.</p>
+<p>When dealing with the resource resolution we have a number of properties
influencing the process:</p>
<ul>
-<li><code>sling:match</code> – This property when set on a node in the
<code>/etc/map</code> 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:
<code>/, :, [, ], *, ', ", \, |</code> and any whitespace except blank
space. In addition a name withou [...]
-<li><code>sling:redirect</code> – This property when set on a node in the
<code>/etc/map</code> 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 <code>Location</code> response header.</li>
+<li><code>sling:match</code> – This property when set on a resource in the
<code>/etc/map</code> tree (see below) defines a partial regular expression
which is used instead of the resource'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: <code>/, :, [, ], *, ', ", \, |</code> and any whitespace except
blank space. In addition a nam [...]
+<li><code>sling:redirect</code> – This property when set on a resource in the
<code>/etc/map</code> 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 <code>Location</code> response header.</li>
<li><code>sling:status</code> – This property defines the HTTP status code
sent to the client with the <code>sling:redirect</code> 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><code>sling:internalRedirect</code> – This property when set on a node in
the <code>/etc/map</code> tree (see below) causes the current path to be
modified internally to continue with resource resolution. This is a multi-value
property, i.e. multiple paths can be given here, which are tried one after
another until one resolved to a resource.</li>
-<li><code>sling:alias</code> – The property may be set on any resource to
indicate an alias name for the resource. For example the resource
<code>/content/visitors</code> may have the <code>sling:alias</code> property
set to <code>besucher</code> allowing the resource to be addressed in an URL as
<code>/content/besucher</code>.</li>
-</ul>
-<h4><a href="#limitation-of-slingalias-for-principal-with-a-limited-access"
id="limitation-of-slingalias-for-principal-with-a-limited-access">Limitation of
<code>sling:alias</code> for Principal with a limited access</a></h4>
-<p>Assuming there is</p>
-<ul>
-<li>An User named <code>testuser</code></li>
-<li>An ACE with deny <code>jcr:all</code> in <code>/</code> for
<code>everyone</code></li>
-<li>An ACE with allow <code>jcr:read</code> in <code>/content</code> for
<code>testuser</code></li>
+<li><code>sling:internalRedirect</code> – This property when set on a resource
in the <code>/etc/map</code> tree (see below) causes the current path to be
modified internally to continue with resource resolution. This is a multi-value
property, i.e. multiple paths can be given here, which are tried one after
another until one resolved to a resource.</li>
</ul>
-<p>If the <code>sling:alias</code> property (e.g. <code>myalias</code>) is set
directly in <code>/content</code>, the User <code>testuser</code> will not be
able to address the resource <code>/content</code> in an URL as
<code>/myalias</code>. Instead if the <code>sling:alias</code> property is set
in any resource under <code>/content</code> (e.g.
<code>/content/visitors</code>) the <code>sling:alias</code> feature will work
as usual.</p>
-<h3><a href="#node-types" id="node-types">Node Types</a></h3>
-<p>To ease with the definition of redirects and aliases, the following node
types are defined:</p>
-<ul>
-<li><code>sling:ResourceAlias</code> – This mixin node type defines the
<code>sling:alias</code> property and may be attached to any node, which does
not otherwise allow setting a property named <code>sling:alias</code></li>
-<li><code>sling:MappingSpec</code> – This mixin node type defines the
<code>sling:match</code>, <code>sling:redirect</code>,
<code>sling:status</code>, and <code>sling:internaleRedirect</code> properties
to define a matching and redirection inside the <code>/etc/map</code>
hierarchy.</li>
-<li><code>sling:Mapping</code> – Primary node type which may be used to easily
construct entries in the <code>/etc/map</code> tree. The node type extends the
<code>sling:MappingSpec</code> mixin node type to allow setting the required
matching and redirection. In addition the <code>sling:Resource</code> mixin
node type is extended to allow setting a resource type and the
<code>nt:hierarchyNode</code> node type is extended to allow locating nodes of
this node type below <code>nt:folder</c [...]
-</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 href="#namespace-mangling" id="namespace-mangling">Namespace
Mangling</a></h2>
-<p>There are systems accessing Sling, which have a hard time handling URLs
containing colons (<code>:</code>) in the path part correctly. Since URLs
produced and supported by Sling may contain colons because JCR item based
resources may be namespaced (e.g. <code>jcr:content</code>), a special
namespace mangling feature is built into the
<code>ResourceResolver.resolve(...)</code> and
<code>ResourceResolver.map(...)</code> methods.</p>
-<p>Namespace mangling operates such, that any namespace prefix identified in
resource path to be mapped as an URL in the <code>map</code> methods is
modified such that the prefix is enclosed in underscores and the colon is
removed.</p>
-<p><em>Example</em>: The path
<code>/content/_a_sample/jcr:content/jcr:data.png</code> is modified by
namespace mangling in the <code>map</code> method to
<code>/content/_a_sample/_jcr_content/_jcr_data.png</code>.</p>
-<p>Conversely, the <code>resolve</code> 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 <code>SlingPostServlet</code> automatically
generates names, there may be cases where the actual name would be matching
this mechanism. Therefore on [...]
-<p><em>Example</em>: The path
<code>/content/_a_sample/_jcr_content/_jcr_data.png</code> is modified by
namespace mangling in the <code>resolve</code> method to get
<code>/content/_a_sample/jcr:content/jcr:data.png</code>. The prefix
<code>_a_</code> is not modified because there is no registered namespace with
prefix <code>a</code>. On the other hand the prefix <code>jcr</code> is
modified because there is of course a registered namespace with prefix
<code>jcr</code>.</p>
-<h2><a href="#root-level-mappings" id="root-level-mappings">Root Level
Mappings</a></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 lik this <code>{scheme}/{host}.{port}/{uri_path}</code>. This string is
then matched against mapping entries below <code>/etc/map</code> 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>
+<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 like this <code>{scheme}/{host}.{port}/{uri_path}</code>. This string
is then matched against mapping entries below <code>/etc/map</code> 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 href="#mapping-entry-specification"
id="mapping-entry-specification">Mapping Entry Specification</a></h3>
<p>Each entry in the mapping table is a regular expression, which is
constructed from the resource path below <code>/etc/map</code>. If any resource
along the path has a <code>sling:match</code> property, the respective value is
used in the corresponding segment instead of the resource name. Only resources
either having a <code>sling:redirect</code> or
<code>sling:internalRedirect</code> property are used as table entries. Other
resources in the tree are just used to build the mapping st [...]
<p><em>Example</em></p>
@@ -285,9 +262,9 @@ for (String segment: segments) {
}
</code></pre>
<h2><a href="#string-interpolation-for-etcmap"
id="string-interpolation-for-etcmap">String Interpolation for /etc/map</a></h2>
-<p>Setting up <code>/etc/map</code> for different instances like <em>dev,
stage, qa and production</em> was time consuming and error prone due to
copy-n-paste errors.</p>
-<p>With <a
href="https://issues.apache.org/jira/browse/SLING-7768";>SLING-7768</a> Sling
now supports String Interpolation under <code>/etc/map</code>.</p>
-<p>With this it is possible to add placeholders to
<strong>sling:match</strong> entries to adapt them to different
environments.</p>
+<p>Setting up <code>/etc/map</code> for different environments like <em>dev,
stage, qa and production</em> was time consuming and error prone due to
copy-n-paste errors.</p>
+<p>With <a
href="https://issues.apache.org/jira/browse/SLING-7768";>SLING-7768</a> Sling
now supports String Interpolation under <code>/etc/map</code>. Before you had
to configure the location of the mapping and make it run mode aware by taking
advantage of the Sling OSGi Installer's run mode awareness.</p>
+<p>With the string interpolation feature it is possible to add placeholders to
<strong>sling:match</strong> entries to adapt them to different
environments.</p>
<p>The values are either provided by System, Bundle Context or String
Interpolation Configuration values.</p>
<p>The placeholders have this format: <strong>$['type':'name';default='default
value']</strong>.</p>
<p>The type can be:</p>
@@ -305,51 +282,35 @@ for (String segment: segments) {
<p>Now go to <strong>composum</strong> and go to that node. If it does not
exist then create one.</p>
<p>The mapping should look like this:</p>
<ul>
-<li>etc
-<ul>
-<li>map
-<ul>
-<li>http
-<ul>
-<li>my-mapping
-<ul>
-<li>sling:match=$[phv.fq.host.name].8080</li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-</li>
+<li>etc * map * http * my-mapping * sling:match=$[phv.fq.host.name].8080</li>
</ul>
<p>Opening the page <strong>http://localhost:8080/starter/index.html</strong>
should work just fine.</p>
<p>This is a mapping from System Properties with a default:</p>
<ul>
-<li>etc
-<ul>
-<li>map
-<ul>
-<li>http
-<ul>
-<li>my-mapping
-<ul>
-<li>sling:match=$[env:phv.fq.host.name;default=localhost].8080</li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-</li>
+<li>etc * map * http * my-mapping *
sling:match=$[env:phv.fq.host.name;default=localhost].8080</li>
</ul>
<h3><a href="#testing-etcmap-interpolation"
id="testing-etcmap-interpolation">Testing /etc/map interpolation</a></h3>
<p>Now got back to the String Interpolation configuration and change the value
to <strong>qa.author.acme.com</strong> and save it.</p>
<p>For local testing open your <strong>hosts</strong> file (/etc/hosts on
Unix) and add a line like this: <code>127.0.0.1 qa.author.acme.com</code> save
it and test with <code>ping qa.author.acme.com</code> to make sure the name
resolves. Now you should be able to open the same page with:
<strong>http://qa.author.acme.com/starter/index.html</strong>.</p>
<p>Now do the same with
<strong>phv.fq.host.name=staging.author.acme.com</strong>.</p>
<p>The String Interpolation works with any part of the etc-map tree.</p>
-<h2><a href="#rebuilding-the-vanity-bloom-filter"
id="rebuilding-the-vanity-bloom-filter">Rebuilding The Vanity Bloom
Filter</a></h2>
+<h2><a href="#alias-configurations" id="alias-configurations">Alias
Configurations</a></h2>
+<p>The property <code>sling:alias</code> may be set on any resource to
indicate an alias name for the resource. For example the resource
<code>/content/visitors</code> may have the <code>sling:alias</code> property
set to <code>besucher</code> allowing the resource to be addressed in an URL as
<code>/content/besucher</code> as well as the original path
<code>/content/visitors</code>.</p>
+<h3><a href="#impact-of-alias-handling" id="impact-of-alias-handling">Impact
of Alias Handling</a></h3>
+<p>In general, the number of aliases have a direct impact on the performance
of the resource resolution - as basically all possible permutations of paths
for a resource have to be tested against the incoming request path. By default
a cache is used to speed up handling aliases during resolving resources. It is
highly recommended to have this cache enabled to avoid slowing down request
performance. However, the cache might have an impact on startup time and on the
alias update time if the [...]
+<p>The cache can be disabled by setting the property
<code>resource.resolver.optimize.alias.resolution</code> of the OSGi
configuration
<code>org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl</code>
to <code>false</code>.</p>
+<h3><a href="#limitation-of-slingalias-for-principal-with-a-limited-access"
id="limitation-of-slingalias-for-principal-with-a-limited-access">Limitation of
<code>sling:alias</code> for Principal with a limited access</a></h3>
+<p>Assuming there is * An User named <code>testuser</code> * An ACE with deny
<code>jcr:all</code> in <code>/</code> for <code>everyone</code> * An ACE with
allow <code>jcr:read</code> in <code>/content</code> for
<code>testuser</code></p>
+<p>If the <code>sling:alias</code> property (e.g. <code>myalias</code>) is set
directly in <code>/content</code>, the User <code>testuser</code> will not be
able to address the resource <code>/content</code> in an URL as
<code>/myalias</code>. Instead if the <code>sling:alias</code> property is set
in any resource under <code>/content</code> (e.g.
<code>/content/visitors</code>) the <code>sling:alias</code> feature will work
as usual.</p>
+<h2><a href="#vanity-path-configuration" id="vanity-path-configuration">Vanity
Path Configuration</a></h2>
+<p>While an alias can provide a variation for a resource name, a vanity path
can provide an alternative path for a resource. The following properties can be
set on a resource:</p>
+<ul>
+<li><code>sling:vanityPath</code> – This property when set on any resource
defines an alternative path to address the resource.</li>
+<li><code>sling:redirect</code> – This property when set on a resource with a
vanity path 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
<code>Location</code> response header.</li>
+<li><code>sling:redirectStatus</code> – This property defines the HTTP status
code sent to the client with the <code>sling:redirect</code> 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><code>sling:vanityOrder</code> – It might happen that several resources in
the resource tree specify the same vanity path. In that case the one with the
highest order is used. This property can be used to set such an order.</li>
+</ul>
+<h3><a href="#rebuilding-the-vanity-bloom-filter"
id="rebuilding-the-vanity-bloom-filter">Rebuilding The Vanity Bloom
Filter</a></h3>
<p><a href="https://issues.apache.org/jira/browse/SLING-4216";>SLING-4216</a>
introduced the usage of a bloom filter in order to resolve long startup time
with many vanityPath entries. The bloom filter is handled automatically by the
Sling framework. In some cases though, as changing the maximum number of vanity
bloom filter bytes, a rebuild of the vanity bloom filter is needed.</p>
<p>In order to rebuild vanity bloom filter:</p>
<ul>
@@ -359,8 +320,22 @@ for (String segment: segments) {
<li>delete the vanityBloomFilter.txt file</li>
<li>start Apache Sling (this might take few minutes, depending on how many
vanity path entries are present)</li>
</ul>
+<h2><a href="#namespace-mangling" id="namespace-mangling">Namespace
Mangling</a></h2>
+<p>There are systems accessing Sling, which have a hard time handling URLs
containing colons (<code>:</code>) in the path part correctly. Since URLs
produced and supported by Sling may contain colons as JCR based resources may
be namespaced (e.g. <code>jcr:content</code>), a special namespace mangling
feature is built into the <code>ResourceResolver.resolve(...)</code> and
<code>ResourceResolver.map(...)</code> methods.</p>
+<p>Namespace mangling operates such, that any namespace prefix identified in a
resource path to be mapped as an URL in the <code>map</code> methods is
modified such that the prefix is enclosed in underscores and the colon is
removed.</p>
+<p><em>Example</em>: The path
<code>/content/_a_sample/jcr:content/jcr:data.png</code> is modified by
namespace mangling in the <code>map</code> method to
<code>/content/_a_sample/_jcr_content/_jcr_data.png</code>.</p>
+<p>Conversely, the <code>resolve</code> 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: Due to the way the <code>SlingPostServlet</code> automatically generates
names, there may be cases where the actual name would be matching this
mechanism. Therefore only pref [...]
+<p><em>Example</em>: The path
<code>/content/_a_sample/_jcr_content/_jcr_data.png</code> is modified by
namespace mangling in the <code>resolve</code> method to get
<code>/content/_a_sample/jcr:content/jcr:data.png</code>. The prefix
<code>_a_</code> is not modified because there is no registered namespace with
prefix <code>a</code>. On the other hand the prefix <code>jcr</code> is
modified because there is of course a registered namespace with prefix
<code>jcr</code>.</p>
<h2><a href="#debugging-issues" id="debugging-issues">Debugging Issues</a></h2>
-<p>Use the Felix Web Console Plugin provided at
<code>/system/console/jcrresolver</code> to inspect both the mapping and the
resolver map entries. Also you can check what either
<code>ResourceResolver.map(...)</code> or
<code>ResourceResolver.resolve(...)</code> would return for a given
URL/path.</p>
+<p>Use the Apache Felix Web Console Plugin provided at
<code>/system/console/jcrresolver</code> to inspect both the mapping and the
resolver map entries. Also you can check what either
<code>ResourceResolver.map(...)</code> or
<code>ResourceResolver.resolve(...)</code> would return for a given
URL/path.</p>
+<h2><a href="#jcr-node-types" id="jcr-node-types">JCR Node Types</a></h2>
+<p>To ease with the definition of redirects and aliases when using nodes in a
JCR repository, the following node types are defined:</p>
+<ul>
+<li><code>sling:ResourceAlias</code> – This mixin node type defines the
<code>sling:alias</code> property and may be attached to any node, which does
not otherwise allow setting a property named <code>sling:alias</code></li>
+<li><code>sling:MappingSpec</code> – This mixin node type defines the
<code>sling:match</code>, <code>sling:redirect</code>,
<code>sling:status</code>, and <code>sling:internaleRedirect</code> properties
to define a matching and redirection inside the <code>/etc/map</code>
hierarchy.</li>
+<li><code>sling:Mapping</code> – Primary node type which may be used to easily
construct entries in the <code>/etc/map</code> tree. The node type extends the
<code>sling:MappingSpec</code> mixin node type to allow setting the required
matching and redirection. In addition the <code>sling:Resource</code> mixin
node type is extended to allow setting a resource type and the
<code>nt:hierarchyNode</code> node type is extended to allow locating nodes of
this node type below <code>nt:folder</c [...]
+</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>
</section></div></div>
</div>
</div>
@@ -368,7 +343,7 @@ for (String segment: segments) {
</div><footer class="footer">
<div class="content has-text-centered is-small">
<div class="revisionInfo">
- Last modified by <span class="author">Bertrand
Delacretaz</span> on <span class="comment">Wed Jun 24 14:37:56 2020 +0200</span>
+ Last modified by <span class="author">Carsten
Ziegeler</span> on <span class="comment">Fri Aug 7 07:53:28 2020 +0200</span>
</div> <p>
Apache Sling, Sling, Apache, the Apache feather logo,
and the Apache Sling project logo are trademarks of The Apache Software
Foundation. All other marks mentioned may be trademarks or registered
trademarks of their respective owners.
</p><p>
