sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ghenz...@apache.org
Subject [sling-org-apache-sling-api] 01/01: SLING-9745 Sling Uri Mapping SPI
Date Wed, 23 Sep 2020 08:16:24 GMT
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 <georg.henzler@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       | 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<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..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;
+
+/**
+ * <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>
+ * 
+ * @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;
 


Mime
View raw message