...
Status: DRAFT
Created: 25. November 2008
Author: fmeschbe
JIRA: SLING-249
References: http://markmail.org/message/cibaddpdfk2jwm7p
Update: 28. November 2008, fmeschbe, Addition to node types and add section on backwards compatibility
Table of Contents | ||
---|---|---|
|
...
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 ofLocation
response header.sling:internalRedirectstatus
– 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 resoltion.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 thesling:alias
property set tobesucher
allowing the resource to be addressed in an URL as/content/besucher
.
Node Types
To ease with the definition of redirects and aliases, the following node types are defined:
- 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 resoltion.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 thesling:alias
property set tobesucher
allowing the resource to be addressed in an URL as/content/besucher
.
Node Types
To ease with the definition of redirects and aliases, the following node types are defined:
sling:ResourceAlias
– This mixin node type defines thesling:alias
property and may be attached to any node, which does not otherwise allow setting a property namedsling:alias
sling:MappingSpec
– This mixin node type defines thesling:match
,sling:redirect
,sling:status
, andsling: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 thesling:MappingSpec
mixin node type to allow setting the required matching and redirection. In addition thesling:Resource
mixin node type is extended to allow setting a resource type and thent:hierarchyNode
node type is extended to allow locating nodes of this node type belownt:
sling:ResourceAlias
– This mixin node type defines thesling:alias
property and may be attached to any node, which does not otherwise allow setting a property namedsling:alias
sling:MappingSpec
– This mixin node type defines thesling:match
,sling:redirect
andsling: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 thesling:MappingSpec
mixin node type to allow setting the required matching and redirection. In addition thesling:Resource
mixin node type is extended to allow setting a resource type and thent:hierarchyNode
node type is extended to allow locating nodes of this node type belownt: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.
...
At the end of the loop, result
contains the mapped path or null
if no entry matches the request path
.
Redirection Values
The result of matching the request path and getting the redirection is either a path into the resource tree or another URL. If the result is an URL, it is converted into a path again and matched against the mapping entries. This may be taking place repeatedly until an absolute or relative path into the resource tree results.
The following pseudo code summarizes this behaviour:
Code Block |
---|
String path = ....;
String result = path;
do {
result = applyMapEntries(result);
} while (isURL(result));
|
As soon as the result of applying the map entries is an absolute or relative path (or no more map entries match), Root Level Mapping terminates and the next step in resource resolution, resource tree access, takes place.
Resource Tree Access
The result of Root Level Mapping is an absolute or relative path to a resource. If the path is relative – e.g. myproject/docroot/sample.gif
– the resource resolver search path (ResourceResolver.getSearchPath()
is used to build absolute paths and resolve the resource. In this case the first resource found is used. If the result of Root Level Mapping is an absolute path, the path is used as is.
Accessing the resource tree after applying the Root Level Mappings has four options:
- Check whether the path addresses a so called Star Resource. A Star Resource is a resource whose path ends with or contains
/*
. Such resources are used by theSlingPostServlet
to create new content below an existing resource. If the path after Root Level Mapping is absolute, it is made absolute by prepending the first search path entry. - Check whether the path exists in the repository. if the path is absolute, it is tried directly. Otherwise the search path entries are prepended to the path until a resource is found or the search path is exhausted without finding a resource.
- Drill down the resource tree starting from the root, optionally using the search path until a resource is found.
- If no resource can be resolved, a Missing Resource is returned.
Drilling Down the Resource Tree
Drilling down the resource tree starts at the root and for each segement in the path checks whether a child resource of the given name exists or not. If not, a child resource is looked up, which has a sling:alias
property whose value matches the given name. If neither exists, the search is terminated and the resource cannot be resolved.
The following pseudo code shows this algorithm assuming the path is absolute:
...
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.
Redirection Values
The result of matching the request path and getting the redirection is either a path into the resource tree or another URL. If the result is an URL, it is converted into a path again and matched against the mapping entries. This may be taking place repeatedly until an absolute or relative path into the resource tree results.
...
As soon as the result of applying the map entries is an absolute or relative path (or no more map entries match), Root Level Mapping terminates and the next step in resource resolution, resource tree access, takes place.
Resource Tree Access
The result of Root Level Mapping is an absolute or relative path to a resource. If the path is relative – e.g. myproject/docroot/sample.gif
– the resource resolver search path (ResourceResolver.getSearchPath()
is used to build absolute paths and resolve the resource. In this case the first resource found is used. If the result of Root Level Mapping is an absolute path, the path is used as is.
...
- Check whether the path addresses a so called Star Resource. A Star Resource is a resource whose path ends with or contains
/*
. Such resources are used by theSlingPostServlet
to create new content below an existing resource. If the path after Root Level Mapping is absolute, it is made absolute by prepending the first search path entry. - Check whether the path exists in the repository. if the path is absolute, it is tried directly. Otherwise the search path entries are prepended to the path until a resource is found or the search path is exhausted without finding a resource.
- Drill down the resource tree starting from the root, optionally using the search path until a resource is found.
- If no resource can be resolved, a Missing Resource is returned.
Drilling Down the Resource Tree
Drilling down the resource tree starts at the root and for each segement in the path checks whether a child resource of the given name exists or not. If not, a child resource is looked up, which has a sling:alias
property whose value matches the given name. If neither exists, the search is terminated and the resource cannot be resolved.
...