Author: bdelacretaz
Date: Thu May 16 09:16:08 2013
New Revision: 1483268
URL: http://svn.apache.org/r1483268
Log:
fix lists formatting
Modified:
sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
Modified:
sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext?rev=1483268&r1=1483267&r2=1483268&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
(original)
+++ sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
Thu May 16 09:16:08 2013
@@ -9,6 +9,7 @@ The Resource is one of the central parts
## How to get a Resource
To get at Resources, you need a `ResourceResolver`. This interface defines
four kinds of methods to access resources:
+
* Absolute Path Mapping Resource Resolution: The `resolve(HttpServletRequest,
String)` and `resolve(String)` methods are called to apply some implementation
specific path matching algorithm to find a Resource. These methods are mainly
used to map external paths - such as path components of request URLs - to
Resources. To support creating external paths usable in an URL a third method
`map(String)` is defined, which allows for round-tripping.
* Absolute or Relative Path Resolution (including search path): The
`getResource(String path)` and `getResource(Resource base, String path)`
methods may be used to access a resource with an absolute path directly. If it
can't be found the path is assumed to be relative and the search path retrieved
from `getSearchPath()` is used to retrieve the resource. This mechanism is
similar to resolving a programm with the `PATH` environment variable in your
favourite operating system.
* Resource Enumeration: To enumerate resources and thus iterate the resource
tree, the `listChildren(Resource)` method may be used. This method returns an
`Iterator<Resource>` listing all resources whose path prefix is the path of the
given Resource. This method will of course also cross boundaries of registered
`ResourceProvider` instances to enable iterating the complete resource tree.
@@ -19,6 +20,7 @@ To get at Resources, you need a `Resourc
As has been said, the absolute path mapping methods
`resolve(HttpServletRequest, String)` and `resolve(String)` apply some
implementation specific path matching algorithm to find a Resource. The
difference between the two methods is that the former may take more properties
of the `HttpServletRequest` into account when resolving the Resoure, while the
latter just has an absolute path to work on.
The general algorithm of the two methods is as follows:
+
1. Call `HttpServletRequest.getScheme(), .getServerName(), getServerPort` to
get an absolute path out of the request URL: \[scheme\]({{ refs.scheme.path
}})/\[host\].\[port\]\[path\] (`resolve(HttpServletRequest, String)` method
only, which)
1. Check whether any virtual path matches the absolute path. If such a match
exists, the next step is entered with the match.
1. Apply a list of mappings in order to create a mapped path. The first mapped
path resolving to a Resource is assumed success and the Resource found is
returned.
@@ -46,6 +48,7 @@ Of course the search path is not used fo
For convenience the `ResourceResolver` provides two Resource querying methods
`findResources` and `queryResources` both methods take as arguments a JCR query
string and a query language name. These parameters match the parameter
definition of the `QueryManager.createQuery(String statement, String language)`
method of the JCR API.
The return value of these two methods differ in the use case:
+
* `findResources` returns an `Iteratory<Resource>` of all Resources matching
the query. This method is comparable to calling `getNodes()` on the
`QueryResult` returned from executing the JCR query.
* `queryResources` returns an `Iterator<Map<String, Object>>`. Each entry in
the iterator is a `Map<String, Object` representing a JCR result `Row` in the
`RowIterator` returned from executing the JCR query. The map is indexed by the
column name and the value of each entry is the value of the named column as a
Java Object.
@@ -60,6 +63,7 @@ The virtual Resource tree to which the t
Each Resource provider is registered as an OSGi service with a required
service registration property `provider.roots`. This is a multi-value String
property listing the absolute paths Resource tree entries serving as roots to
provided subtrees. For example, if a Resource provider is registered with the
service registration property `provider.roots` set to */some/root*, all paths
starting with `/some/root` are first looked up in the given Resource Provider.
When looking up a Resource in the registered Resource providers, the
`ResourceResolver` applies a longest prefix matching algorithm to find the best
match. For example consider three Resource provider registered as follows:
+
* JCR Resource provider as `/`
* Resource provider R1 as `/some`
* Resource provider R2 as `/some/path`
