From commits-return-89530-archive-asf-public=cust-asf.ponee.io@sling.apache.org Wed Sep 23 08:16:25 2020 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mailroute1-lw-us.apache.org (mailroute1-lw-us.apache.org [207.244.88.153]) by mx-eu-01.ponee.io (Postfix) with ESMTPS id CF7A61806D6 for ; Wed, 23 Sep 2020 10:16:24 +0200 (CEST) Received: from mail.apache.org (localhost [127.0.0.1]) by mailroute1-lw-us.apache.org (ASF Mail Server at mailroute1-lw-us.apache.org) with SMTP id F3F9C123D83 for ; Wed, 23 Sep 2020 08:16:23 +0000 (UTC) Received: (qmail 6191 invoked by uid 500); 23 Sep 2020 08:16:23 -0000 Mailing-List: contact commits-help@sling.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@sling.apache.org Delivered-To: mailing list commits@sling.apache.org Received: (qmail 6171 invoked by uid 99); 23 Sep 2020 08:16:23 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 23 Sep 2020 08:16:23 +0000 Received: by gitbox.apache.org (ASF Mail Server at gitbox.apache.org, from userid 33) id 8A9E18DCA9; Wed, 23 Sep 2020 08:16:23 +0000 (UTC) Date: Wed, 23 Sep 2020 08:16:24 +0000 To: "commits@sling.apache.org" Subject: [sling-org-apache-sling-api] 01/01: SLING-9745 Sling Uri Mapping SPI MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit From: ghenzler@apache.org In-Reply-To: <160084898347.7723.7975759681212179350@gitbox.apache.org> References: <160084898347.7723.7975759681212179350@gitbox.apache.org> X-Git-Host: gitbox.apache.org X-Git-Repo: sling-org-apache-sling-api X-Git-Refname: refs/heads/feature/SLING-9662-Introduce-SlingUri-Mapping-SPI-v3 X-Git-Reftype: branch X-Git-Rev: 415ec0d4b3dfb184d653571364a07d821a890a10 X-Git-NotificationType: diff X-Git-Multimail-Version: 1.5.dev Auto-Submitted: auto-generated Message-Id: <20200923081623.8A9E18DCA9@gitbox.apache.org> This is an automated email from the ASF dual-hosted git repository. ghenzler pushed a commit to branch feature/SLING-9662-Introduce-SlingUri-Mapping-SPI-v3 in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-api.git commit 415ec0d4b3dfb184d653571364a07d821a890a10 Author: georg.henzler AuthorDate: Tue Sep 22 08:47:59 2020 +0200 SLING-9745 Sling Uri Mapping SPI --- .../resource/mapping/PathToUriMappingService.java | 77 ++++++++++++++++++++++ .../sling/api/resource/mapping/package-info.java | 2 +- .../sling/spi/urimapping/MappingChainContext.java | 65 ++++++++++++++++++ .../sling/spi/urimapping/SlingUriMapper.java | 68 +++++++++++++++++++ .../mapping => spi/urimapping}/package-info.java | 4 +- 5 files changed, 213 insertions(+), 3 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 new file mode 100644 index 0000000..20e45c2 --- /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 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/spi/urimapping/MappingChainContext.java b/src/main/java/org/apache/sling/spi/urimapping/MappingChainContext.java new file mode 100644 index 0000000..6f65aa9 --- /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 0000000..34b6afb --- /dev/null +++ b/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; + +/** + *

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

+ * + * @since 1.0.0 (Sling API Bundle 2.23.0) + */ +@ConsumerType +public interface SlingUriMapper { + + /** + * Contributes to the resolve process, may or may not make adjustments to the Sling URI + * + * @param resourceUri the URI to be resolved + * @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 map 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/api/resource/mapping/package-info.java b/src/main/java/org/apache/sling/spi/urimapping/package-info.java similarity index 92% copy from src/main/java/org/apache/sling/api/resource/mapping/package-info.java copy to src/main/java/org/apache/sling/spi/urimapping/package-info.java index e871225..7506b45 100644 --- a/src/main/java/org/apache/sling/api/resource/mapping/package-info.java +++ b/src/main/java/org/apache/sling/spi/urimapping/package-info.java @@ -17,8 +17,8 @@ * under the License. */ -@Version("1.0.1") -package org.apache.sling.api.resource.mapping; +@Version("1.0.0") +package org.apache.sling.spi.urimapping; import org.osgi.annotation.versioning.Version;