This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-api.git
The following commit(s) were added to refs/heads/master by this push:
new 1206694 Clarify when to expect an absolute URI from map() calls
1206694 is described below
commit 12066940bbc97b0478b9faff9dc657811771b3fb
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
