From 0bef38d53d047958848f8e1539103a39e7883411 Mon Sep 17 00:00:00 2001 From: Marco Ziccardi Date: Thu, 30 Jun 2016 10:39:58 +0200 Subject: [PATCH] Minor javadoc fixes to gcloud-java-nio --- gcloud-java-contrib/README.md | 2 +- .../gcloud-java-nio-examples/README.md | 19 ++++++++------- .../gcloud-java-nio-examples/pom.xml | 2 +- gcloud-java-contrib/gcloud-java-nio/README.md | 2 +- gcloud-java-contrib/gcloud-java-nio/pom.xml | 2 +- .../nio/CloudStorageConfiguration.java | 2 +- .../contrib/nio/CloudStorageFileSystem.java | 12 ++++++---- .../nio/CloudStorageFileSystemProvider.java | 7 +++--- .../contrib/nio/CloudStorageOption.java | 6 ++--- .../contrib/nio/CloudStorageOptions.java | 2 +- .../storage/contrib/nio/CloudStoragePath.java | 7 +++--- .../storage/contrib/nio/CloudStorageUtil.java | 6 ++--- .../storage/contrib/nio/it/ITGcsNio.java | 21 ++++++++-------- gcloud-java-examples/README.md | 11 +++++---- .../com/google/cloud/examples/nio/Stat.java | 10 ++++---- .../cloud/storage/testing/package-info.java | 24 +------------------ 16 files changed, 59 insertions(+), 76 deletions(-) diff --git a/gcloud-java-contrib/README.md b/gcloud-java-contrib/README.md index 0a0ad0dd61a6..85808ae24a07 100644 --- a/gcloud-java-contrib/README.md +++ b/gcloud-java-contrib/README.md @@ -13,7 +13,7 @@ Contents -------- * [gcloud-java-nio](./gcloud-java-nio/): NIO Filesystem Provider for Google Cloud Storage. - * [gcloud-java-nio-examples](./gcloud-java-nio-examples/): How to add GCS NIO after the fact. + * [gcloud-java-nio-examples](./gcloud-java-nio-examples/): How to add Google Cloud Storage NIO after the fact. Quickstart ---------- diff --git a/gcloud-java-contrib/gcloud-java-nio-examples/README.md b/gcloud-java-contrib/gcloud-java-nio-examples/README.md index c9db073aa933..9a07c31177f2 100644 --- a/gcloud-java-contrib/gcloud-java-nio-examples/README.md +++ b/gcloud-java-contrib/gcloud-java-nio-examples/README.md @@ -1,8 +1,8 @@ Example of adding the Google Cloud Storage NIO Provider to a legacy jar ======================================================================= -This project shows how to add GCS capabilities to a jar file for a Java 7 application -that uses Java NIO without the need to recompile. +This project shows how to add Google Cloud Storage capabilities to a jar file for a Java 7 +application that uses Java NIO without the need to recompile. Note that whenever possible, you instead want to recompile the app and use the normal dependency mechanism to add a dependency to gcloud-java-nio. You can see examples of @@ -25,19 +25,20 @@ To run this example: java -cp gcloud-java-contrib/gcloud-java-nio/target/gcloud-java-nio-0.2.5-SNAPSHOT-shaded.jar:gcloud-java-contrib/gcloud-java-nio-examples/target/gcloud-java-nio-examples-0.2.5-SNAPSHOT.jar com.google.cloud.nio.examples.ListFilesystems ``` - Notice that it lists gcs, which it wouldn't if you ran it without the nio jar: + Notice that it lists Google Cloud Storage, which it wouldn't if you ran it without the NIO jar: ``` java -cp gcloud-java-contrib/gcloud-java-nio-examples/target/gcloud-java-nio-examples-0.2.5-SNAPSHOT.jar com.google.cloud.nio.examples.ListFilesystems ``` -The sample doesn't have anything about GCS in it. It gets that ability from the nio jar that -we're adding to the classpath. You can use the nio "fat shaded" jar for this purpose as it also -includes the dependencies for gcloud-java-nio. +The sample doesn't have anything about Google Cloud Storage in it. It gets that ability from the NIO +jar that we're adding to the classpath. You can use the NIO "fat shaded" jar for this purpose as it +also includes the dependencies for gcloud-java-nio. The underlying mechanism is Java's standard [ServiceLoader](https://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html) facility, the [standard way](http://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/filesystemprovider.html) to plug in NIO providers like this one. If you have access to a project's source code you can also simply add gcloud-java-nio as -a dependency and let Maven pull in the required dependencies (this is what the nio unit tests do). -This approach is preferable as the fat jar approach may waste memory on multiple copies of dependencies. +a dependency and let Maven pull in the required dependencies (this is what the NIO unit tests do). +This approach is preferable as the fat jar approach may waste memory on multiple copies of +dependencies. -[developers-console]:https://console.developers.google.com/ \ No newline at end of file +[developers-console]:https://console.developers.google.com/ diff --git a/gcloud-java-contrib/gcloud-java-nio-examples/pom.xml b/gcloud-java-contrib/gcloud-java-nio-examples/pom.xml index c44b927f25ba..448c38a2e8e2 100644 --- a/gcloud-java-contrib/gcloud-java-nio-examples/pom.xml +++ b/gcloud-java-contrib/gcloud-java-nio-examples/pom.xml @@ -6,7 +6,7 @@ GCloud Java NIO examples https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-contrib/gcloud-java-nio-examples - Demonstrates how to use the gcloud-java-nio jar to add GCS functionality to legacy code. + Demonstrates how to use the gcloud-java-nio jar to add Google Cloud Storage functionality to legacy code. com.google.cloud diff --git a/gcloud-java-contrib/gcloud-java-nio/README.md b/gcloud-java-contrib/gcloud-java-nio/README.md index 9a15d8e24458..ecb541971020 100644 --- a/gcloud-java-contrib/gcloud-java-nio/README.md +++ b/gcloud-java-contrib/gcloud-java-nio/README.md @@ -141,7 +141,7 @@ yet implemented: * Resuming upload or download * Generations * File attributes - * (more) + * (more - list is not exhaustive) Some features are not on the roadmap: this library would be a poor choice to mirror a local filesystem onto the cloud because Google Cloud Storage has a diff --git a/gcloud-java-contrib/gcloud-java-nio/pom.xml b/gcloud-java-contrib/gcloud-java-nio/pom.xml index 3c988e768bbc..a63b8b45856e 100644 --- a/gcloud-java-contrib/gcloud-java-nio/pom.xml +++ b/gcloud-java-contrib/gcloud-java-nio/pom.xml @@ -6,7 +6,7 @@ GCloud Java NIO https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-contrib/gcloud-java-nio - FileSystemProvider for Java NIO to access GCS transparently. + FileSystemProvider for Java NIO to access Google Cloud Storage transparently. com.google.cloud diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java index fa21c5f8cdd2..efa086d7db80 100644 --- a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java +++ b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java @@ -55,7 +55,7 @@ public abstract class CloudStorageConfiguration { public abstract boolean usePseudoDirectories(); /** - * Returns block size (in bytes) used when talking to the GCS HTTP server. + * Returns block size (in bytes) used when talking to the Google Cloud Storage HTTP server. */ public abstract int blockSize(); diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystem.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystem.java index ce12ff3eee97..60a39fb5a817 100644 --- a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystem.java +++ b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystem.java @@ -97,9 +97,10 @@ public static CloudStorageFileSystem forBucket(String bucket, CloudStorageConfig /** * Returns Google Cloud Storage {@link FileSystem} object for {@code bucket}. * - *

GCS file system objects are basically free. You can create as many as you want, even if you - * have multiple instances for the same bucket. There's no actual system resources associated - * with this object. Therefore calling {@link #close()} on the returned value is optional. + *

Google Cloud Storage file system objects are basically free. You can create as many as you + * want, even if you have multiple instances for the same bucket. There's no actual system + * resources associated with this object. Therefore calling {@link #close()} on the returned value + * is optional. * *

Note: It is also possible to instantiate this class via Java's * {@code FileSystems.getFileSystem(URI.create("gs://bucket"))}. We discourage you @@ -151,7 +152,7 @@ public CloudStorageConfiguration config() { public CloudStoragePath getPath(String first, String... more) { checkArgument( !first.startsWith(URI_SCHEME + ":"), - "GCS FileSystem.getPath() must not have schema and bucket name: %s", + "Google Cloud Storage FileSystem.getPath() must not have schema and bucket name: %s", first); return CloudStoragePath.getPath(this, first, more); } @@ -196,7 +197,8 @@ public Iterable getRootDirectories() { } /** - * Returns nothing because GCS doesn't have disk partitions of limited size, or anything similar. + * Returns nothing because Google Cloud Storage doesn't have disk partitions of limited size, or + * anything similar. */ @Override public Iterable getFileStores() { diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystemProvider.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystemProvider.java index cc8bd5cf0bbf..624c410ddb5c 100644 --- a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystemProvider.java +++ b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystemProvider.java @@ -77,7 +77,8 @@ * *

Note: This class should never be used directly. This class is instantiated by the * service loader and called through a standardized API, e.g. {@link java.nio.file.Files}. However - * the javadocs in this class serve as useful documentation for the behavior of the GCS NIO library. + * the javadocs in this class serve as useful documentation for the behavior of the Google Cloud + * Storage NIO library. */ @Singleton @ThreadSafe @@ -481,7 +482,7 @@ public boolean isSameFile(Path path, Path path2) { } /** - * Always returns {@code false}, because GCS doesn't support hidden files. + * Always returns {@code false}, because Google Cloud Storage doesn't support hidden files. */ @Override public boolean isHidden(Path path) { @@ -561,7 +562,7 @@ public V getFileAttributeView( } /** - * Does nothing since GCS uses fake directories. + * Does nothing since Google Cloud Storage uses fake directories. */ @Override public void createDirectory(Path dir, FileAttribute... attrs) { diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOption.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOption.java index 266bd67c2c84..d4921e10a0ec 100644 --- a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOption.java +++ b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOption.java @@ -25,17 +25,17 @@ public interface CloudStorageOption { /** - * Interface for GCS options that can be specified when opening files. + * Interface for Google Cloud Storage options that can be specified when opening files. */ interface Open extends CloudStorageOption, OpenOption {} /** - * Interface for GCS options that can be specified when copying files. + * Interface for Google Cloud Storage options that can be specified when copying files. */ interface Copy extends CloudStorageOption, CopyOption {} /** - * Interface for GCS options that can be specified when opening or copying files. + * Interface for Google Cloud Storage options that can be specified when opening or copying files. */ interface OpenCopy extends Open, Copy {} } diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOptions.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOptions.java index 6ee762eff0ea..74293b7a79f2 100644 --- a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOptions.java +++ b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOptions.java @@ -83,7 +83,7 @@ public static CloudStorageOption.OpenCopy withUserMetadata(String key, String va } /** - * Sets the block size (in bytes) when talking to the GCS server. + * Sets the block size (in bytes) when talking to the Google Cloud Storage server. * *

The default is {@value CloudStorageFileSystem#BLOCK_SIZE_DEFAULT}. */ diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStoragePath.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStoragePath.java index fdb407ba1852..7c9154b20d93 100644 --- a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStoragePath.java +++ b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStoragePath.java @@ -139,7 +139,8 @@ private UnixPath toRealPathInternal(boolean errorCheck) { objectName = objectName.removeBeginningSeparator(); } checkArgument( - !errorCheck || !objectName.isEmpty(), "I/O not allowed on empty GCS object names."); + !errorCheck || !objectName.isEmpty(), + "I/O not allowed on empty Google Cloud Storage object names."); return objectName; } @@ -256,8 +257,8 @@ public WatchKey register(WatchService watcher, Kind... events) { } /** - * Throws {@link UnsupportedOperationException} because GCS files are not backed by the local file - * system. + * Throws {@link UnsupportedOperationException} because Google Cloud Storage files are not backed + * by the local file system. */ @Override public File toFile() { diff --git a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageUtil.java b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageUtil.java index 78a602e407b3..14b1921a7b9e 100644 --- a/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageUtil.java +++ b/gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageUtil.java @@ -36,9 +36,9 @@ static void checkBucket(String bucket) { "Invalid bucket name: '" + bucket + "'. " - + "GCS bucket names must contain only lowercase letters, numbers, dashes (-), " - + "underscores (_), and dots (.). Bucket names must start and end with a number or a " - + "letter. See the following page for more details: " + + "Google Cloud Storage bucket names must contain only lowercase letters, numbers, " + + "dashes (-), underscores (_), and dots (.). Bucket names must start and end with a " + + "number or a letter. See the following page for more details: " + "https://developers.google.com/storage/docs/bucketnaming"); } diff --git a/gcloud-java-contrib/gcloud-java-nio/src/test/java/com/google/cloud/storage/contrib/nio/it/ITGcsNio.java b/gcloud-java-contrib/gcloud-java-nio/src/test/java/com/google/cloud/storage/contrib/nio/it/ITGcsNio.java index 949d98051eea..dad6fc35ba2d 100644 --- a/gcloud-java-contrib/gcloud-java-nio/src/test/java/com/google/cloud/storage/contrib/nio/it/ITGcsNio.java +++ b/gcloud-java-contrib/gcloud-java-nio/src/test/java/com/google/cloud/storage/contrib/nio/it/ITGcsNio.java @@ -58,21 +58,20 @@ import java.util.logging.Logger; /** - * Integration test for gcloud-nio. + * Integration test for gcloud-java-nio. * - *

This test actually talks to GCS (you need an account) and tests both reading and writing. You - * *must* set the {@code GOOGLE_APPLICATION_CREDENTIALS} environment variable for this test to work. - * It must contain the name of a local file that contains your Service Account JSON Key. + *

This test actually talks to Google Cloud Storage (you need an account) and tests both reading + * and writing. You *must* set the {@code GOOGLE_APPLICATION_CREDENTIALS} environment variable for + * this test to work. It must contain the name of a local file that contains your Service Account + * JSON Key. * - *

The instructions for how to get the Service Account JSON Key are - * at https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts + *

See + * Service Accounts for instructions on how to get the Service Account JSON Key. * - *

The short version is this: go to cloud.google.com/console, - * select your project, search for "API manager", click "Credentials", - * click "create credentials/service account key", new service account, - * JSON. The contents of the file that's sent to your browsers is your + *

The short version is this: go to cloud.google.com/console, select your project, search for + * "API manager", click "Credentials", click "create credentials/service account key", new service + * account, JSON. The contents of the file that's sent to your browsers is your * "Service Account JSON Key". - * */ @RunWith(JUnit4.class) public class ITGcsNio { diff --git a/gcloud-java-examples/README.md b/gcloud-java-examples/README.md index 50ac44e11c47..2e5d66a6a7ff 100644 --- a/gcloud-java-examples/README.md +++ b/gcloud-java-examples/README.md @@ -46,9 +46,9 @@ To run examples from your command line: Before running the example, go to the [Google Developers Console][developers-console] to ensure that BigQuery API is enabled. You can upload a CSV file `my_csv_file` to the `my_bucket` bucket - (replace `my_csv_file` and `my_bucket` with actual file and bucket names) using the GCS - [web browser](https://console.developers.google.com/storage/browser). The CSV file will be used to - load data into a BigQuery table and should look something like: + (replace `my_csv_file` and `my_bucket` with actual file and bucket names) using the Google Cloud + Storage [web browser](https://console.developers.google.com/storage/browser). The CSV file will + be used to load data into a BigQuery table and should look something like: ```csv value1 value2 @@ -143,8 +143,9 @@ To run examples from your command line: target/appassembler/bin/Stat gs://mybucket/myfile.txt ``` - The sample doesn't have anything special about GCS in it, it just opens files via the NIO API. - It lists gcloud-java-nio as a dependency, and that enables it to interpret `gs://` paths. + The sample doesn't have anything special about Google Cloud Storage in it, it just opens files + via the NIO API. It lists gcloud-java-nio as a dependency, and that enables it to interpret + `gs://` paths. Troubleshooting --------------- diff --git a/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/Stat.java b/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/Stat.java index 19933204705b..35a1a2ae7c7f 100644 --- a/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/Stat.java +++ b/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/Stat.java @@ -31,9 +31,9 @@ * *

It's meant to be used to test GCloud's integration with Java NIO. * - *

You can either use the '--check' argument to see whether GCS is enabled, - * or you can directly pass in a GCS file name to use. In that case you have to - * be logged in (using e.g. the gcloud auth command). + *

You can either use the '--check' argument to see whether Google Cloud Storage is enabled, or + * you can directly pass in a Google Cloud Storage file name to use. In that case you have to be + * logged in (using e.g. the gcloud auth command). * *

See the * @@ -92,13 +92,13 @@ private static void help() { " to list the filesystem providers.", "", " * --check", - " to double-check the GCS provider is installed.", + " to double-check the Google Cloud Storage provider is installed.", "", "The purpose of this tool is to demonstrate that the gcloud NIO filesystem provider", "can add Google Cloud Storage support to programs not explicitly designed for it.", "", "This tool normally knows nothing of Google Cloud Storage. If you pass it --check", - "or a GCS file name (e.g. gs://mybucket/myfile), it will show an error.", + "or a Google Cloud Storage file name (e.g. gs://mybucket/myfile), it will show an error.", "However, by just adding the gcloud-nio jar as a dependency and recompiling, this tool is", "made aware of gs:// paths and can access files on the cloud.", "", diff --git a/gcloud-java-storage/src/main/java/com/google/cloud/storage/testing/package-info.java b/gcloud-java-storage/src/main/java/com/google/cloud/storage/testing/package-info.java index 3fbf95fb29f7..89769c39ba42 100644 --- a/gcloud-java-storage/src/main/java/com/google/cloud/storage/testing/package-info.java +++ b/gcloud-java-storage/src/main/java/com/google/cloud/storage/testing/package-info.java @@ -15,9 +15,7 @@ */ /** - * Two testing helpers for Google Cloud Storage. - * - * RemoteGcsHelper helps with testing on the actual cloud. + * A testing helper for Google Cloud Storage. * *

A simple usage example: * @@ -29,26 +27,6 @@ * storage.create(BucketInfo.of(bucket)); * } * - *

After the test: - * 

 {@code
- * RemoteStorageHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
- * }
- * - * LocalGcsHelper helps with testing on an in-memory filesystem (this is best for unit tests). - * Note that this filesystem isn't a complete implementation. In particular, it is not thread-safe. - * - *

A simple usage example: - * - * 

- * CloudStorageFileSystemProvider.setGCloudOptions(LocalGcsHelper.options());
- * Path path = Paths.get(URI.create("gs://bucket/wednesday"));
- * thrown.expect(NoSuchFileException.class);
- * Files.newByteChannel(path);
- *
- * - *

The first line ensures that the test uses the in-memory GCS instead of the real one - * (note that you have to set the cloud options before the first usage of the gs:// prefix). - * * @see * gcloud-java tools for testing */