This is an automated email from the ASF dual-hosted git repository. cziegeler pushed a commit to branch feature/pathmappingproposal in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-api.git
commit 54ff78a519f17454da62ea239e580dad188d6e18 Author: Carsten Ziegeler <[email protected]> AuthorDate: Wed Sep 2 13:56:09 2020 +0200 Prototype api --- .../sling/api/resource/ResourceResolver.java | 110 +++++++++------------ .../api/resource/ResourceResolverFactory.java | 10 +- .../{package-info.java => PathRewriter.java} | 25 ++++- ...{package-info.java => PathRewriterFactory.java} | 17 +++- .../sling/api/resource/mapping/ResourceMapper.java | 51 +++++----- .../sling/api/resource/mapping/package-info.java | 2 +- .../apache/sling/api/resource/package-info.java | 2 +- .../api/wrappers/ResourceResolverWrapper.java | 14 ++- 8 files changed, 130 insertions(+), 101 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 8a2b27d..73be59e 100644 --- a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java +++ b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java @@ -22,12 +22,13 @@ import java.io.Closeable; import java.util.Iterator; import java.util.Map; -import org.jetbrains.annotations.Nullable; -import org.jetbrains.annotations.NotNull; import javax.servlet.http.HttpServletRequest; import org.apache.sling.api.adapter.Adaptable; +import org.apache.sling.api.resource.mapping.PathRewriter; import org.apache.sling.api.resource.mapping.ResourceMapper; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; import org.osgi.annotation.versioning.ProviderType; /** @@ -172,16 +173,39 @@ public interface ResourceResolver extends Adaptable, Closeable { String PROPERTY_RESOURCE_TYPE = "sling:resourceType"; /** - * Resolves the resource from the given <code>absPath</code> optionally - * taking <code>HttpServletRequest</code> into account, such as the value of - * the <code>Host</code> request header. Returns a + * Resolves the resource from the given absolute path. Returns a * {@link NonExistingResource} if the path cannot be resolved to an existing * and accessible resource. * <p> - * The difference between this method and the {@link #resolve(String)} - * method is, that this method may take request properties like the scheme, - * the host header or request parameters into account to resolve the - * resource. + * + * @param absPath The absolute path to be resolved to a resource. If this + * parameter is <code>null</code>, it is assumed to address the + * root of the resource tree. If the path is relative it is + * assumed relative to the root, that is a slash is prepended to + * the path before resolving it. + * @return The {@link Resource} addressed by the <code>absPath</code> or a + * {@link NonExistingResource} if no such resource can be resolved. + * @throws org.apache.sling.api.SlingException Or a subclass thereof may be + * thrown if an error occurs trying to resolve the resource. + * @throws IllegalStateException if this resource resolver has already been + * {@link #close() closed}. + * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html";>Mappings for Resource Resolution</a> + * Resolve a resource based on the path. + * @param path The full path + * @return The resolved resource + * @since 2.13.0 + */ + @NotNull Resource resolveResource(@NotNull String path); + + /** + * Return the path rewriter associated with this resolver + * @return The path rewriter. + * @since 2.13.0 + */ + @NotNull PathRewriter getPathRewriter(); + + /** + * Same as calling rewrite on the path rewriter and resolveResource with the result. * * @param request The http servlet request object providing more hints at * how to resolve the <code>absPath</code>. This parameter may be @@ -200,22 +224,13 @@ public interface ResourceResolver extends Adaptable, Closeable { * {@link #close() closed}. * @since 2.0.4 (Sling API Bundle 2.0.4) * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html";>Mappings for Resource Resolution</a> + * @deprecated */ + @Deprecated @NotNull Resource resolve(@NotNull HttpServletRequest request, @NotNull String absPath); /** - * Resolves the resource from the given absolute path. Returns a - * {@link NonExistingResource} if the path cannot be resolved to an existing - * and accessible resource. - * <p> - * This method is intended to apply the same algorithm to the absolute path - * as is used by the {@link #resolve(HttpServletRequest)} method except for - * cases where the latter uses request property such as request headers or - * request parameters to resolve a resource. - * <p> - * It is ok for the implementation of this method to just call the - * {@link #resolve(HttpServletRequest, String)} method with - * <code>null</code> as the request argument. + * Same as calling rewrite on the path rewriter and resolveResource with the result. * * @param absPath The absolute path to be resolved to a resource. If this * parameter is <code>null</code>, it is assumed to address the @@ -229,7 +244,9 @@ public interface ResourceResolver extends Adaptable, Closeable { * @throws IllegalStateException if this resource resolver has already been * {@link #close() closed}. * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html";>Mappings for Resource Resolution</a> + * @deprecated */ + @Deprecated @NotNull Resource resolve(@NotNull String absPath); /** @@ -262,60 +279,23 @@ public interface ResourceResolver extends Adaptable, Closeable { @NotNull Resource resolve(@NotNull HttpServletRequest request); /** - * Returns a (request) 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. - * <p> - * This method also does percent-encoding before returning the (request) path - * (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)}. + * Same as calling reverseRewrite on the path rewriter * * @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 ResourceMapper#getMapping(String, HttpServletRequest) * @see <a href="https://tools.ietf.org/html/rfc3986#section-2.1";>Percent-Encoding</a> * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html";>Mappings for Resource Resolution</a> + * @deprecated */ + @Deprecated @NotNull String map(@NotNull String resourcePath); /** - * 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. - * <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 - * fashion might lead to an invalid URL which can subsequently not - * be resolved via {@link #resolve(String)}. + * Same as calling reverseRewrite on the path rewriter * * @param request The http servlet request object which may be used to apply * more mapping functionality. @@ -324,11 +304,13 @@ public interface ResourceResolver extends Adaptable, Closeable { * @throws IllegalStateException if this resource resolver has already been * {@link #close() closed}. * @since 2.0.4 (Sling API Bundle 2.0.4) - * + * * @see ResourceMapper#getMapping(String, HttpServletRequest) * @see <a href="https://tools.ietf.org/html/rfc3986#section-2.1";>Percent-Encoding</a> * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html";>Mappings for Resource Resolution</a> + * @deprecated */ + @Deprecated @Nullable String map(@NotNull HttpServletRequest request, @NotNull String resourcePath); /** diff --git a/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java b/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java index 111c34c..8ce3967 100644 --- a/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java +++ b/src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java @@ -21,9 +21,8 @@ package org.apache.sling.api.resource; import java.util.List; import java.util.Map; -import org.jetbrains.annotations.Nullable; import org.jetbrains.annotations.NotNull; - +import org.jetbrains.annotations.Nullable; import org.osgi.annotation.versioning.ProviderType; /** @@ -100,6 +99,13 @@ public interface ResourceResolverFactory { String SUBSERVICE = "sling.service.subservice"; /** + * Name of the authentication information property to pass in a + * dedicated PathRewriter object + * @since 2.13.0 + */ + String PATH_REWRITER = "service.path.rewriter"; + + /** * Returns a new {@link ResourceResolver} instance with further * configuration taken from the given <code>authenticationInfo</code> map. * Generally this map will contain a user name and password to authenticate. diff --git a/src/main/java/org/apache/sling/api/resource/mapping/package-info.java b/src/main/java/org/apache/sling/api/resource/mapping/PathRewriter.java similarity index 58% copy from src/main/java/org/apache/sling/api/resource/mapping/package-info.java copy to src/main/java/org/apache/sling/api/resource/mapping/PathRewriter.java index e871225..47d9124 100644 --- a/src/main/java/org/apache/sling/api/resource/mapping/package-info.java +++ b/src/main/java/org/apache/sling/api/resource/mapping/PathRewriter.java @@ -16,9 +16,28 @@ * specific language governing permissions and limitations * under the License. */ - -@Version("1.0.1") package org.apache.sling.api.resource.mapping; -import org.osgi.annotation.versioning.Version; +import javax.servlet.http.HttpServletRequest; + +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; +import org.osgi.annotation.versioning.ProviderType; + +/** + * @since 1.1.0 + */ +@ProviderType +public interface PathRewriter { + + @NotNull String rewrite(@NotNull String path); + + @NotNull String rewrite(@NotNull HttpServletRequest request, @NotNull String path); + + @NotNull String reverseRewrite(@NotNull String path); + + @NotNull String reverseRewrite(@NotNull HttpServletRequest request, @NotNull String path); + + @Nullable HttpServletRequest getDefaultRequest(); +} diff --git a/src/main/java/org/apache/sling/api/resource/mapping/package-info.java b/src/main/java/org/apache/sling/api/resource/mapping/PathRewriterFactory.java similarity index 71% copy from src/main/java/org/apache/sling/api/resource/mapping/package-info.java copy to src/main/java/org/apache/sling/api/resource/mapping/PathRewriterFactory.java index e871225..b6c3d88 100644 --- a/src/main/java/org/apache/sling/api/resource/mapping/package-info.java +++ b/src/main/java/org/apache/sling/api/resource/mapping/PathRewriterFactory.java @@ -16,9 +16,20 @@ * specific language governing permissions and limitations * under the License. */ - -@Version("1.0.1") package org.apache.sling.api.resource.mapping; -import org.osgi.annotation.versioning.Version; +import javax.servlet.http.HttpServletRequest; + +import org.jetbrains.annotations.NotNull; +import org.osgi.annotation.versioning.ProviderType; + +/** + * @since 1.1.0 + */ +@ProviderType +public interface PathRewriterFactory { + + @NotNull PathRewriter newPathWriter(); + @NotNull PathRewriter newPathWriter(@NotNull HttpServletRequest request); +} 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 a302469..b218bc6 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 @@ -22,45 +22,44 @@ import java.util.Collection; import javax.servlet.http.HttpServletRequest; -import org.apache.sling.api.resource.ResourceResolver; import org.jetbrains.annotations.NotNull; 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 + * 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} + * + * <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> + * 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 + * 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 + * {@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) */ @@ -68,20 +67,20 @@ public interface ResourceMapper { /** * Returns an URL mapped from the (resource) path applying the reverse - * mapping used by the {@link ResourceResolver#resolve(HttpServletRequest, String)} such + * mapping used by the {@link org.apache.sling.api.resource.ResourceResolver#resolve(HttpServletRequest, String)} such * that when the path is given to the - * {@link ResourceResolver#resolve(HttpServletRequest, String)} method the same resource is + * {@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 + * {@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 + * {@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. @@ -90,46 +89,46 @@ 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) */ @NotNull String getMapping(@NotNull String resourcePath, @NotNull HttpServletRequest request); - + /** * Returns all possible mappings for a given {@code resourcePath} 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}. + * {@link org.apache.sling.api.resource.ResourceResolver#close() closed}. * @since 1.0.0 (Sling API Bundle 2.19.0) */ Collection<String> getAllMappings(@NotNull String resourcePath); /** * Returns all possible mappings for a given {@code resourcePath} as URLs. - * + * * <p> * This method differs from the {@link #getMapping(String, HttpServletRequest)} 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. * @param request The http servlet request object which may be used to apply * more mapping functionality. * @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(@NotNull String resourcePath, @NotNull HttpServletRequest request); diff --git a/src/main/java/org/apache/sling/api/resource/mapping/package-info.java b/src/main/java/org/apache/sling/api/resource/mapping/package-info.java index e871225..00a1ea1 100644 --- a/src/main/java/org/apache/sling/api/resource/mapping/package-info.java +++ b/src/main/java/org/apache/sling/api/resource/mapping/package-info.java @@ -17,7 +17,7 @@ * under the License. */ -@Version("1.0.1") +@Version("1.1.0") package org.apache.sling.api.resource.mapping; import org.osgi.annotation.versioning.Version; diff --git a/src/main/java/org/apache/sling/api/resource/package-info.java b/src/main/java/org/apache/sling/api/resource/package-info.java index 7bd85e6..ac05b61 100644 --- a/src/main/java/org/apache/sling/api/resource/package-info.java +++ b/src/main/java/org/apache/sling/api/resource/package-info.java @@ -17,7 +17,7 @@ * under the License. */ -@Version("2.12.2") +@Version("2.13.0") package org.apache.sling.api.resource; import org.osgi.annotation.versioning.Version; diff --git a/src/main/java/org/apache/sling/api/wrappers/ResourceResolverWrapper.java b/src/main/java/org/apache/sling/api/wrappers/ResourceResolverWrapper.java index 67c2fbf..5f650b8 100644 --- a/src/main/java/org/apache/sling/api/wrappers/ResourceResolverWrapper.java +++ b/src/main/java/org/apache/sling/api/wrappers/ResourceResolverWrapper.java @@ -18,7 +18,7 @@ package org.apache.sling.api.wrappers; import java.util.Iterator; import java.util.Map; -import org.jetbrains.annotations.NotNull; + import javax.servlet.http.HttpServletRequest; import org.apache.sling.api.resource.LoginException; @@ -26,6 +26,8 @@ import org.apache.sling.api.resource.PersistenceException; import org.apache.sling.api.resource.Resource; import org.apache.sling.api.resource.ResourceResolver; import org.apache.sling.api.resource.ResourceWrapper; +import org.apache.sling.api.resource.mapping.PathRewriter; +import org.jetbrains.annotations.NotNull; import org.osgi.annotation.versioning.ConsumerType; /** @@ -107,6 +109,16 @@ public class ResourceResolverWrapper implements ResourceResolver { return wrapped.map(request, resourcePath); } + @Override + public @NotNull Resource resolveResource(@NotNull String path) { + return wrapped.resolveResource(path); + } + + @Override + public @NotNull PathRewriter getPathRewriter() { + return wrapped.getPathRewriter(); + } + /** * Wraps and returns the {@code Resource} obtained by calling {@code getResource} on the wrapped resource resolver. *
