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 f5f4de2 SLING-7792 - Resource Resolver should return more than one
resolved path if available
f5f4de2 is described below
commit f5f4de2af0432816cbe3452df354ba7c03498c79
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
---
.../sling/api/resource/ResourceResolver.java | 10 ++--
.../sling/api/resource/mapping/ResourceMapper.java | 64 ++++++++++++++++++----
2 files changed, 60 insertions(+), 14 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 e4b8f75..fb90dd3 100644
--- a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
+++ b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
@@ -258,15 +258,17 @@ public interface ResourceResolver extends Adaptable,
Closeable {
@Nonnull Resource resolve(@Nonnull HttpServletRequest request);
/**
- * @deprecated Use {@link ResourceMapper#getMapping(String,
HttpServletRequest)} with a <tt>null</tt> request
+ * Returns a path mapped from the (resource) path
+ *
+ * @see {@link ResourceMapper#getMapping(String, HttpServletRequest)}
*/
- @Deprecated
@Nonnull String map(@Nonnull String resourcePath);
/**
- * @deprecated Use {@link ResourceMapper#getMapping(String,
HttpServletRequest)}
+ * Returns an URL mapped from the (resource) path
+ *
+ * @see {@link ResourceMapper#getMapping(String, HttpServletRequest)}
*/
- @Deprecated
@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 69149ed..b857054 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
@@ -21,7 +21,6 @@ package org.apache.sling.api.resource.mapping;
import java.util.Collection;
import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
import javax.servlet.http.HttpServletRequest;
import org.apache.sling.api.resource.ResourceResolver;
@@ -34,9 +33,38 @@ import org.osgi.annotation.versioning.ProviderType;
* 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>
+ *
+ * <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>
*/
@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.
+ * <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>.
+ * <p>
+ * This method is intended as the reverse operation of the
+ * {@link 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}.
+ *
+ * @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
@@ -52,14 +80,11 @@ public interface ResourceMapper {
* {@link ResourceResolver#resolve(HttpServletRequest, String)} with the
path returned may
* return <code>null</code>.
* <p>
- * Then passed a non-null <tt>request</tt>, this method acts as the
reverse operation of the
+ * 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
* servlet context path and the actual path used to resolve the resource.
- * <p>
- * In case that multiple possible exist, only one is returned, without any
- * guarantees as to which one is chosen.
- *
+
* @param resourcePath The path for which to return a mapped path.
* @param request The http servlet request object which may be used to
apply
* more mapping functionality.
@@ -68,10 +93,28 @@ public interface ResourceMapper {
* {@link ResourceResolver#close() closed}.
* @since 1.0.0 (Sling API Bundle 2.19.0)
*/
- @Nonnull String getMapping(@Nonnull String resourcePath, @Nullable
HttpServletRequest request);
+ @Nonnull String getMapping(@Nonnull String resourcePath, @Nonnull
HttpServletRequest request);
/**
- * Retuns all possible URL mappings for a given <tt>resourcePath</tt>.
+ * Retuns all possible mappings for a given <tt>resourcePath</tt> as paths.
+ *
+ * <p>
+ * This method differs from the {@link #getMapping(String)} variant
+ * by guaranteeing that all possible mappings are returned for a specified
path.
+ *
+ * <p>
+ * The mappings are not returned in any particular order.
+ *
+ * @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}.
+ * @since 1.0.0 (Sling API Bundle 2.19.0)
+ */
+ Collection<String> getAllMappings(@Nonnull String resourcePath);
+
+ /**
+ * Retuns all possible mappings for a given <tt>resourcePath</tt> as URLs.
*
* <p>
* This method differs from the {@link #getMapping(String,
HttpServletRequest)} variant
@@ -80,13 +123,14 @@ public interface ResourceMapper {
* <p>
* The mappings are not returned in any particular order.
*
+ * @param resourcePath The path for which to return a mapped path.
* @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 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}.
* @since 1.0.0 (Sling API Bundle 2.19.0)
*/
- Collection<String> getAllMappings(@Nonnull String resourcePath, @Nullable
HttpServletRequest request);
+ Collection<String> getAllMappings(@Nonnull String resourcePath, @Nonnull
HttpServletRequest request);
}
