This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch documentation/improve-rr-mapping-javadoc in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-api.git
commit 7e6e7e0b58456ad9f09adc24d984eaf70e5dc9a7 Author: Konrad Windszus <[email protected]> AuthorDate: Tue Dec 9 17:02:03 2025 +0100 Clarify when to expect an absolute URI from map() calls --- .../java/org/apache/sling/api/resource/ResourceResolver.java | 10 +++++++--- .../org/apache/sling/api/resource/mapping/ResourceMapper.java | 6 ++++-- 2 files changed, 11 insertions(+), 5 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 a3197cc..e5ae711 100644 --- a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java +++ b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java @@ -333,7 +333,9 @@ public interface ResourceResolver extends Adaptable, Closeable { * (with charset UTF-8). Due to this calling this method multiple times in a nested * fashion might lead to an invalid (request) path which can subsequently not * be resolved via {@link #resolve(String)}. - * + * <p> + * Whenever possible prefer using {@link #map(HttpServletRequest, String)} or {@link #map(javax.servlet.http.HttpServletRequest, String)} + * as that way you get a shorter URI (not necessarily containing schema, host and protocol). * @param resourcePath The path for which to return a mapped path. * @return The mapped path or {@code resourcePath} in case no mapping is found. * @throws IllegalStateException if this resource resolver has already been @@ -363,7 +365,8 @@ public interface ResourceResolver extends Adaptable, Closeable { * 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. + * servlet context path and the actual path used to resolve the resource except if the given request + * context is having the same server name, port and protocol as the one given in the mapping. * <p> * This method also does percent-encoding before returning the URL * (with charset UTF-8). Due to this calling this method multiple times in a nested @@ -402,7 +405,8 @@ public interface ResourceResolver extends Adaptable, Closeable { * 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. + * servlet context path and the actual path used to resolve the resource except if the given request + * context is having the same server name, port and protocol as the one given in the mapping. * <p> * This method also does percent-encoding before returning the URL * (with charset UTF-8). Due to this calling this method multiple times in a nested 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 2b3c2b1..2222086 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 @@ -83,7 +83,8 @@ public interface ResourceMapper { * 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. + * servlet context path and the actual path used to resolve the resource except if the given request + * context is having the same server name, port and protocol as the one given in the mapping. * * @param resourcePath The path for which to return a mapped path. * @param request The http servlet request object which may be used to apply @@ -113,7 +114,8 @@ public interface ResourceMapper { * 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. + * servlet context path and the actual path used to resolve the resource except if the given request + * context is having the same server name, port and protocol as the one given in the mapping. * * @param resourcePath The path for which to return a mapped path. * @param request The http servlet request object which may be used to apply
