incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r722892 - /incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
Date Wed, 03 Dec 2008 14:09:06 GMT
Author: fmeschbe
Date: Wed Dec  3 06:09:06 2008
New Revision: 722892

URL: http://svn.apache.org/viewvc?rev=722892&view=rev
Log:
SLING-752 Clarify API JavaDoc

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=722892&r1=722891&r2=722892&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
Wed Dec  3 06:09:06 2008
@@ -40,23 +40,34 @@
 
     /**
      * 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.
+     * 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.
+     * 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.
+     * <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 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.
+     * @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.
+     * @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.
      * @since 2.0.4
      */
     Resource resolve(HttpServletRequest request, String absPath);
@@ -64,13 +75,12 @@
     /**
      * Resolves the resource from the given <code>HttpServletRequest</code>.
      * <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.
+     * 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.
      * <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
@@ -79,11 +89,14 @@
      * <code>getPathInfo()</code> on the <code>request</code> object.
      * 
      * @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.
+     *            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 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)}
      *             instead.
      */
@@ -103,12 +116,15 @@
      * If the <code>absPath</code> is a relative path, this method returns
      * <code>null</code>.
      * 
-     * @param absPath The absolute path to be mapped to a resource.
-     * @return The {@link Resource} mapped from the path or <code>null</code>
-     *         if no resource can be found for the path.
-     * @throws org.apache.sling.api.SlingException A subclass of this exception
-     *             is thrown if the resource to which the request maps cannot be
-     *             retrieved.
+     * @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);
 



Mime
View raw message