From 610bae1028aa4253fed744fab012d40a507b0263 Mon Sep 17 00:00:00 2001 From: "georg.henzler" Date: Tue, 22 Sep 2020 08:47:59 +0200 Subject: [PATCH 1/4] SLING-9745 Sling Uri Mapping SPI --- .../mapping/PathToUriMappingService.java | 77 +++++++++++++++++++ .../api/resource/mapping/package-info.java | 2 +- .../spi/urimapping/MappingChainContext.java | 65 ++++++++++++++++ .../sling/spi/urimapping/SlingUriMapper.java | 66 ++++++++++++++++ .../sling/spi/urimapping/package-info.java | 24 ++++++ 5 files changed, 233 insertions(+), 1 deletion(-) create mode 100644 src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java create mode 100644 src/main/java/org/apache/sling/spi/urimapping/MappingChainContext.java create mode 100644 src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java create mode 100644 src/main/java/org/apache/sling/spi/urimapping/package-info.java diff --git a/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java b/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java new file mode 100644 index 00000000..20e45c2c --- /dev/null +++ b/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java @@ -0,0 +1,77 @@ +/* + * 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.Map; + +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 { + + /** 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 + Map getIntermediateMappings(); + } + + /** + * 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) + * @return a @{link PathToUriMappingService.Result} + */ + Result map(@Nullable HttpServletRequest referenceRequest, @NotNull String unmappedPath); + + /** + * 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); +} \ No newline at end of file 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 e8712253..00a1ea15 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/spi/urimapping/MappingChainContext.java b/src/main/java/org/apache/sling/spi/urimapping/MappingChainContext.java new file mode 100644 index 00000000..6f65aa97 --- /dev/null +++ b/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 getAttributes(); + + /** + * Provides access to intermediate mappings as already created by SlingUriMapper instances earlier in the chain. + * + * @return the URI mappings + */ + @NotNull + Map getIntermediateMappings(); + +} diff --git a/src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java b/src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java new file mode 100644 index 00000000..c57a902d --- /dev/null +++ b/src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java @@ -0,0 +1,66 @@ +/* + * 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; + +/** + *

+ * 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. + *

+ *

+ * 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 highest + * service ranking and map() passes through the chain starting at the SlingUriMapper with the lowest service ranking. + *

+ *

+ * The resource resolver's map() and resolve() methods also use PathToUriMappingService as implementation. + *

+ */ +@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 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, @NotNull MappingChainContext context); + +} diff --git a/src/main/java/org/apache/sling/spi/urimapping/package-info.java b/src/main/java/org/apache/sling/spi/urimapping/package-info.java new file mode 100644 index 00000000..7506b457 --- /dev/null +++ b/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; + From 43f580496978061a3dcd92962928a257ee2ca311 Mon Sep 17 00:00:00 2001 From: "georg.henzler" Date: Thu, 8 Oct 2020 23:56:48 +0200 Subject: [PATCH 2/4] SLING-9745 Use IntermediateMapping tuple instead of map --- .../mapping/PathToUriMappingService.java | 58 ++++++++++++------- 1 file changed, 38 insertions(+), 20 deletions(-) diff --git a/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java b/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java index 20e45c2c..ea43d8e6 100644 --- a/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java +++ b/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java @@ -18,7 +18,7 @@ */ package org.apache.sling.api.resource.mapping; -import java.util.Map; +import java.util.List; import javax.servlet.http.HttpServletRequest; @@ -36,6 +36,25 @@ @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) + * @return a @{link PathToUriMappingService.Result} + */ + Result map(@Nullable HttpServletRequest referenceRequest, @NotNull String unmappedPath); + + /** + * 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 { @@ -48,30 +67,29 @@ public interface Result { SlingUri getUri(); /** - * Returns all intermediate mappings as produced by {@link org.apache.sling.spi.urimapping.SlingUriMapper} services + * Returns all intermediate mappings as produced by {@link org.apache.sling.spi.urimapping.SlingUriMapper} services. * * @return the intermediate mappings */ @NotNull - Map getIntermediateMappings(); + List getIntermediateMappings(); } - /** - * 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) - * @return a @{link PathToUriMappingService.Result} - */ - Result map(@Nullable HttpServletRequest referenceRequest, @NotNull String unmappedPath); + /** 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(); + } - /** - * 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); } \ No newline at end of file From 855191c70e5278c90e1591b840cc5f747d215719 Mon Sep 17 00:00:00 2001 From: "georg.henzler" Date: Thu, 8 Oct 2020 23:59:16 +0200 Subject: [PATCH 3/4] SLING-9745 Using unique SNAPSHOT version --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 36cd97d9..7007e9b3 100644 --- a/pom.xml +++ b/pom.xml @@ -28,7 +28,7 @@ org.apache.sling.api - 2.23.1-SNAPSHOT + 2.23.1-sum-SNAPSHOT Apache Sling API From 21dc4a27d33b9d89a20516df9401a0a3f64237a2 Mon Sep 17 00:00:00 2001 From: "georg.henzler" Date: Fri, 9 Oct 2020 00:08:18 +0200 Subject: [PATCH 4/4] SLING-9745 Add the ability to force an absolute URI to API/SPI map signature --- .../sling/api/resource/mapping/PathToUriMappingService.java | 3 ++- .../java/org/apache/sling/spi/urimapping/SlingUriMapper.java | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java b/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java index ea43d8e6..59d46fd3 100644 --- a/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java +++ b/src/main/java/org/apache/sling/api/resource/mapping/PathToUriMappingService.java @@ -42,9 +42,10 @@ public interface PathToUriMappingService { * @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); + Result map(@Nullable HttpServletRequest referenceRequest, @NotNull String unmappedPath, boolean forceAbsoluteUri); /** * Resolves a path relative to the given request. diff --git a/src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java b/src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java index c57a902d..a080c453 100644 --- a/src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java +++ b/src/main/java/org/apache/sling/spi/urimapping/SlingUriMapper.java @@ -58,9 +58,11 @@ public interface SlingUriMapper { * * @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, @NotNull MappingChainContext context); + SlingUri map(@NotNull SlingUri resourceUri, @Nullable HttpServletRequest request, boolean forceAbsoluteUri, + @NotNull MappingChainContext context); }