Author: fmeschbe
Date: Mon Apr 6 11:43:36 2009
New Revision: 762291
URL: http://svn.apache.org/viewvc?rev=762291&view=rev
Log:
SLING-909 define the ResourceResolver API consistently:
resolve: always return Resource or NonExistingResource
getResource: return null if no resource at path
Modified:
incubator/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
Modified:
incubator/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
URL:
http://svn.apache.org/viewvc/incubator/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java?rev=762291&r1=762290&r2=762291&view=diff
==============================================================================
---
incubator/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
(original)
+++
incubator/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
Mon Apr 6 11:43:36 2009
@@ -35,33 +35,55 @@
* The <code>ResourceResolver</code> is also an {...@link Adaptable} to get
* adapters to other types. A JCR based resource resolver might support
adapting
* to the JCR Session used by the resolver to access the JCR Repository.
+ * <p>
+ * This interface defines two kinds of methods to access resources: The
+ * <code>resolve</code> methods and the <code>getResource</code> methods. The
+ * difference lies in the algorithm applied to find the requested resource and
+ * in the behaviour in case a resource cannot be found:
+ * <table>
+ * <tr>
+ * <th>Method Kind</th>
+ * <th>Access Algorithm</th>
+ * <th>Missing Resource</th>
+ * </tr>
+ * <tr>
+ * <td>resolve</td>
+ * <td>Path is always assumed to be absolute. Uses elaborate resource
resolution
+ * algorithm. This kind of method is intended to resolve request URLs to
+ * resources.</td>
+ * <td>Returns {...@link NonExistingResource}</td>
+ * </tr>
+ * <tr>
+ * <td>getResource</td>
+ * <td>Directly access resources with absolute path. For relative paths, the
+ * {...@link #getSearchPath() search path} is applied. This method is intended
to
+ * be used by request processing scripts to access further resources as
+ * required.</td>
+ * <td>Returns <code>null</code></td>
+ * </tr>
+ * </table>
*/
public interface ResourceResolver extends Adaptable {
/**
* Resolves the resource from the given <code>absPath</code> optionally
- * taking <code>HttpServletRequest</code> into account, such as the value
- * of the <code>Host</code> request header.
- * <p>
- * If the <code>absPath</code> cannot be resolved to an existing resource
- * this method returns a {...@link NonExistingResource}. This method is
- * intended to apply the same algorithm to the absolute path as is used by
- * the {...@link #resolve(HttpServletRequest, String)} method except for
cases
- * where the latter uses request property such as request headers or
request
- * parameters to resolve a resource.
+ * taking <code>HttpServletRequest</code> into account, such as the value
of
+ * the <code>Host</code> request header. Returns a
+ * {...@link NonExistingResource} if the path cannot be resolved to an
existing
+ * and accessible resource.
* <p>
* The difference between this method and the {...@link #resolve(String)}
* method is, that this method may take request properties like the scheme,
* the host header or request parameters into account to resolve the
* resource.
- *
+ *
* @param request The http servlet request object providing more hints at
- * how to resolve the <code>absPath</code>. This parameter may
- * be <code>null</code> in which case the implementation should
- * use reasonable defaults.
+ * how to resolve the <code>absPath</code>. This parameter may
be
+ * <code>null</code> in which case the implementation should use
+ * reasonable defaults.
* @param absPath The absolute path to be resolved to a resource. If this
- * parameter is <code>null</code>, it is assumed to address
- * the root of the resource tree. If the path is relative it is
+ * parameter is <code>null</code>, it is assumed to address the
+ * root of the resource tree. If the path is relative it is
* assumed relative to the root, that is a slash is prepended to
* the path before resolving it.
* @return The {...@link Resource} addressed by the <code>absPath</code>
or a
@@ -73,28 +95,49 @@
Resource resolve(HttpServletRequest request, String absPath);
/**
+ * Resolves the resource from the given absolute path. Returns a
+ * {...@link NonExistingResource} if the path cannot be resolved to an
existing
+ * and accessible resource.
+ * <p>
+ * This method is intended to apply the same algorithm to the absolute path
+ * as is used by the {...@link #resolve(HttpServletRequest)} method except
for
+ * cases where the latter uses request property such as request headers or
+ * request parameters to resolve a resource.
+ * <p>
+ * It is ok for the implementation of this method to just call the
+ * {...@link #resolve(HttpServletRequest, String)} method with
+ * <code>null</code> as the request argument.
+ *
+ * @param absPath The absolute path to be resolved to a resource. If this
+ * parameter is <code>null</code>, it is assumed to address the
+ * root of the resource tree. If the path is relative it is
+ * assumed relative to the root, that is a slash is prepended to
+ * the path before resolving it.
+ * @return The {...@link Resource} addressed by the <code>absPath</code>
or a
+ * {...@link NonExistingResource} if no such resource can be
resolved.
+ * @throws org.apache.sling.api.SlingException Or a subclass thereof may be
+ * thrown if an error occurrs trying to resolve the resource.
+ */
+ Resource resolve(String absPath);
+
+ /**
* Resolves the resource from the given <code>HttpServletRequest</code>.
- * <p>
- * If the request cannot be resolved to an existing resource this method
- * returns a {...@link NonExistingResource}. This method is intended to
apply
- * the same algorithm to the absolute path as is used by the
- * {...@link #resolve(HttpServletRequest, String)} method except for cases
- * where the latter uses request property such as request headers or
request
- * parameters to resolve a resource.
+ * Returns a {...@link NonExistingResource} if the path cannot be resolved
to
+ * an existing and accessible resource.
* <p>
* This method is deprecated as of API version 2.0.4 and should not be used
* anymore. Implementations are expected to implement this method calling
* the {...@link #resolve(HttpServletRequest, String)} where the
* <code>absPath</code> argument is the result of calling the
* <code>getPathInfo()</code> on the <code>request</code> object.
- *
+ *
* @param request The http servlet request object used to resolve the
* resource for. This must not be <code>null</code>.
* @return The {...@link Resource} addressed by
* <code>HttpServletRequest.getPathInfo()</code> or a
* {...@link NonExistingResource} if no such resource can be
resolved.
- * @throws NullPointerException If <code>request</code> is
- * <code>null</code>.
+ * @throws NullPointerException If <code>request</code> is
<code>null</code>
+ * .
* @throws org.apache.sling.api.SlingException Or a subclass thereof may be
* thrown if an error occurrs trying to resolve the resource.
* @deprecated as of 2.0.4, use {...@link #resolve(HttpServletRequest,
String)}
@@ -104,47 +147,21 @@
Resource resolve(HttpServletRequest request);
/**
- * Resolves the resource from the given absolute path.
- * <p>
- * If the request cannot be resolved to an existing resource this method
- * returns <code>null</code>. This method is intended to apply the same
- * algorithm to the absolute path as is used by the
- * {...@link #resolve(HttpServletRequest)} method except for cases where
the
- * latter uses request property such as request headers or request
- * parameters to resolve a resource. In this case this method may return
- * <code>null</code>.
- * <p>
- * If the <code>absPath</code> is a relative path, this method returns
- * <code>null</code>.
- *
- * @param absPath The absolute path to be resolved to a resource. If the
- * path is relative <code>null</code> is returned. This
- * parameter must not be <code>null</code>.
- * @return The {...@link Resource} addressed by the <code>absPath</code>
or a
- * {...@link NonExistingResource} if no such resource can be
resolved.
- * @throws NullPointerException if <code>absPath</code> is
- * <code>null</code>.
- * @throws org.apache.sling.api.SlingException Or a subclass thereof may be
- * thrown if an error occurrs trying to resolve the resource.
- */
- Resource resolve(String absPath);
-
- /**
* Returns a path mapped from the (resource) path applying the reverse
* mapping used by the {...@link #resolve(String)} such that when the path
is
* given to the {...@link #resolve(String)} method the same resource is
* returned.
* <p>
- * Note, that technically the <code>resourcePath</code> need not refer to
- * an existing resource. This method just applies the mappings and returns
- * the resulting string. If the <code>resourcePath</code> does not address
- * an existing resource roundtripping may of course not work and calling
+ * Note, that technically the <code>resourcePath</code> need not refer to
an
+ * existing resource. This method just applies the mappings and returns the
+ * resulting string. If the <code>resourcePath</code> does not address an
+ * existing resource roundtripping may of course not work and calling
* {...@link #resolve(String)} with the path returned may return
* <code>null</code>.
* <p>
* This method is intended as the reverse operation of the
* {...@link #resolve(String)} method.
- *
+ *
* @param resourcePath The path for which to return a mapped path.
* @return The mapped path.
*/
@@ -157,10 +174,10 @@
* {...@link #resolve(HttpServletRequest, String)} method the same
resource is
* returned.
* <p>
- * Note, that technically the <code>resourcePath</code> need not refer to
- * an existing resource. This method just applies the mappings and returns
- * the resulting string. If the <code>resourcePath</code> does not address
- * an existing resource roundtripping may of course not work and calling
+ * Note, that technically the <code>resourcePath</code> need not refer to
an
+ * existing resource. This method just applies the mappings and returns the
+ * resulting string. If the <code>resourcePath</code> does not address an
+ * existing resource roundtripping may of course not work and calling
* {...@link #resolve(HttpServletRequest, String)} with the path returned
may
* return <code>null</code>.
* <p>
@@ -168,7 +185,7 @@
* {...@link #resolve(HttpServletRequest, String)} method. As such the URL
* returned is expected to be an absolute URL including scheme, host, any
* servlet context path and the actual path used to resolve the resource.
- *
+ *
* @param request The http servlet request object which may be used to
apply
* more mapping functionality.
* @param resourcePath The path for which to return a mapped path.
@@ -184,11 +201,10 @@
* semantics for resource paths. For an implementation reading content from
* a Java Content Repository, the path could be a
* <code>javax.jcr.Item</code> path from which the resource object is
- * loaded.
- * In contrast to the {...@link #resolve(String)} method, this method
- * does not apply any logic to the path, so the path is used as-is to
- * fetch the content.
- *
+ * loaded. In contrast to the {...@link #resolve(String)} method, this
method
+ * does not apply any logic to the path, so the path is used as-is to fetch
+ * the content.
+ *
* @param path The absolute path to the resource object to be loaded. The
* path may contain relative path specifiers like <code>.</code>
* (current location) and <code>..</code> (parent location),
@@ -211,24 +227,23 @@
* a Java Content Repository, the path could be a
* <code>javax.jcr.Item</code> path from which the resource object is
* loaded.
- *
+ *
* @param base The base {...@link Resource} against which a relative path
* argument given by <code>path</code> is resolved. This
- * parameter may be <code>null</code> if the <code>path</code>
- * is known to be absolute.
+ * parameter may be <code>null</code> if the <code>path</code>
is
+ * known to be absolute.
* @param path The path to the resource object to be loaded. If the path is
* relative, i.e. does not start with a slash (<code>/</code>),
- * the resource relative to the given <code>base</code>
- * resource is returned. The path may contain relative path
- * specifiers like <code>.</code> (current location) and
- * <code>..</code> (parent location), which are resolved by
- * this method.
+ * the resource relative to the given <code>base</code> resource
+ * is returned. The path may contain relative path specifiers
+ * like <code>.</code> (current location) and <code>..</code>
+ * (parent location), which are resolved by this method.
* @return The <code>Resource</code> object loaded from the path or
* <code>null</code> if the path does not resolve to a resource.
* @throws org.apache.sling.api.SlingException If an error occurrs trying
to
* load the resource object from the path or if
- * <code>base</code> is <code>null</code> and
- * <code>path</code> is relative.
+ * <code>base</code> is <code>null</code> and <code>path</code>
+ * is relative.
*/
Resource getResource(Resource base, String path);
@@ -249,19 +264,18 @@
String[] getSearchPath();
/**
- * Returns an <code>Iterator</code> of {...@link Resource} objects loaded
- * from the children of the given <code>Resource</code>.
+ * Returns an <code>Iterator</code> of {...@link Resource} objects loaded
from
+ * the children of the given <code>Resource</code>.
* <p>
* This specification does not define what the term "child" means. This is
* left to the implementation to define. For example an implementation
* reading content from a Java Content Repository, the children could be
the
* {...@link Resource} objects loaded from child items of the
<code>Item</code>
* of the given <code>Resource</code>.
- *
+ *
* @param parent The {...@link Resource Resource} whose children are
requested.
* @return An <code>Iterator</code> of {...@link Resource} objects.
- * @throws NullPointerException If <code>parent</code> is
- * <code>null</code>.
+ * @throws NullPointerException If <code>parent</code> is
<code>null</code>.
* @throws org.apache.sling.api.SlingException If any error occurs
acquiring
* the child resource iterator.
*/
@@ -277,11 +291,11 @@
* create a JCR <code>Query</code> through the <code>QueryManager</code>.
* The result returned is then based on the <code>NodeIterator</code>
* provided by the query result.
- *
+ *
* @param query The query string to use to find the resources.
* @param language The language in which the query is formulated.
- * @return An <code>Iterator</code> of {...@link Resource} objects matching
- * the query.
+ * @return An <code>Iterator</code> of {...@link Resource} objects
matching the
+ * query.
* @throws QuerySyntaxException If the query is not syntactically correct
* according to the query language indicator of if the query
* language is not supported.
@@ -300,14 +314,14 @@
* create a JCR <code>Query</code> through the <code>QueryManager</code>.
* The result returned is then based on the <code>RowIterator</code>
* provided by the query result. The map returned for each row is indexed
by
- * the column name and the column value is the JCR <code>Value</code>
- * object converted into the respective Java object, such as
- * <code>Boolean</code> for a value of property type <em>Boolean</em>.
- *
+ * the column name and the column value is the JCR <code>Value</code>
object
+ * converted into the respective Java object, such as <code>Boolean</code>
+ * for a value of property type <em>Boolean</em>.
+ *
* @param query The query string to use to find the resources.
* @param language The language in which the query is formulated.
- * @return An <code>Iterator</code> of <code>Map</code> instances
- * providing access to the query result.
+ * @return An <code>Iterator</code> of <code>Map</code> instances providing
+ * access to the query result.
* @throws QuerySyntaxException If the query is not syntactically correct
* according to the query language indicator of if the query
* language is not supported.
