SLING-7792 - Resource Resolver should return more than one resolved path
if available
Restore ResourceResolver javadoc, it was lost during the squash / rebase
work.
diff --git a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
index 0cc9ba7..c3b476d 100644
--- a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
+++ b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
@@ -258,14 +258,56 @@
@NotNull Resource resolve(@NotNull HttpServletRequest request);
/**
- * Returns a path mapped from the (resource) path
+ * 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
+ * {@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.
+ * @throws IllegalStateException if this resource resolver has already been
+ * {@link #close() closed}.
*
* @see {@link ResourceMapper#getMapping(String, HttpServletRequest)}
*/
@NotNull String map(@NotNull String resourcePath);
/**
- * Returns an URL mapped from the (resource) path
+ * 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.
+ * @throws IllegalStateException if this resource resolver has already been
+ * {@link #close() closed}.
+ * @since 2.0.4 (Sling API Bundle 2.0.4)
*
* @see {@link ResourceMapper#getMapping(String, HttpServletRequest)}
*/
