SLING-9745 Sling Uri Mapping SPI

pom.xml

@@ -28,7 +28,7 @@
     </parent>
 
     <artifactId>org.apache.sling.api</artifactId>
-    <version>2.23.1-SNAPSHOT</version>
+    <version>2.23.1-sum-SNAPSHOT</version>
 
     <name>Apache Sling API</name>
     <description>

src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java

@@ -0,0 +1,96 @@
+/*
+ * 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 java.util.List;
+
+import javax.servlet.http.HttpServletRequest;
+
+import org.apache.sling.api.uri.SlingUri;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Provides a way to resolve and map paths to Sling URIs. Both operations are extensible by
+ * {@link org.apache.sling.spi.urimapping.SlingUriMapper} OSGi services.
+ * 
+ * @since 1.1.0 (Sling API Bundle 2.23.0)
+ */
+@ProviderType
+public interface PathToUriMappingService {
+
+    /**
+     * Maps a path to a Sling URI.
+     * 
+     * @param referenceRequest the reference request with the same properties as the actual request that will have to resolve the produced
+     *        URI.
+     * @param unmappedPath the path that is not mapped yet (may or may not contain selector, extension and suffix)
+     * @param forceAbsoluteUri whether or not an absolute URI is required
+     * @return a @{link PathToUriMappingService.Result}
+     */
+    Result map(@Nullable HttpServletRequest referenceRequest, @NotNull String unmappedPath, boolean forceAbsoluteUri);
+
+    /**
+     * Resolves a path relative to the given request.
+     * 
+     * @param request the request
+     * @param path the path to be resolved or null for which case the information from request is used
+     * @return a @{link PathToUriMappingService.Result}
+     */
+    Result resolve(@Nullable HttpServletRequest request, @Nullable String path);
+
+    /** The result of a map or resolve operation */
+    @ProviderType
+    public interface Result {
+        /**
+         * The Sling URI as result of the resolve or map operation.
+         * 
+         * @return the Sling URI
+         */
+        @NotNull
+        SlingUri getUri();
+
+        /**
+         * Returns all intermediate mappings as produced by {@link org.apache.sling.spi.urimapping.SlingUriMapper} services.
+         * 
+         * @return the intermediate mappings
+         */
+        @NotNull
+        List<IntermediateMapping> getIntermediateMappings();
+    }
+
+    /** Tuple of mapper name and its result as SlingUri. */
+    @ProviderType
+    public interface IntermediateMapping {
+
+        /**
+         * @return The name of the {@link org.apache.sling.spi.urimapping.SlingUriMapper} that produced the intermediate result
+         */
+        @NotNull
+        String getName();
+
+        /**
+         * @return The SlingUri as produced by the {@link org.apache.sling.spi.urimapping.SlingUriMapper}
+         */
+        @NotNull
+        SlingUri getUri();
+    }
+
+}

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;

src/main/java/org/apache/sling/spi/urimapping/MappingChainContext.java

@@ -0,0 +1,65 @@
+/*
+ * 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.spi.urimapping;
+
+import java.util.Map;
+
+import org.apache.sling.api.resource.ResourceResolver;
+import org.apache.sling.api.uri.SlingUri;
+import org.jetbrains.annotations.NotNull;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Provides SlingUriMapper instances with additional context.
+ * 
+ * @since 1.0.0 (Sling API Bundle 2.23.0)
+ */
+@ProviderType
+public interface MappingChainContext {
+
+    /**
+     * May be called by any SlingUriMapper in the chain to indicate that the rest of the chain should be skipped.
+     */
+    void skipRemainingChain();
+
+    /**
+     * A service resource resolver with read permissions.
+     * 
+     * @return a resource resolver
+     */
+    @NotNull
+    ResourceResolver getResourceResolver();
+
+    /**
+     * Allows to share state between SlingUriMapper instances in the chain.
+     * 
+     * @return a mutable map to share state (never null).
+     */
+    @NotNull
+    Map<String, Object> getAttributes();
+
+    /**
+     * Provides access to intermediate mappings as already created by SlingUriMapper instances earlier in the chain.
+     * 
+     * @return the URI mappings
+     */
+    @NotNull
+    Map<String, SlingUri> getIntermediateMappings();
+
+}

src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java

@@ -0,0 +1,68 @@
+/*
+ * 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.spi.urimapping;
+
+import javax.servlet.http.HttpServletRequest;
+
+import org.apache.sling.api.uri.SlingUri;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.osgi.annotation.versioning.ConsumerType;
+
+/**
+ * <p>
+ * SPI interface that contributes to the resolving and mapping of Sling URIs. All registered services build a conceptual chain sorted by
+ * service ranking. The Sling URI is passed through the chain while any SlingUriMapper chain member may or may not make adjustments to the
+ * Sling URI.
+ * </p>
+ * <p>
+ * The {@link org.apache.sling.api.resource.mapping.PathToUriMappingService} allows to call the resolve() (however normally called by
+ * request only) and map() methods. resolve() passes through the chain starting at the SlingUriMapper with the <strong>highest</strong>
+ * service ranking and map() passes through the chain starting at the SlingUriMapper with the <strong>lowest</strong> service ranking.
+ * </p>
+ * <p>
+ * The resource resolver's map() and resolve() methods also use PathToUriMappingService as implementation.
+ * </p>
+ */
+@ConsumerType
+public interface SlingUriMapper {
+
+    /**
+     * Contributes to the resolve process (forward mapping), may or may not make adjustments to the Sling URI
+     * 
+     * @param resourceUri the URI to be mapped for resolution
+     * @param request the request context that may or may not influence the resolution process (request may be null)
+     * @param context can be used to skip further processing of the chain or for sharing state between instances of SlingUriMapper services
+     * @return the adjusted SlingUri or if no adjustments are necessary, just return resourceUri as passed in by first parameter
+     */
+    SlingUri resolve(@NotNull SlingUri resourceUri, @Nullable HttpServletRequest request, @NotNull MappingChainContext context);
+
+    /**
+     * Contributes to the reverse mapping process, may or may not make adjustments to the Sling URI.
+     * 
+     * @param resourceUri the URI to be mapped
+     * @param request the request to be taken as reference
+     * @param forceAbsoluteUri whether or not an absolute URI is required
+     * @param context can be used to skip further processing of the chain or for sharing state between instances of SlingUriMapper services
+     * @return the adjusted SlingUri or if no adjustments are necessary, just return resourceUri as passed in by first parameter
+     */
+    SlingUri map(@NotNull SlingUri resourceUri, @Nullable HttpServletRequest request, boolean forceAbsoluteUri,
+            @NotNull MappingChainContext context);
+
+}

src/main/java/org/apache/sling/spi/urimapping/package-info.java

@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+
+@Version("1.0.0")
+package org.apache.sling.spi.urimapping;
+
+import org.osgi.annotation.versioning.Version;
+