svn commit: r1739954 - /sling/site/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.mdtext

[kw...@apache.org]

Author: kwin
Date: Tue Apr 19 16:04:39 2016
New Revision: 1739954

URL: http://svn.apache.org/viewvc?rev=1739954&view=rev
Log:
SLING-2560 document how to add mapping entries only for reverse mapping

some minor fixes

Modified:
    sling/site/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.mdtext

Modified: sling/site/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.mdtext?rev=1739954&r1=1739953&r2=1739954&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.mdtext Tue Apr 19 16:04:39 2016
@@ -6,11 +6,12 @@ Title: Mappings for Resource Resolution
 ### 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]({{ refs.sling-settings-org-apache-sling-settings.path }}) by having a unique path per [run mode specific OSGi configuration]({{ refs./jcr-installer-provider.path }}).
 
 
 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: /, :, \[, \]({{ refs..path }}), \*, ', ", \| 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: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.
@@ -84,7 +85,7 @@ This would define the following mapping
 | http/localhost\.\d*/gateway | http://gbiv.com | yes | Replace the `/gateway` prefix in the URI path with `http://gbiv.com` for requests to localhost, regardless of actual port the request was received on. |
 | http/localhost\.\d*/(stories) | /anecdotes/stories | yes | Prepend the URI paths starting with `/stories` with `/anecdotes` for requests to localhost, regardless of actual port the request was received on. |
 
-### Regular Expression matching
+### Regular Expression Matching
 
 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: `http/localhost\.\d*/(stories)`. After matching the path against the regular expression, the replacement pattern is applied which allows references back to the capturing groups.
 
@@ -107,7 +108,28 @@ To illustrate the matching and replaceme
 
 At the end of the loop, `result` contains the mapped path or `null` if no entry matches the request `path`.
 
-**NOTE:** Since the entries in the `/etc/map` 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.
+**NOTE:** Since the entries in the `/etc/map` are also used to reverse map any resource paths to URLs, using regular expressions with wildcards 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.
+
+#### Regular Expressions for Reverse Mappings
+
+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. 
+
+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 |
+| ------- | ----------- |
+| /content/([^/]+)/home/(.*) | http://example.com/$1/index/$2 |
+
 
 ### Redirection Values
 
@@ -168,7 +190,7 @@ The following pseudo code shows this alg
 
 ## Rebuild The Vanity Bloom Filter 
 
-<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.
+[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.
 
 In order to rebuild vanity bloom filter:
@@ -178,3 +200,8 @@ In order to rebuild vanity bloom filter:
 * locate the vanityBloomFilter.txt file in the file system (e.g. $SLING_HOME/felix/bundleXX/data/vanityBloomFilter.txt)
 * delete the vanityBloomFilter.txt file
 * start Apache Sling (this might take few minutes, depending on how many vanity path entries are present)
+
+## 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 that what either `ResourceResolver.map(...)` or `ResourceResolver.resolve(...)` would return for a given URL/path.
+