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.
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 @@
* 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/external/package-info.java b/src/main/java/org/apache/sling/api/resource/external/package-info.java
new file mode 100644
index 0000000..7853694
--- /dev/null
+++ b/src/main/java/org/apache/sling/api/resource/external/package-info.java
@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+
+@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;
