This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new 9a86f29 SLING-9645 : Update resource mapping documentation
9a86f29 is described below
commit 9a86f29328287c767084de74e33497496ec2292d
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Fri Aug 7 07:53:28 2020 +0200
SLING-9645 : Update resource mapping documentation
---
.../mappings-for-resource-resolution.md | 188 ++++++++++-----------
1 file changed, 93 insertions(+), 95 deletions(-)
diff --git
a/src/main/jbake/content/documentation/the-sling-engine/mappings-for-resource-resolution.md
b/src/main/jbake/content/documentation/the-sling-engine/mappings-for-resource-resolution.md
index 1c14cb5..9c02105 100644
---
a/src/main/jbake/content/documentation/the-sling-engine/mappings-for-resource-resolution.md
+++
b/src/main/jbake/content/documentation/the-sling-engine/mappings-for-resource-resolution.md
@@ -8,57 +8,24 @@ tags=core,resources,resourcemappings
## Configuration
+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
-### Properties
-
-The mapping of request URLs to resources is mainly configured in a
configuration tree which is (by default) located below `/etc/map`. The actual
location can be configured with the `resource.resolver.map.location` property
of the `org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl`
configuration.
-That way you can even make it run mode specific, by taking advantage of the
Sling OSGi Installer's run mode awareness.
+## Root Level Mappings
+The mapping of request URLs to resources is mainly configured in a
configuration tree which is (by default) located below `/etc/map`. While the
actual location can be configured with the property
`resource.resolver.map.location` of the OSGi configuration
`org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl`, it is
suggested to leave the default value.
-When dealing with the new resource resolution we have a number of properties
influencing the process:
+When dealing with the resource resolution we have a number of properties
influencing the process:
-* `sling:match` – This property when set on a node in the `/etc/map`
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: `/, :, [, ], *, ',
", \, |` and any whitespace except blank space. In addition a name without a
name space may not be `.` or ` [...]
-* `sling:redirect` – This property when set on a node in the `/etc/map`
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 `Location` response header.
+* `sling:match` – This property when set on a resource in the `/etc/map`
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: `/, :, [, ], *, ',
", \, |` and any whitespace except blank space. In addition a name without a
name space may not be [...]
+* `sling:redirect` – This property when set on a resource in the
`/etc/map` 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 `Location` response header.
* `sling:status` – This property defines the HTTP status code sent to
the client with the `sling:redirect` 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).
-* `sling:internalRedirect` – This property when set on a node in the
`/etc/map` 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.
-* `sling:alias` – The property may be set on any resource to indicate an
alias name for the resource. For example the resource `/content/visitors` may
have the `sling:alias` property set to `besucher` allowing the resource to be
addressed in an URL as `/content/besucher`.
-
-#### Limitation of `sling:alias` for Principal with a limited access
-
-Assuming there is
-
-* An User named `testuser`
-* An ACE with deny `jcr:all` in `/` for `everyone`
-* An ACE with allow `jcr:read` in `/content` for `testuser`
+* `sling:internalRedirect` – This property when set on a resource in the
`/etc/map` 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.
-If the `sling:alias` property (e.g. `myalias`) is set directly in `/content`,
the User `testuser` will not be able to address the resource `/content` in an
URL as `/myalias`.
-Instead if the `sling:alias` property is set in any resource under `/content`
(e.g. `/content/visitors`) the `sling:alias` feature will work as usual.
-
-### Node Types
-
-To ease with the definition of redirects and aliases, the following node types
are defined:
-
-* `sling:ResourceAlias` – This mixin node type defines the `sling:alias`
property and may be attached to any node, which does not otherwise allow
setting a property named `sling:alias`
-* `sling:MappingSpec` – This mixin node type defines the `sling:match`,
`sling:redirect`, `sling:status`, and `sling:internaleRedirect` properties to
define a matching and redirection inside the `/etc/map` hierarchy.
-* `sling:Mapping` – Primary node type which may be used to easily
construct entries in the `/etc/map` tree. The node type extends the
`sling:MappingSpec` mixin node type to allow setting the required matching and
redirection. In addition the `sling:Resource` mixin node type is extended to
allow setting a resource type and the `nt:hierarchyNode` node type is extended
to allow locating nodes of this node type below `nt:folder` nodes.
-
-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.
-
-## Namespace Mangling
-
-There are systems accessing Sling, which have a hard time handling URLs
containing colons (`:`) 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. `jcr:content`), a special namespace mangling feature is built
into the `ResourceResolver.resolve(...)` and `ResourceResolver.map(...)`
methods.
-
-Namespace mangling operates such, that any namespace prefix identified in
resource path to be mapped as an URL in the `map` methods is modified such that
the prefix is enclosed in underscores and the colon is removed.
-
-*Example*: The path `/content/_a_sample/jcr:content/jcr:data.png` is modified
by namespace mangling in the `map` method to
`/content/_a_sample/_jcr_content/_jcr_data.png`.
-
-Conversely, the `resolve` 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 `SlingPostServlet` automatically generates names, there may
be cases where the actual name would be matching this mechanism. Therefore only
prefixes are modified [...]
-
-*Example*: The path `/content/_a_sample/_jcr_content/_jcr_data.png` is
modified by namespace mangling in the `resolve` method to get
`/content/_a_sample/jcr:content/jcr:data.png`. The prefix `_a_` is not modified
because there is no registered namespace with prefix `a`. On the other hand the
prefix `jcr` is modified because there is of course a registered namespace with
prefix `jcr`.
-
-## Root Level Mappings
-
-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 `{scheme}/{host}.{port}/{uri_path}`. This string is then matched
against mapping entries below `/etc/map` which are structured in the content
analogously. The longest matching entry string is used and the replacement,
that is the redirection property, is applied.
+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 `{scheme}/{host}.{port}/{uri_path}`. This string is then matched
against mapping entries below `/etc/map` which are structured in the content
analogously. The longest matching entry string is used and the replacement,
that is the redirection property, is applied.
### Mapping Entry Specification
@@ -129,18 +96,18 @@ At the end of the loop, `result` contains the mapped path
or `null` if no entry
#### Regular Expressions for Reverse Mappings
-By default using regular expressions with wildcards will prevent to use the
mapping entry for reverse mappings (see above).
+By default using regular expressions with wildcards will prevent to use the
mapping entry for reverse mappings (see above).
-There is one exception though: If there is a `sling:internalRedirect` property
containing a regular expression the map entry will be *exclusively used for
reverse mappings* (i.e. used only for `ResourceResolver.map(...)`) (see also
[SLING-2560](https://issues.apache.org/jira/browse/SLING-2560)). The same
resource may carry a `sling:match` property with wildcards and groups referring
to the groups being defined in the `sling:internalRedirect` property.
+There is one exception though: If there is a `sling:internalRedirect` property
containing a regular expression the map entry will be *exclusively used for
reverse mappings* (i.e. used only for `ResourceResolver.map(...)`) (see also
[SLING-2560](https://issues.apache.org/jira/browse/SLING-2560)). The same
resource may carry a `sling:match` property with wildcards and groups referring
to the groups being defined in the `sling:internalRedirect` property.
-This example
+This example
/etc/map
+-- http
+-- example.com.80
| +-- sling:internalRedirect = "/content/([^/]+)/home/(.*)"
| +-- sling:match = "$1/index/$2"
-
+
leads to the following entry being used in the reverse mapping table:
| Pattern | Replacement |
@@ -207,18 +174,13 @@ The following pseudo code shows this algorithm assuming
the path is absolute:
## String Interpolation for /etc/map
-Setting up `/etc/map` for different instances like _dev, stage,
-qa and production_ was time consuming and error prone due to copy-n-paste
-errors.
+Setting up `/etc/map` for different environments like _dev, stage, qa and
production_ was time consuming and error prone due to copy-n-paste errors.
-With [SLING-7768](https://issues.apache.org/jira/browse/SLING-7768) Sling
-now supports String Interpolation under `/etc/map`.
+With [SLING-7768](https://issues.apache.org/jira/browse/SLING-7768) Sling now
supports String Interpolation under `/etc/map`. 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.
-With this it is possible to add placeholders to **sling:match** entries
-to adapt them to different environments.
+With the string interpolation feature it is possible to add placeholders to
**sling:match** entries to adapt them to different environments.
-The values are either provided by System, Bundle Context or String
Interpolation
-Configuration values.
+The values are either provided by System, Bundle Context or String
Interpolation Configuration values.
The placeholders have this format: **$['type':'name';default='default
value']**.
@@ -228,67 +190,82 @@ The type can be:
* **prop**: taken from the Bundle Context Properties
* otherwise: taken from the String Interpolation Configuration
-With this it is possible to create a single set of `/etc/map` definitions and
-then adjust the actual values of an instance by an OSGi configuration.
+With this it is possible to create a single set of `/etc/map` definitions and
then adjust the actual values of an instance by an OSGi configuration.
-**Note**: the placeholder **must be placed** into a **sling:match** entry
-and cannot be the JCR Node name, as some of the characters are not allowed.
+**Note**: the placeholder **must be placed** into a **sling:match** entry and
cannot be the JCR Node name, as some of the characters are not allowed.
### Setting up /etc/map interpolation
-The Substitution Configuration can be found in the OSGi Configuration
-as **Apache Sling String Interpolation Provider**.
+The Substitution Configuration can be found in the OSGi Configuration as
**Apache Sling String Interpolation Provider**.
-The property **Placeholder Values** takes a list of **key=value** entries
-where each of them map a variable with its actual value.
+The property **Placeholder Values** takes a list of **key=value** entries
where each of them map a variable with its actual value.
-In our little introduction we add an entry of
-**phv.default.host.name=localhost**. Save the configuration for now.
-Before going on make sure that you know Mapping Location configuration
-in the OSGi configuration of **Apache Sling Resource Resolver Factory**.
+In our little introduction we add an entry of
**phv.default.host.name=localhost**. Save the configuration for now. Before
going on make sure that you know Mapping Location configuration in the OSGi
configuration of **Apache Sling Resource Resolver Factory**.
-Now go to **composum** and go to that node. If it does not exist then create
-one.
+Now go to **composum** and go to that node. If it does not exist then create
one.
The mapping should look like this:
-* etc
- * map
- * http
- * my-mapping
- * sling:match=$\[phv.fq.host.name\].8080
-
-Opening the page **http://localhost:8080/starter/index.html** should
-work just fine.
+ * etc
+ * map
+ * http
+ * my-mapping
+ * sling:match=$\[phv.fq.host.name\].8080
+
+Opening the page **http://localhost:8080/starter/index.html** should work just
fine.
This is a mapping from System Properties with a default:
-* etc
- * map
- * http
- * my-mapping
- * sling:match=$\[env:phv.fq.host.name;default=localhost\].8080
+ * etc
+ * map
+ * http
+ * my-mapping
+ *
sling:match=$\[env:phv.fq.host.name;default=localhost\].8080
### Testing /etc/map interpolation
-Now got back to the String Interpolation configuration and change the value
-to **qa.author.acme.com** and save it.
+Now got back to the String Interpolation configuration and change the value to
**qa.author.acme.com** and save it.
-For local testing open your **hosts** file (/etc/hosts on Unix) and add a
-line like this:
+For local testing open your **hosts** file (/etc/hosts on Unix) and add a line
like this:
```
127.0.0.1 qa.author.acme.com
```
-save it and test with `ping qa.author.acme.com` to make sure the name
-resolves.
-Now you should be able to open the same page with:
-**http://qa.author.acme.com/starter/index.html**.
+save it and test with `ping qa.author.acme.com` to make sure the name
resolves. Now you should be able to open the same page with:
**http://qa.author.acme.com/starter/index.html**.
Now do the same with **phv.fq.host.name=staging.author.acme.com**.
The String Interpolation works with any part of the etc-map tree.
-## Rebuilding The Vanity Bloom Filter
+## Alias Configurations
+
+The property `sling:alias` may be set on any resource to indicate an alias
name for the resource. For example the resource `/content/visitors` may have
the `sling:alias` property set to `besucher` allowing the resource to be
addressed in an URL as `/content/besucher` as well as the original path
`/content/visitors`.
+
+### Impact of Alias Handling
+
+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 nu [...]
+
+The cache can be disabled by setting the property
`resource.resolver.optimize.alias.resolution` of the OSGi configuration
`org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl` to
`false`.
+
+### Limitation of `sling:alias` for Principal with a limited access
+
+Assuming there is
+* An User named `testuser`
+* An ACE with deny `jcr:all` in `/` for `everyone`
+* An ACE with allow `jcr:read` in `/content` for `testuser`
+
+If the `sling:alias` property (e.g. `myalias`) is set directly in `/content`,
the User `testuser` will not be able to address the resource `/content` in an
URL as `/myalias`.
+Instead if the `sling:alias` property is set in any resource under `/content`
(e.g. `/content/visitors`) the `sling:alias` feature will work as usual.
+
+## Vanity Path Configuration
+
+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:
+
+* `sling:vanityPath` – This property when set on any resource defines an
alternative path to address the resource.
+* `sling:redirect` – 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
`Location` response header.
+* `sling:redirectStatus` – This property defines the HTTP status code
sent to the client with the `sling:redirect` 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).
+* `sling:vanityOrder` – 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.
+
+### Rebuilding The Vanity Bloom Filter
[SLING-4216](https://issues.apache.org/jira/browse/SLING-4216) 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.
@@ -301,7 +278,28 @@ In order to rebuild vanity bloom filter:
* delete the vanityBloomFilter.txt file
* start Apache Sling (this might take few minutes, depending on how many
vanity path entries are present)
+## Namespace Mangling
+
+There are systems accessing Sling, which have a hard time handling URLs
containing colons (`:`) in the path part correctly. Since URLs produced and
supported by Sling may contain colons as JCR based resources may be namespaced
(e.g. `jcr:content`), a special namespace mangling feature is built into the
`ResourceResolver.resolve(...)` and `ResourceResolver.map(...)` methods.
+
+Namespace mangling operates such, that any namespace prefix identified in a
resource path to be mapped as an URL in the `map` methods is modified such that
the prefix is enclosed in underscores and the colon is removed.
+
+*Example*: The path `/content/_a_sample/jcr:content/jcr:data.png` is modified
by namespace mangling in the `map` method to
`/content/_a_sample/_jcr_content/_jcr_data.png`.
+
+Conversely, the `resolve` 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 `SlingPostServlet` automatically generates names, there may be
cases where the actual name would be matching this mechanism. Therefore only
prefixes are modified which a [...]
+
+*Example*: The path `/content/_a_sample/_jcr_content/_jcr_data.png` is
modified by namespace mangling in the `resolve` method to get
`/content/_a_sample/jcr:content/jcr:data.png`. The prefix `_a_` is not modified
because there is no registered namespace with prefix `a`. On the other hand the
prefix `jcr` is modified because there is of course a registered namespace with
prefix `jcr`.
+
## Debugging Issues
-Use the Felix Web Console Plugin provided at `/system/console/jcrresolver` to
inspect both the mapping and the resolver map entries. Also you can check what
either `ResourceResolver.map(...)` or `ResourceResolver.resolve(...)` would
return for a given URL/path.
+Use the Apache Felix Web Console Plugin provided at
`/system/console/jcrresolver` to inspect both the mapping and the resolver map
entries. Also you can check what either `ResourceResolver.map(...)` or
`ResourceResolver.resolve(...)` would return for a given URL/path.
+
+## JCR Node Types
+
+To ease with the definition of redirects and aliases when using nodes in a JCR
repository, the following node types are defined:
+
+* `sling:ResourceAlias` – This mixin node type defines the `sling:alias`
property and may be attached to any node, which does not otherwise allow
setting a property named `sling:alias`
+* `sling:MappingSpec` – This mixin node type defines the `sling:match`,
`sling:redirect`, `sling:status`, and `sling:internaleRedirect` properties to
define a matching and redirection inside the `/etc/map` hierarchy.
+* `sling:Mapping` – Primary node type which may be used to easily
construct entries in the `/etc/map` tree. The node type extends the
`sling:MappingSpec` mixin node type to allow setting the required matching and
redirection. In addition the `sling:Resource` mixin node type is extended to
allow setting a resource type and the `nt:hierarchyNode` node type is extended
to allow locating nodes of this node type below `nt:folder` nodes.
+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.
