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:12 UTC
[sling-org-apache-sling-api] branch feature/SLING-11067-extend-URIProvider created (now e0f3405)
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a change to branch feature/SLING-11067-extend-URIProvider
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-api.git.
at e0f3405 SLING-11067 extend URIProvider by method returning Optional
This branch includes the following new commits:
new e0f3405 SLING-11067 extend URIProvider by method returning Optional
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[sling-org-apache-sling-api] 01/01: SLING-11067 extend URIProvider by method returning Optional
Posted by kw...@apache.org.
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;