You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by kw...@apache.org on 2022/01/17 09:51:13 UTC
[sling-org-apache-sling-api] 01/01: SLING-11067 extend URIProvider by method returning Optional
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch feature/SLING-11067-extend-URIProvider
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-api.git
commit e0f3405a164ba5f017edd4060e5685d2710e7ed2
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Jan 17 10:51:03 2022 +0100
SLING-11067 extend URIProvider by method returning Optional
Prevents throwing exception if URIProvider does not have URI for
resource. Cleanup some javadoc
---
.../external/ExternalizableInputStream.java | 10 +++--
.../sling/api/resource/external/URIProvider.java | 50 ++++++++++++++++------
.../sling/api/resource/external/package-info.java | 2 +-
3 files changed, 44 insertions(+), 18 deletions(-)
diff --git a/src/main/java/org/apache/sling/api/resource/external/ExternalizableInputStream.java b/src/main/java/org/apache/sling/api/resource/external/ExternalizableInputStream.java
index fc175cd..753504c 100644
--- a/src/main/java/org/apache/sling/api/resource/external/ExternalizableInputStream.java
+++ b/src/main/java/org/apache/sling/api/resource/external/ExternalizableInputStream.java
@@ -22,23 +22,25 @@ package org.apache.sling.api.resource.external;
import java.net.URI;
import org.jetbrains.annotations.NotNull;
+import org.osgi.annotation.versioning.ProviderType;
/**
* This interface is normally used to extend an InputStream to indicate that it has a URI form that could
* be used in place of the InputStream if desired. It is used in situations where the internal of a ResourceProvider
- * wants to offload IO to channels that do not pass through the JVM. The URI that is returned may have restrictions
+ * wants to offload I/O to channels that do not pass through the JVM. The URI that is returned may have restrictions
* imposed on it requiring it to be used immediately. Do not store the URI for later usage as it will, in most cases,
* have expired.
- *
+ * Every implementation implementing {@code ExternalizableInputStream} should rely on {@link URIProviders} for getting the URI.
+ * @since 1.0.0 (Sling API Bundle 2.16.4)
*/
+@ProviderType
public interface ExternalizableInputStream {
/**
* Get a URI that is specific to the current session, and may be used in any context internal or external. The URI must not
- * be stored and must not be shared between clients. For a wider range of URIs the caller should use the URIProvider class
+ * be stored and must not be shared between clients. For a wider range of URIs the caller should use the {@link URIProvider} class
* directly and not this interface.
* @return a URI intended for any network context.
*/
@NotNull URI getURI();
-
}
diff --git a/src/main/java/org/apache/sling/api/resource/external/URIProvider.java b/src/main/java/org/apache/sling/api/resource/external/URIProvider.java
index 8f4422a..3e36d24 100644
--- a/src/main/java/org/apache/sling/api/resource/external/URIProvider.java
+++ b/src/main/java/org/apache/sling/api/resource/external/URIProvider.java
@@ -20,32 +20,26 @@
package org.apache.sling.api.resource.external;
import java.net.URI;
+import java.util.Optional;
import org.apache.sling.api.resource.Resource;
import org.jetbrains.annotations.NotNull;
import org.osgi.annotation.versioning.ProviderType;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
/**
- * Provides a URI in exchange for a Resource.
- * Typically the Resource will represent something where is a URI is valiable and usefull.
- * Implementations of this interface must ensure that the any underlying security model is delegated
+ * Provides a URI representing the given Resource.
+ * Implementations of this interface must ensure that the underlying security model is delegated
* securely and not circumvented. Typically resource provider bundles should implement this provider as in most cases
* internal implementation details of the resource will be required to achieve the implementation. Ideally
* implementations should be carefully reviewed by peers.
- *
+ * @since 1.0.0 (Sling API Bundle 2.16.4)
*/
@ProviderType
public interface URIProvider {
- /**
- * Return a URI applicable to the defined scope.
- * @param resource the resource to convert from.
- * @param scope the required scope.
- * @param operation the required operation.
- * @return a URI if the resource has a URI suitable for the requested scope and operation, otherwise the implementation should throw an IlleagalArgumentException.
- * @throws IllegalArgumentException if a URI for the requested scope and operation cannot be provided to the caller.
- */
- @NotNull URI toURI(@NotNull Resource resource, @NotNull URIProvider.Scope scope, @NotNull URIProvider.Operation operation);
+ static final Logger LOG = LoggerFactory.getLogger(URIProvider.class);
/**
* Defines which operation the URI may be used to perform.
@@ -91,4 +85,34 @@ public interface URIProvider {
*/
PUBLIC
}
+
+ /**
+ * Return a URI applicable to the defined scope.
+ * @param resource the resource to convert from.
+ * @param scope the required scope.
+ * @param operation the required operation.
+ * @return a URI if the resource has a URI suitable for the requested scope and operation, otherwise the implementation should throw an {@link IllegalArgumentException}.
+ * @throws IllegalArgumentException if a URI for the requested scope and operation cannot be provided to the caller.
+ * @deprecated Use {@link #getOptionalUriForResource(Resource, Scope, Operation)} instead.
+ */
+ @Deprecated
+ @NotNull URI toURI(@NotNull Resource resource, @NotNull Scope scope, @NotNull Operation operation);
+
+ /**
+ * Return a URI applicable to the defined scope.
+ * @param resource the resource to convert from.
+ * @param scope the required scope.
+ * @param operation the required operation.
+ * @return a URI if the resource has a URI suitable for the requested scope and operation, otherwise {@link Optional#empty()}.
+ * @since 1.1.0 (Sling API Bundle 2.25.0)
+ */
+ default @NotNull Optional<URI> getOptionalUriForResource(@NotNull Resource resource, @NotNull Scope scope, @NotNull Operation operation) {
+ try {
+ return Optional.of(toURI(resource, scope, operation));
+ } catch (IllegalArgumentException e) {
+ LOG.debug("{} declined toURI() for resource '{}' (scope {}, operation {})", this.getClass(), resource.getPath(), scope, operation, e);
+ return Optional.empty();
+ }
+ }
+
}
diff --git a/src/main/java/org/apache/sling/api/resource/external/package-info.java b/src/main/java/org/apache/sling/api/resource/external/package-info.java
index 3b3161c..3721047 100644
--- a/src/main/java/org/apache/sling/api/resource/external/package-info.java
+++ b/src/main/java/org/apache/sling/api/resource/external/package-info.java
@@ -17,7 +17,7 @@
* under the License.
*/
-@Version("1.0.2")
+@Version("1.1.0")
package org.apache.sling.api.resource.external;
import org.osgi.annotation.versioning.Version;