SLING-9645 : Update resource mapping documentation
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 @@
## Configuration
-
-### 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.
-
-
-When dealing with the new 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 `..` and a blank space is only allowed inside the name.
-* `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: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`
-
-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 which are actually namespace prefixes.
-
-*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`.
+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
## 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.
+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 resource resolution we have a number of properties influencing the process:
+
+* `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 `.` or `..` and a blank space is only allowed inside the name.
+* `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 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.
+
+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 @@
#### 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 @@
## 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 @@
* **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 number of aliases is huge (over 10000).
+
+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 @@
* 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 are actually namespace prefixes.
+
+*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.
