incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1483268 - /sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
Date Thu, 16 May 2013 09:16:08 GMT
Author: bdelacretaz
Date: Thu May 16 09:16:08 2013
New Revision: 1483268

fix lists formatting


Modified: sling/site/trunk/content/documentation/the-sling-engine/resources.mdtext
--- 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
@@ -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
@@ -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`

View raw message