Author: kwin
Date: Thu Sep 22 11:59:23 2016
New Revision: 1761914

URL: http://svn.apache.org/viewvc?rev=1761914&view=rev
Log:
clarify URL decomposition 

explicitly mention that decomposition can only be done correctly when knowing 
the underlying resource structure.

Modified:
    
sling/site/trunk/content/documentation/the-sling-engine/url-decomposition.mdtext
    
sling/site/trunk/content/documentation/the-sling-engine/url-to-script-resolution.mdtext

Modified: 
sling/site/trunk/content/documentation/the-sling-engine/url-decomposition.mdtext
URL: 
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/url-decomposition.mdtext?rev=1761914&r1=1761913&r2=1761914&view=diff
==============================================================================
--- 
sling/site/trunk/content/documentation/the-sling-engine/url-decomposition.mdtext
 (original)
+++ 
sling/site/trunk/content/documentation/the-sling-engine/url-decomposition.mdtext
 Thu Sep 22 11:59:23 2016
@@ -1,15 +1,21 @@
 Title: URL decomposition
 
-During the *Resource Resolution* step, the client request URL is decomposed 
into the following parts:
+[TOC]
 
-1. **Resource Path** -  The longest substring of the request URL such that the 
resource path is either the complete request URL or the next character in the 
request URL after the resource path is a dot (`.`).
+During the *Resource Resolution* step, the client request URI (as being 
returned by 
[HttpServletRequest.getRequestURI()](http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRequestURI())`
 is decomposed into the following parts (in exactly this order):
+
+1. **Resource Path** - For existing resources the resource path is the longest 
match (also considering its [mappings]({{ 
refs.mappings-for-resource-resolution.path }})) pointing to a resource where 
the next character is either a dot (`.`) or it is the full request URI.
+Otherwise (for a path not matching any existing resource) the resource path 
ends at the *first dot (`.`)* in the request url. The exact logic for 
retrieving the resource path is implemented at 
[ResourceResolver.resolve(HttpServletRequest,String](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#resolve-javax.servlet.http.HttpServletRequest-java.lang.String-).
 *It is impossible to tell from just looking at the request URI where the 
resource path part ends. You have to know the underlying resource structure to 
know how a URL is decomposed*.
 1. **Selectors** -  If the first character in the request URL after the 
resource path is a dot, the string after the dot up to but not including the 
last dot before the next slash character or the end of the request URL. If the 
resource path spans the complete request URL no seletors exist. If only one dot 
follows the resource path before the end of the request URL or the next slash, 
also no selectors exist.
 1. **Extension** -  The string after the last dot after the resource path in 
the request URL but before the end of the request URL or the next slash after 
the resource path in the request URL. 
-1. **Suffix Path** -  If the request URL contains a slash character after the 
resource path and optional selectors and extension, the path starting with the 
slash up to the end of the request URL is the suffix path. Otherwise, the 
suffix path is empty. Note, that after the resource path at least a dot must be 
in the URL to let Sling detect the resource path.
+1. **Suffix** -  If the request URL contains a slash character after the 
resource path and optional selectors and extension, the path starting with the 
slash up to the end of the request URL is the suffix path. Otherwise, the 
suffix path is empty. Note, that after the resource path at least a dot must be 
in the URL to let Sling detect the suffix.
+
+Those decomposed parts can be accessed through the `RequestPathInfo` object, 
which is retrieved via 
[SlingHttpServletRequest.getPathInfo()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/SlingHttpServletRequest.html#getRequestPathInfo--)
 
-There's a cheat sheet on Day's dev page under 
[http://dev.day.com/content/docs/en/cq/current/developing/sling_cheatsheet.html](http://dev.day.com/content/docs/en/cq/current/developing/sling_cheatsheet.html)
 available to get you familiar with the URL decomposition of Sling.
+There's a cheat sheet in Adobe's AEM documentation at 
[https://docs.adobe.com/docs/en/aem/6-2/develop/platform/sling-cheatsheet.html](https://docs.adobe.com/docs/en/aem/6-2/develop/platform/sling-cheatsheet.html)
 available to get you familiar with the URL decomposition of Sling.
 
-*Examples*: Assume there is a Resource at `/a/b`, which has no children.
+# Examples #
+Assume there is a Resource at `/a/b`, which has no children.
 
 | URI | Resource Path | Selectors | Extension | Suffix | Resource Found |
 |--|--|--|--|--|--|
@@ -18,6 +24,7 @@ There's a cheat sheet on Day's dev page
 | /a/b.s1.html              | /a/b | s1    | html | null       | yes |
 | /a/b.s1.s2.html           | /a/b | s1.s2 | html | null       | yes |
 | /a/b/c/d                  | /a/b/c/d | null  | null | null       | no! |
+| /a/c.html/s.txt           | /a/c | null  | html | /s.txt     | no! |
 | /a/b./c/d                  | /a/b | null  | null | /c/d       | yes |
 | /a/b.html/c/d             | /a/b | null  | html | /c/d       | yes |
 | /a/b.s1.html/c/d          | /a/b | s1    | html | /c/d       | yes |
@@ -27,7 +34,11 @@ There's a cheat sheet on Day's dev page
 | /a/b.s1.html/c/d.s.txt    | /a/b | s1    | html | /c/d.s.txt | yes |
 | /a/b.s1.s2.html/c/d.s.txt | /a/b | s1.s2 | html | /c/d.s.txt | yes |
 
-<div class="info">
-<b>Automated tests and examples</b><br/>
-The <a 
href="http://svn.apache.org/repos/asf/sling/trunk/bundles/engine/src/test/java/org/apache/sling/engine/impl/request/SlingRequestPathInfoTest.java";>SlingRequestPathInfoTest</a>
 demonstrates and tests this decomposition. Feel free to suggest additional 
tests that help clarify how this works!
-</div>
+
+# Automated Tests #
+
+The tests at
+* 
[ResourceResolverImplTest](http://svn.apache.org/repos/asf/sling/trunk/bundles/resourceresolver/src/test/java/org/apache/sling/resourceresolver/impl/ResourceResolverImplTest.java)
 for the split between resource path and the rest. Mostly in the method 
`testbasicAPIAssumptions`.
+* 
[SlingRequestPathInfoTest](http://svn.apache.org/repos/asf/sling/trunk/bundles/engine/src/test/java/org/apache/sling/engine/impl/request/SlingRequestPathInfoTest.java)
 demonstrates the decomposition after the resource path part.
+
+Feel free to suggest additional tests that help clarify how this works!

Modified: 
sling/site/trunk/content/documentation/the-sling-engine/url-to-script-resolution.mdtext
URL: 
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/url-to-script-resolution.mdtext?rev=1761914&r1=1761913&r2=1761914&view=diff
==============================================================================
--- 
sling/site/trunk/content/documentation/the-sling-engine/url-to-script-resolution.mdtext
 (original)
+++ 
sling/site/trunk/content/documentation/the-sling-engine/url-to-script-resolution.mdtext
 Thu Sep 22 11:59:23 2016
@@ -6,16 +6,15 @@ This page explains how Sling maps URLs t
 
 See also [Servlets and Scripts]({{ refs.servlets.path }}) which provides 
detailed info about how to register servlets.
 
-First of all Sling looks up the resource identified 
-by the URL - typically a path inside the JCR repository, which is annotated by 
the `sling:resourceType` property 
+First of all Sling looks up the resource identified by the URL - typically a 
path inside the JCR repository, which is annotated by the `sling:resourceType` 
property 
 which defines the resource type of that resource. Using this resource type 
(which is kind of a relative path, 
-eg. "myblog/comment"), scripts or servlets are looked up. 
+eg. "myblog/comment"), scripts or servlets are looked up. For more details 
about how the initial resource is identified for a specific request URL look at 
[URL decomposition] ({{refs.url-decomposition.path}}).
 
-Scripts and servlets are itself resource in Sling and thus have a resource 
path: this is either the location in the 
+Scripts and servlets are itself resources in Sling and thus have a resource 
path: this is either the location in the 
 JCR repository, the resource type in a servlet component configuration or the 
"virtual" bundle resource path 
 (if a script is provided inside a bundle without being installed into the JCR 
repository). 
 
-For the Whole Truth about script resolution, see the 
[ScriptSelectionTest](http://svn.apache.org/repos/asf/sling/trunk/bundles/servlets/resolver/src/test/java/org/apache/sling/servlets/resolver/internal/helper/ScriptSelectionTest.java)
 class. If you see interesting cases that are not
+For the whole Truth about script resolution, see the 
[ScriptSelectionTest](http://svn.apache.org/repos/asf/sling/trunk/bundles/servlets/resolver/src/test/java/org/apache/sling/servlets/resolver/internal/helper/ScriptSelectionTest.java)
 class. If you see interesting cases that are not
 covered there, please let us know via the Sling users mailing list.
 
 TODO: explain super types, servlet path mappings, node type resource types 
(`my:type -> my/type`) 


Reply via email to