svn commit: r720676 - /incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java

[fm...@apache.org]

Author: fmeschbe
Date: Tue Nov 25 16:05:18 2008
New Revision: 720676

URL: http://svn.apache.org/viewvc?rev=720676&view=rev
Log:
SLING-249 Extended API for the new Resource Resolver

Modified:
    incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java

Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java?rev=720676&r1=720675&r2=720676&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java Tue Nov 25 16:05:18 2008
@@ -39,6 +39,29 @@
 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 request cannot be resolved to an existing resource, a
+     * {@link Resource} object is returned whose
+     * {@link Resource#getResourceType() resource type} is set to
+     * {@link Resource#RESOURCE_TYPE_NON_EXISTING} and the
+     * {@link Resource#getPath() resource path} set to the request URI.
+     * {@link Resource#adaptTo(Class) object} returns <code>null</code> for
+     * all classes.
+     * 
+     * @param request The http servlet request object used to resolve the
+     *            resource for.
+     * @return The {@link Resource} for the request.
+     * @throws org.apache.sling.api.SlingException A subclass of this exception
+     *             is thrown if the resource to which the request maps cannot be
+     *             retrieved.
+     * @since 2.0.4
+     */
+    Resource resolve(HttpServletRequest request, String absPath);
+
+    /**
      * Resolves the resource from the given <code>HttpServletRequest</code>.
      * <p>
      * If the request cannot be resolved to an existing resource, a
@@ -48,6 +71,12 @@
      * {@link Resource#getPath() resource path} set to the request URI.
      * {@link Resource#adaptTo(Class) object} returns <code>null</code> for
      * all classes.
+     * <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.
@@ -55,6 +84,8 @@
      * @throws org.apache.sling.api.SlingException A subclass of this exception
      *             is thrown if the resource to which the request maps cannot be
      *             retrieved.
+     * @deprecated as of 2.0.4, use {@link #resolve(HttpServletRequest, String)}
+     *             instead.
      */
     Resource resolve(HttpServletRequest request);
 
@@ -83,9 +114,9 @@
 
     /**
      * Returns a path mapped from the (resource) path applying the reverse
-     * mapping used by the {@link #resolve(HttpServletRequest)} and
-     * {@link #resolve(String)} such that when the path is given to the
-     * {@link #resolve(String)} method the same resource is returned.
+     * 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
@@ -93,6 +124,9 @@
      * 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.
@@ -100,6 +134,33 @@
     String map(String resourcePath);
 
     /**
+     * Returns an URL mapped from the (resource) path applying the reverse
+     * mapping used by the {@link #resolve(HttpServletRequest, String)} such
+     * that when the path is given to the
+     * {@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
+     * {@link #resolve(HttpServletRequest, String)} with the path returned may
+     * return <code>null</code>.
+     * <p>
+     * This method is intended as the reverse operation of the
+     * {@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.
+     * @return The mapped URL.
+     * @since 2.0.4
+     */
+    String map(HttpServletRequest request, String resourcePath);
+
+    /**
      * Returns a {@link Resource} object for data located at the given path.
      * <p>
      * This specification does not define the location for resources or the