This is an automated email from the ASF dual-hosted git repository.
rombert pushed a commit to branch feature/SLING-7792
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-api.git
The following commit(s) were added to refs/heads/feature/SLING-7792 by this
push:
new 8bcb3ec SLING-7792 - Resource Resolver should return more than one
resolved path if available
8bcb3ec is described below
commit 8bcb3eced71b2a9c7faf37c7f381a8780fa6570f
Author: Robert Munteanu <[email protected]>
AuthorDate: Thu Aug 9 15:24:59 2018 +0300
SLING-7792 - Resource Resolver should return more than one resolved path
if available
Updated API based on review comments (2)
---
.../sling/api/resource/ResourceResolver.java | 53 ++++++++++++++++++---
.../sling/api/resource/mapping/ResourceMapper.java | 55 +++++++++++-----------
2 files changed, 75 insertions(+), 33 deletions(-)
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 fb90dd3..16503d4 100644
--- a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
+++ b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
@@ -27,7 +27,6 @@ import javax.annotation.Nonnull;
import javax.servlet.http.HttpServletRequest;
import org.apache.sling.api.adapter.Adaptable;
-import org.apache.sling.api.resource.mapping.ResourceMapper;
import org.osgi.annotation.versioning.ProviderType;
/**
@@ -258,16 +257,58 @@ public interface ResourceResolver extends Adaptable,
Closeable {
@Nonnull Resource resolve(@Nonnull 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)}
+ * @see
org.apache.sling.api.resource.mapping.ResourceMapper#getMapping(String,
HttpServletRequest)
*/
@Nonnull String map(@Nonnull String resourcePath);
/**
- * Returns an URL mapped from the (resource) path
- *
- * @see {@link ResourceMapper#getMapping(String, HttpServletRequest)}
+ * 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
org.apache.sling.api.resource.mapping.ResourceMapper#getMapping(String,
HttpServletRequest)
*/
@CheckForNull String map(@Nonnull HttpServletRequest request, @Nonnull
String resourcePath);
diff --git
a/src/main/java/org/apache/sling/api/resource/mapping/ResourceMapper.java
b/src/main/java/org/apache/sling/api/resource/mapping/ResourceMapper.java
index b857054..6550d46 100644
--- a/src/main/java/org/apache/sling/api/resource/mapping/ResourceMapper.java
+++ b/src/main/java/org/apache/sling/api/resource/mapping/ResourceMapper.java
@@ -23,66 +23,67 @@ import java.util.Collection;
import javax.annotation.Nonnull;
import javax.servlet.http.HttpServletRequest;
-import org.apache.sling.api.resource.ResourceResolver;
import org.osgi.annotation.versioning.ProviderType;
/**
* Allows access to resource mappings
*
* <p>This interface superceeds the resource mapping functionality present
- * in the {@link ResourceResolver}. Although the methods present in that
- * interface will continue to work, the resource mapper will provide better
- * APIs to access the resource mappings.</p>
+ * in the {@link org.apache.sling.api.resource.ResourceResolver}.
+ * Although the methods present in that interface will continue to work,
+ * the resource mapper will provide better APIs to access the resource
mappings.</p>
*
- * <p>Implementations of this class are obtained by adapting a {@link
ResourceResolver}
- * instance. As such, the mappings returned by its methods reflect the
repository
- * permissions of the underyling resolver instance.</p>
+ * <p>Implementations of this class are obtained by adapting a
+ * {@link org.apache.sling.api.resource.ResourceResolver} instance. As such,
the
+ * mappings returned by its methods reflect the repository permissions of the
underyling
+ * resolver instance.</p>
*/
@ProviderType
public interface ResourceMapper {
/**
- * Returns a path mapped from the (resource) path applying the reverse
- * mapping used by the {@link ResourceResolver#resolve(String)} such that
when the path is
- * given to the {@link ResourceResolver#resolve(String)} method the same
resource is
- * returned.
+ * Returns a path mapped from the (resource) path applying the reverse
mapping
+ * used by the {@link
org.apache.sling.api.resource.ResourceResolver#resolve(String)}
+ * such that when the path is given to the
+ * {@link org.apache.sling.api.resource.ResourceResolver#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 ResourceResolver#resolve(String)} with the path returned may
return
- * <code>null</code>.
+ * {@link org.apache.sling.api.resource.ResourceResolver#resolve(String)}
+ * with the path returned may return <code>null</code>.
* <p>
* This method is intended as the reverse operation of the
- * {@link ResourceResolver#resolve(String)} method.
+ * {@link org.apache.sling.api.resource.ResourceResolver#resolve(String)}
method.
*
* @param resourcePath The path for which to return a mapped path.
* @return The mapped path.
* @throws IllegalStateException if the underlying resource resolver has
already been
- * {@link ResourceResolver#close() closed}.
+ * {@link
org.apache.sling.api.resource.ResourceResolver#close() closed}.
*
* @since 1.0.0 (Sling API Bundle 2.19.0)
*/
@Nonnull String getMapping(@Nonnull String resourcePath);
/**
- * Returns an URL mapped from the (resource) path applying the reverse
- * mapping used by the {@link ResourceResolver#resolve(HttpServletRequest,
String)} such
- * that when the path is given to the
- * {@link ResourceResolver#resolve(HttpServletRequest, String)} method the
same resource is
- * returned.
+ * Returns an URL mapped from the (resource) path applying the reverse
mapping
+ * used by the {@link
org.apache.sling.api.resource.ResourceResolver#resolve(HttpServletRequest,
String)}
+ * such that when the path is given to the
+ * {@link
org.apache.sling.api.resource.ResourceResolver#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 ResourceResolver#resolve(HttpServletRequest, String)} with the
path returned may
- * return <code>null</code>.
+ * {@link
org.apache.sling.api.resource.ResourceResolver#resolve(HttpServletRequest,
String)}
+ * with the path returned may return <code>null</code>.
* <p>
* This method is intended as the reverse operation of the
- * {@link ResourceResolver#resolve(HttpServletRequest, String)} method. As
such the URL
- * returned is expected to be an absolute URL including scheme, host, any
+ * {@link
org.apache.sling.api.resource.ResourceResolver#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 resourcePath The path for which to return a mapped path.
@@ -90,7 +91,7 @@ public interface ResourceMapper {
* more mapping functionality.
* @return The mapped URL.
* @throws IllegalStateException if the underlying resource resolver has
already been
- * {@link ResourceResolver#close() closed}.
+ * {@link
org.apache.sling.api.resource.ResourceResolver#close() closed}.
* @since 1.0.0 (Sling API Bundle 2.19.0)
*/
@Nonnull String getMapping(@Nonnull String resourcePath, @Nonnull
HttpServletRequest request);
@@ -108,7 +109,7 @@ public interface ResourceMapper {
* @param resourcePath The path for which to return a mapped path.
* @return a collection of mapped URLs, in no particular order. May not be
null or empty.
* @throws IllegalStateException if the underlying resource resolver has
already been
- * {@link ResourceResolver#close() closed}.
+ * {@link
org.apache.sling.api.resource.ResourceResolver#close() closed}.
* @since 1.0.0 (Sling API Bundle 2.19.0)
*/
Collection<String> getAllMappings(@Nonnull String resourcePath);
@@ -129,7 +130,7 @@ public interface ResourceMapper {
* @return a collection of mapped URLs, in no particular order. May not be
null or empty.
* @throws IllegalStateException if the underlying resource resolver has
already been
- * {@link ResourceResolver#close() closed}.
+ * {@link
org.apache.sling.api.resource.ResourceResolver#close() closed}.
* @since 1.0.0 (Sling API Bundle 2.19.0)
*/
Collection<String> getAllMappings(@Nonnull String resourcePath, @Nonnull
HttpServletRequest request);
