This is an automated email from the ASF dual-hosted git repository. ieb pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-api.git
The following commit(s) were added to refs/heads/master by this push: new 9052826 SLING-7140 Support redirects to URLs provided by the underlying resource provider. Refactored to move API into external package and avoid changing resource API versions. 9052826 is described below commit 90528268eb01edff266851e085c835f487f8f4bd Author: Ian Boston <i...@tfd.co.uk> AuthorDate: Mon Oct 23 11:31:32 2017 +0100 SLING-7140 Support redirects to URLs provided by the underlying resource provider. Refactored to move API into external package and avoid changing resource API versions. --- .../org/apache/sling/api/resource/URIProvider.java | 51 ------------ .../{ => external}/ExternalizableInputStream.java | 15 +--- .../sling/api/resource/external/URIProvider.java | 94 ++++++++++++++++++++++ .../api/resource/{ => external}/package-info.java | 4 +- .../apache/sling/api/resource/package-info.java | 2 +- 5 files changed, 101 insertions(+), 65 deletions(-) diff --git a/src/main/java/org/apache/sling/api/resource/URIProvider.java b/src/main/java/org/apache/sling/api/resource/URIProvider.java deleted file mode 100644 index 8d2f381..0000000 --- a/src/main/java/org/apache/sling/api/resource/URIProvider.java +++ /dev/null @@ -1,51 +0,0 @@ -/* - * 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; - -import org.osgi.annotation.versioning.ProviderType; - -import java.net.URI; - -/** - * 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 - * 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 2.11.0 - */ -@ProviderType -public interface URIProvider { - - /** - * Return a URI appicable to the defined scope. - * @param scope the required scope. - * @param resource the resource to convert from. - * @return a URI if the resoruce has a URI suitable for the requested scope. - */ - URI toURI(URIProvider.Scope scope, Resource resource); - - enum Scope { - PUBLIC, - INTERNAL - } -} \ No newline at end of file diff --git a/src/main/java/org/apache/sling/api/resource/ExternalizableInputStream.java b/src/main/java/org/apache/sling/api/resource/external/ExternalizableInputStream.java similarity index 73% rename from src/main/java/org/apache/sling/api/resource/ExternalizableInputStream.java rename to src/main/java/org/apache/sling/api/resource/external/ExternalizableInputStream.java index 0f3fbfe..b7d5f53 100644 --- a/src/main/java/org/apache/sling/api/resource/ExternalizableInputStream.java +++ b/src/main/java/org/apache/sling/api/resource/external/ExternalizableInputStream.java @@ -17,7 +17,7 @@ * under the License. */ -package org.apache.sling.api.resource; +package org.apache.sling.api.resource.external; import java.net.URI; @@ -28,22 +28,15 @@ import java.net.URI; * 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. * - * @since 2.11.0 */ public interface ExternalizableInputStream { /** - * Get a URI that is specific to the current session, and may be used anywhere. May return null if this - * type of URI is not available. + * 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 + * directly and not this interface. * @return a URI intended for any network context. */ URI getURI(); - /** - * Get a URI that is specific to the current session and may only be used in a private context. A private network context means - * that the URI may only be resolvable inside a private network. Usign this URL in any context will not always work, and - * may leak information about the private network. - * @return a URI intended for a private network context. - */ - URI getPrivateURI(); } 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 new file mode 100644 index 0000000..be6d2bc --- /dev/null +++ b/src/main/java/org/apache/sling/api/resource/external/URIProvider.java @@ -0,0 +1,94 @@ +/* + * 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.external; + +import org.apache.sling.api.resource.Resource; +import org.omg.CORBA.INTERNAL; +import org.osgi.annotation.versioning.ProviderType; + +import java.net.URI; + +/** + * 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 + * 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. + * + */ +@ProviderType +public interface URIProvider { + + /** + * Return a URI appicable to the defined scope. + * @param scope the required scope. + * @param operation the required operation. + * @param resource the resource to convert from. + * @return a URI if the resoruce has a URI suitable for the requested scope and operation, otherwise the implemenation should throw an IlleagalArgumentException. + * @throws IllegalArgumentException if a URI for the requested scope and operation cannot be provided to the caller. + */ + URI toURI(Resource resource, URIProvider.Scope scope, URIProvider.Operation operation); + + /** + * Defines which operatio the URI may be used to perform. + */ + enum Operation { + /** + * The URI may be used to create resources at the resource identified by the Resource. + */ + CREATE, + /** + * The URI may be used to read the resource. + */ + READ, + /** + * The URI may be used to update the resource. + */ + UPDATE, + /** + * The URI may be used to delete the resource. + */ + DELETE + } + + /** + * Defines the scope in which the URI may be used. + * Implementations should pay close attention to the scope requested and not emit URIs inappropriate for the scope requested. + */ + enum Scope { + /** + * A External URI safe to be used by the requesting client in a external context. + * This does not imply it can be stored, shared between clients or published, only that the client may be on the public + * internet as opposed to an internal network. + */ + EXTERNAL, + /** + * Internal URI only to be used by a client on an internal network and never leaked onto a public network. + */ + INTERNAL, + /** + * A URI that may be published to many client in public context. Implementations should only issue URIs with this scope + * if the URI can safely be shared between multiple clients, and therefore by definition public to anonymous clients anywhere + * on the internet. + */ + PUBLIC + } +} \ No newline at end of file diff --git a/src/main/java/org/apache/sling/api/resource/package-info.java b/src/main/java/org/apache/sling/api/resource/external/package-info.java similarity index 92% copy from src/main/java/org/apache/sling/api/resource/package-info.java copy to src/main/java/org/apache/sling/api/resource/external/package-info.java index 2c357f6..7853694 100644 --- a/src/main/java/org/apache/sling/api/resource/package-info.java +++ b/src/main/java/org/apache/sling/api/resource/external/package-info.java @@ -17,8 +17,8 @@ * under the License. */ -@Version("2.11.0") -package org.apache.sling.api.resource; +@Version("1.0.0") +package org.apache.sling.api.resource.external; import org.osgi.annotation.versioning.Version; diff --git a/src/main/java/org/apache/sling/api/resource/package-info.java b/src/main/java/org/apache/sling/api/resource/package-info.java index 2c357f6..2928554 100644 --- a/src/main/java/org/apache/sling/api/resource/package-info.java +++ b/src/main/java/org/apache/sling/api/resource/package-info.java @@ -17,7 +17,7 @@ * under the License. */ -@Version("2.11.0") +@Version("2.10.1") package org.apache.sling.api.resource; import org.osgi.annotation.versioning.Version; -- To stop receiving notification emails like this one, please contact ['"commits@sling.apache.org" <commits@sling.apache.org>'].