This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
commit 97f67d1dc8965f638d54d43a644741ac0add21a0
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Fri Dec 20 11:12:55 2024 +0100
Revisit the S3 documentation for reducing a confusion about what S3 call
"key".
In the context of Apache SIS, a S3 "key" is interpreted as a file path.
Furthermore, "key" was too easily confused with "access key".
---
.../org/apache/sis/cloud/aws/s3/FileService.java | 20 +++++++--------
.../main/org/apache/sis/cloud/aws/s3/KeyPath.java | 4 +--
.../org/apache/sis/cloud/aws/s3/package-info.java | 29 +++++++++++++---------
3 files changed, 29 insertions(+), 24 deletions(-)
diff --git
a/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/FileService.java
b/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/FileService.java
index 210c84bacc..f68ad04cc0 100644
---
a/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/FileService.java
+++
b/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/FileService.java
@@ -64,13 +64,13 @@ import org.apache.sis.util.collection.Containers;
* This provider accepts URIs of the following forms:
*
* <ul>
- * <li>{@code S3://bucket/key}</li>
- * <li>{@code S3://accessKey@bucket/key} (password not allowed)</li>
+ * <li>{@code S3://bucket/file}</li>
+ * <li>{@code S3://accessKey@bucket/file} (password not allowed)</li>
* </ul>
*
- * Keys can be paths with components separated by the {@code '/'} separator.
+ * "Files" are S3 keys interpreted as paths with components separated by the
{@code '/'} separator.
* The password and the region can be specified at {@linkplain #newFileSystem
file system initialization time}.
- * The endpoint (e.g. {@code "s3.eu-central-1.amazonaws.com"}) shall
<em>not</em> be specified in the URI.
+ * The endpoint (e.g. {@code "s3.eu-central-1.amazonaws.com"}) shall
<em>not</em> be specified in the <abbr>URI</abbr>.
* In particular the region ({@code "eu-central-1"} in the above example) can
depend on the server location
* instead of the data to access, and can be a global configuration for the
server.
*
@@ -169,10 +169,10 @@ public class FileService extends FileSystemProvider {
}
/**
- * Initializes and returns a new file system identified by a URI.
- * The given URI shall have the following pattern:
+ * Initializes and returns a new file system identified by a
<abbr>URI</abbr>.
+ * The given <abbr>URI</abbr> shall have the following pattern:
*
- * <pre class="text">S3://accessKey@bucket/key</pre>
+ * <pre class="text">S3://accessKey@bucket/file</pre>
*
* In current version all path components after {@code accessKey} are
ignored.
* A future version may allow finer grain control.
@@ -193,7 +193,7 @@ public class FileService extends FileSystemProvider {
* {@linkplain Region#of(String) convertible} to region.</li>
* </ul>
*
- * @param uri a URI of the form {@code
"s3://accessKey@bucket/key"}.
+ * @param uri a <abbr>URI</abbr> of the form {@code
"s3://accessKey@bucket/file"}.
* @param properties properties to configure the file system, or {@code
null} if none.
* @return the new file system.
* @throws IllegalArgumentException if the URI or the map contains invalid
values.
@@ -258,7 +258,7 @@ public class FileService extends FileSystemProvider {
* If the file system has not been created or has been closed,
* then this method throws {@link FileSystemNotFoundException}.
*
- * @param uri a URI of the form {@code "s3://accessKey@bucket/key"}.
+ * @param uri a <abbr>URI</abbr> of the form {@code
"s3://accessKey@bucket/file"}.
* @return the file system previously created by {@link
#newFileSystem(URI, Map)}.
* @throws IllegalArgumentException if the URI is not supported by this
provider.
* @throws FileSystemNotFoundException if the file system does not exist
or has been closed.
@@ -281,7 +281,7 @@ public class FileService extends FileSystemProvider {
* The resulting {@code Path} is associated with a {@link FileSystem}
* that already exists or is constructed automatically.
*
- * @param uri a URI of the form {@code "s3://accessKey@bucket/key"}.
+ * @param uri a <abbr>URI</abbr> of the form {@code
"s3://accessKey@bucket/file"}.
* @return the resulting {@code Path}.
* @throws IllegalArgumentException if the URI is not supported by this
provider.
* @throws FileSystemNotFoundException if the file system does not exist
and cannot be created automatically.
diff --git
a/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/KeyPath.java
b/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/KeyPath.java
index bb876f4f6c..50171eb101 100644
---
a/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/KeyPath.java
+++
b/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/KeyPath.java
@@ -187,8 +187,8 @@ final class KeyPath implements Path {
* with any number of occurrences of the {@link
ClientFileSystem#separator} separator:
*
* <ul>
- * <li>{@code "S3://bucket/key"} (note that {@code "accessKey@bucket"}
is not accepted)</li>
- * <li>{@code "/bucket/key"} (absolute path)</li>
+ * <li>{@code "S3://bucket/file"} (note that {@code "accessKey@bucket"}
is not accepted)</li>
+ * <li>{@code "/bucket/file"} (absolute path)</li>
* <li>{@code "key"} (relative path)</li>
* </ul>
*
diff --git
a/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/package-info.java
b/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/package-info.java
index 62ea6f97c0..caf3fc4632 100644
---
a/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/package-info.java
+++
b/endorsed/src/org.apache.sis.cloud.aws/main/org/apache/sis/cloud/aws/s3/package-info.java
@@ -20,29 +20,34 @@
* Java NIO wrappers for Amazon Simple Storage Service (S3).
* The wrapped framework is AWS SDK version 2.
*
- * <h2>URL syntax</h2>
- * <p>The file system in this package accepts URIs of the following forms:</p>
+ * <h2><abbr>URL</abbr> syntax</h2>
+ * The S3 storage mechanism is similar to a {@code java.util.Map}:
+ * a set of key-value pairs where the keys have no particular meaning for S3.
+ * However, Apache <abbr>SIS</abbr> interprets the key names in a way similar
to file paths.
+ * In this module, <dfn>files</dfn> can be understood as S3 <em>keys</em>
+ * with a special meaning given by Apache <abbr>SIS</abbr> to the {@code '/'}
character.
+ * The file system view in this package accepts <abbr>URI</abbr>s of the
following forms:
*
* <ul>
- * <li>{@code S3://bucket/key}</li>
- * <li>{@code S3://accessKey@bucket/key} (password not allowed)</li>
+ * <li>{@code S3://bucket/file}</li>
+ * <li>{@code S3://accessKey@bucket/file} (password not allowed in
<abbr>URI</abbr>)</li>
* </ul>
*
- * <p>Keys can be paths with components separated by the {@code '/'} separator.
+ * The separator character for the file components is {@code '/'} on all
platforms.
* The password and the region can be specified at
* {@linkplain java.nio.file.FileSystems#newFileSystem file system
initialization time}.
- * The endpoint (e.g. {@code "s3.eu-central-1.amazonaws.com"}) shall
<em>not</em> be specified in the URI.
- * In particular the region ({@code "eu-central-1"} in the above example) can
depend on the server location
- * instead of the data to access, and can be a global configuration for the
server.</p>
+ * The endpoint (e.g. {@code "s3.eu-central-1.amazonaws.com"}) shall
<em>not</em> be specified in the <abbr>URI</abbr>.
+ * In particular, the region ({@code "eu-central-1"} in the above example) can
depend on the server location
+ * instead of the data to access, and can be a global configuration for the
server.
*
* <p>After a {@link java.nio.file.Path} instance has been created,
* the following syntax can be used on {@code Path} methods expecting a {@code
String} argument.
- * The {@code key} can be a path with {@code '/'} separators.</p>
+ * The {@code file} can be a string with {@code '/'} separators.</p>
*
* <ul>
- * <li>{@code "S3://bucket/key"} (note that {@code "accessKey@bucket"} is
not accepted)</li>
- * <li>{@code "/bucket/key"} (absolute path)</li>
- * <li>{@code "key"} (relative path)</li>
+ * <li>{@code "S3://bucket/file"}</li>
+ * <li>{@code "/bucket/file"} (absolute path)</li>
+ * <li>{@code "file"} (relative path)</li>
* </ul>
*
* <h2>Thread safety</h2>
