incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r762291 - /incubator/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
Date Mon, 06 Apr 2009 11:43:36 GMT
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.



Mime
View raw message