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 f149adc88030a394fa7fb693fd1442fdf1b0680e
Author: georg.henzler <georg.henz...@netcentric.biz>
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 | 66 +++++++++++++++++++
.../mapping => spi/urimapping}/package-info.java | 4 +-
5 files changed, 211 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<String, SlingUri> 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<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();
+
+}
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..c57a902
--- /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;
+
+/**
+ * <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 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;
