Prototype api
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.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 @@
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 @@
* {@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 @@
* @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 @@
@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 @@
* @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 @@
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 @@
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/PathRewriter.java b/src/main/java/org/apache/sling/api/resource/mapping/PathRewriter.java
new file mode 100644
index 0000000..47d9124
--- /dev/null
+++ b/src/main/java/org/apache/sling/api/resource/mapping/PathRewriter.java
@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.sling.api.resource.mapping;
+
+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/PathRewriterFactory.java b/src/main/java/org/apache/sling/api/resource/mapping/PathRewriterFactory.java
new file mode 100644
index 0000000..b6c3d88
--- /dev/null
+++ b/src/main/java/org/apache/sling/api/resource/mapping/PathRewriterFactory.java
@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.sling.api.resource.mapping;
+
+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 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 @@
/**
* 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 @@
* 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 @@
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.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 @@
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.
*
