From d36c958ac3ae75f38376f0e3af0c50a48ab48212 Mon Sep 17 00:00:00 2001 From: JP Martin Date: Fri, 1 Apr 2016 15:41:49 -0700 Subject: [PATCH 1/8] Split off the "normal case" example from the "legacy case" one. (and create a "normal case" example, first) --- gcloud-java-contrib/README.md | 6 + .../gcloud-java-nio-example/README.md | 38 ++++++ .../gcloud-java-nio-example/pom.xml | 92 +++++++++++++++ .../com/google/gcloud/nio/example/Stat.java | 108 ++++++++++++++++++ gcloud-java-contrib/pom.xml | 1 + .../com/google/gcloud/datastore/Query.java | 2 +- gcloud-java-examples/README.md | 24 ++-- gcloud-java-examples/pom.xml | 5 + .../examples/bigquery/BigQueryExample.java | 2 +- .../examples/datastore/DatastoreExample.java | 2 +- .../com/google/gcloud/examples/nio/Stat.java | 9 +- .../ResourceManagerExample.java | 2 +- .../examples/storage/StorageExample.java | 2 +- .../resourcemanager/ResourceManager.java | 2 +- 14 files changed, 271 insertions(+), 24 deletions(-) create mode 100644 gcloud-java-contrib/gcloud-java-nio-example/README.md create mode 100644 gcloud-java-contrib/gcloud-java-nio-example/pom.xml create mode 100644 gcloud-java-contrib/gcloud-java-nio-example/src/main/java/com/google/gcloud/nio/example/Stat.java diff --git a/gcloud-java-contrib/README.md b/gcloud-java-contrib/README.md index b8bef6eb977e..60a194e7234c 100644 --- a/gcloud-java-contrib/README.md +++ b/gcloud-java-contrib/README.md @@ -7,6 +7,12 @@ Contents -------- * [gcloud-java-nio](./gcloud-java-nio/): NIO Filesystem Provider for Google Cloud Storage. + * [gcloud-java-nio-example](./gcloud-java-nio-example/): How to add GCS NIO after the fact. + +See also +-------- + + * [gcloud-java-examples](../gcloud-java-examples) for an example of how to use NIO normally. Contributing ------------ diff --git a/gcloud-java-contrib/gcloud-java-nio-example/README.md b/gcloud-java-contrib/gcloud-java-nio-example/README.md new file mode 100644 index 000000000000..4d11fd7e1959 --- /dev/null +++ b/gcloud-java-contrib/gcloud-java-nio-example/README.md @@ -0,0 +1,38 @@ +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 but that you cannot 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 +this in the [gcloud-java-examples](../../gcloud-java-examples) project. + +To run this example: + +1. Before running the example, go to the [Google Developers Console][developers-console] to ensure that Google Cloud Storage API is enabled and that you have a bucket with a file in it. + +2. Log in using gcloud SDK (`gcloud auth login` in command line) + +3. Compile the JAR with: + ``` + mvn package -DskipTests -Dmaven.javadoc.skip=true -Dmaven.source.skip=true + ``` + +4. Run the sample with: + + ``` + java -cp gcloud-java-contrib/gcloud-java-nio/target/gcloud-java-nio-0.1.6-SNAPSHOT-shaded.jar:gcloud-java-contrib/gcloud-java-nio-example/target/gcloud-java-nio-example-0.1.6-SNAPSHOT.jar com.google.gcloud.nio.example.Stat --check + ``` + Or, if you have a file in `gs://mybucket/myfile.txt`, you can run: + ``` + java -cp gcloud-java-contrib/gcloud-java-nio/target/gcloud-java-nio-0.1.6-SNAPSHOT-shaded.jar:gcloud-java-contrib/gcloud-java-nio-example/target/gcloud-java-nio-example-0.1.6-SNAPSHOT.jar com.google.gcloud.nio.example.Stat gs://mybucket/myfile.txt + ``` + +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. + +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. diff --git a/gcloud-java-contrib/gcloud-java-nio-example/pom.xml b/gcloud-java-contrib/gcloud-java-nio-example/pom.xml new file mode 100644 index 000000000000..93f2b0e70613 --- /dev/null +++ b/gcloud-java-contrib/gcloud-java-nio-example/pom.xml @@ -0,0 +1,92 @@ + + + 4.0.0 + com.google.gcloud + gcloud-java-nio-example + jar + GCloud Java NIO example + + Demonstrates how to use the gcloud-java-nio jar to add GCS functionality after the fact. + + + com.google.gcloud + gcloud-java-contrib + 0.1.6-SNAPSHOT + + + nio + + + + ${project.groupId} + gcloud-java-storage + ${project.version} + + + com.google.guava + guava + 19.0 + + + com.google.code.findbugs + jsr305 + 2.0.1 + + + javax.inject + javax.inject + 1 + + + com.google.auto.service + auto-service + 1.0-rc2 + provided + + + com.google.auto.value + auto-value + 1.1 + provided + + + junit + junit + 4.12 + test + + + com.google.guava + guava-testlib + 19.0 + test + + + com.google.truth + truth + 0.27 + test + + + org.mockito + mockito-core + 1.9.5 + + + org.apache.maven.plugins + maven-assembly-plugin + 2.5.4 + + + + + + org.codehaus.mojo + exec-maven-plugin + + false + + + + + diff --git a/gcloud-java-contrib/gcloud-java-nio-example/src/main/java/com/google/gcloud/nio/example/Stat.java b/gcloud-java-contrib/gcloud-java-nio-example/src/main/java/com/google/gcloud/nio/example/Stat.java new file mode 100644 index 000000000000..c702c3e9501c --- /dev/null +++ b/gcloud-java-contrib/gcloud-java-nio-example/src/main/java/com/google/gcloud/nio/example/Stat.java @@ -0,0 +1,108 @@ +package com.google.gcloud.nio.example; + +import java.io.IOException; +import java.net.URI; +import java.nio.file.FileSystem; +import java.nio.file.FileSystems; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.nio.file.spi.FileSystemProvider; + +/** + * Stat is a super-simple program that just displays the size of the file + * passed as argument. + * + *

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). + * + *

See the README for a command line to run this example. + * + *

In short, This version (in gcloud-java-nio-example) is in a package that does not list + * gcloud-java-nio as a dependency, so you have to add the gcloud-java-nio jar to the classpath. + + */ +public class Stat { + + /** + * See the class documentation. + */ + public static void main(String[] args) throws IOException { + if (args.length == 0 || args[0].equals("--help")) { + help(); + return; + } + if (args[0].equals("--list")) { + listFilesystems(); + return; + } + if (args[0].equals("--check")) { + checkGcs(); + return; + } + for (String a : args) { + statFile(a); + } + } + + /** + * Print the length of the indicated file. + * + *

This uses the normal Java NIO Api, so it can take advantage of any installed + * NIO Filesystem provider without any extra effort. + */ + private static void statFile(String fname) { + try { + Path path = Paths.get(new URI(fname)); + long size = Files.size(path); + System.out.println(fname + ": " + size + " bytes."); + } catch (Exception ex) { + System.out.println(fname + ": " + ex.toString()); + } + } + + private static void help() { + String[] help = + {"The arguments can be one of:", + " * ", + " to display the length of that file.", + "", + " * --list", + " to list the filesystem providers.", + "", + " * --check", + " to double-check the GCS 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.", + "However, by just adding the gcloud-nio jar in your classpath, this tool is made", + "aware of gs:// paths and can access files on the cloud.", + "", + "The gcloud NIO filesystem provider can similarly enable existing Java 7 programs", + "to read and write cloud files, even if they have no special built-in cloud support." + }; + for (String s : help) { + System.out.println(s); + } + } + + private static void listFilesystems() { + System.out.println("Installed filesystem providers:"); + for (FileSystemProvider p : FileSystemProvider.installedProviders()) { + System.out.println(" " + p.getScheme()); + } + } + + private static void checkGcs() { + FileSystem fs = FileSystems.getFileSystem(URI.create("gs://domain-registry-alpha")); + System.out.println("Success! We can instantiate a gs:// filesystem."); + System.out.println("isOpen: " + fs.isOpen()); + System.out.println("isReadOnly: " + fs.isReadOnly()); + } +} diff --git a/gcloud-java-contrib/pom.xml b/gcloud-java-contrib/pom.xml index 4c8eff8cab0f..47e321793e81 100644 --- a/gcloud-java-contrib/pom.xml +++ b/gcloud-java-contrib/pom.xml @@ -17,6 +17,7 @@ gcloud-java-nio + gcloud-java-nio-example diff --git a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/Query.java b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/Query.java index 50591a87a6a4..a9381a215bb0 100644 --- a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/Query.java +++ b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/Query.java @@ -30,7 +30,7 @@ /** * A Google Cloud Datastore query. - * For usage examples see {@link GqlQuery} and {@link StructuredQuery}. + * For usage example see {@link GqlQuery} and {@link StructuredQuery}. * * Note that queries require proper indexing. See * diff --git a/gcloud-java-examples/README.md b/gcloud-java-examples/README.md index 29872245a19d..ae6c35b7aa49 100644 --- a/gcloud-java-examples/README.md +++ b/gcloud-java-examples/README.md @@ -24,7 +24,7 @@ If you are using Maven, add this to your pom.xml file ``` If you are using Gradle, add this to your dependencies ```Groovy -compile 'com.google.gcloud:gcloud-java-examples:0.1.5' +compile example ``` If you are using SBT, add this to your dependencies ```Scala @@ -89,28 +89,22 @@ To run examples from your command line: mvn exec:java -Dexec.mainClass="com.google.gcloud.examples.storage.StorageExample" -Dexec.args="download test.txt" mvn exec:java -Dexec.mainClass="com.google.gcloud.examples.storage.StorageExample" -Dexec.args="delete test.txt" ``` + * Here's an example run of `Stat`, illustrating the use of the gcloud-java-nio jar. - Before running the example, go to the [Google Developers Console][developers-console] to ensure that Google Cloud Storage API is enabled and that you have a bucket with a file in it. - Compile the JAR with: - ``` - mvn package -DskipTests -Dmaven.javadoc.skip=true -Dmaven.source.skip=true + Before running the example, go to the [Google Developers Console][developers-console] to ensure that Google Cloud Storage API is enabled and that you have a bucket with a file in it. + Run the sample with: ``` - Then run the sample with: - ``` - java -cp gcloud-java-contrib/gcloud-java-nio/target/gcloud-java-nio-0.1.6-SNAPSHOT-shaded.jar:gcloud-java-examples/target/gcloud-java-examples-0.1.6-SNAPSHOT.jar com.google.gcloud.examples.nio.Stat --check + mvn exec:java -Dexec.mainClass="com.google.gcloud.examples.nio.Stat" -Dexec.args="--check" + ``` Or, if you have a file in `gs://mybucket/myfile.txt`, you can run: ``` - java -cp gcloud-java-contrib/gcloud-java-nio/target/gcloud-java-nio-0.1.6-SNAPSHOT-shaded.jar:gcloud-java-examples/target/gcloud-java-examples-0.1.6-SNAPSHOT.jar com.google.gcloud.examples.nio.Stat gs://mybucket/myfile.txt + mvn exec:java -Dexec.mainClass="com.google.gcloud.examples.nio.Stat" -Dexec.args="gs://mybucket/myfile.txt" ``` - 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. - 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. + 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. Troubleshooting --------------- diff --git a/gcloud-java-examples/pom.xml b/gcloud-java-examples/pom.xml index 74cba268e2bd..076db9b5c3ab 100644 --- a/gcloud-java-examples/pom.xml +++ b/gcloud-java-examples/pom.xml @@ -21,6 +21,11 @@ gcloud-java ${project.version} + + ${project.groupId} + gcloud-java-nio + ${project.version} + org.apache.maven.plugins maven-assembly-plugin diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/BigQueryExample.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/BigQueryExample.java index fe27ee3cf63b..422d1ef88450 100644 --- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/BigQueryExample.java +++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/BigQueryExample.java @@ -63,7 +63,7 @@ *

  • login using gcloud SDK - {@code gcloud auth login}.
    • *
  • compile using maven - {@code mvn compile}
    • *
  • run using maven - - * 
    {@code mvn exec:java -Dexec.mainClass="com.google.gcloud.examples.bigquery.BigQueryExample"
+ * 
    {@code mvn exec:java -Dexec.mainClass="com.google.gcloud.example.bigquery.BigQueryExample"
  *  -Dexec.args="[]
  *  list datasets |
  *  list tables  |
diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/datastore/DatastoreExample.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/datastore/DatastoreExample.java
index cc4331734200..715a7c6d8618 100644
--- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/datastore/DatastoreExample.java
+++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/datastore/DatastoreExample.java
@@ -44,7 +44,7 @@
  * 
  • login using gcloud SDK - {@code gcloud auth login}.
    • 
  * 
  • compile using maven - {@code mvn compile}
    • 
  * 
  • run using maven - {@code mvn exec:java
- * -Dexec.mainClass="com.google.gcloud.examples.datastore.DatastoreExample"
+ * -Dexec.mainClass="com.google.gcloud.example.datastore.DatastoreExample"
  * -Dexec.args="[projectId] [user] [delete|display|add comment]"}
    • 
  * 
  */
diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/nio/Stat.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/nio/Stat.java
index 6a0349701804..054657d717ef 100644
--- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/nio/Stat.java
+++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/nio/Stat.java
@@ -20,6 +20,9 @@
  * be logged in (using e.g. the gcloud auth command).
  *
  * 
    See the README for a command line to run this example.
+ *
+ * 
    In short, this version (in gcloud-java-examples) is in a package that lists gcloud-java-nio
+ * as a dependency, so it will work directly without having to do any special work.
  */
 public class Stat {
 
@@ -77,8 +80,8 @@ private static void help() {
          "",
          "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.",
-         "However, by just adding the gcloud-nio jar in your classpath, this tool is made",
-         "aware of gs:// paths and can access files on the cloud.",
+         "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.",
          "",
          "The gcloud NIO filesystem provider can similarly enable existing Java 7 programs",
          "to read and write cloud files, even if they have no special built-in cloud support."
@@ -97,7 +100,7 @@ private static void listFilesystems() {
 
   private static void checkGcs() {
     FileSystem fs = FileSystems.getFileSystem(URI.create("gs://domain-registry-alpha"));
-    System.out.println("We seem to be able to instantiate a gs:// filesystem.");
+    System.out.println("Success! We can instantiate a gs:// filesystem.");
     System.out.println("isOpen: " + fs.isOpen());
     System.out.println("isReadOnly: " + fs.isReadOnly());
   }
diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/resourcemanager/ResourceManagerExample.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/resourcemanager/ResourceManagerExample.java
index 349c0eebe73d..315da0cf6e97 100644
--- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/resourcemanager/ResourceManagerExample.java
+++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/resourcemanager/ResourceManagerExample.java
@@ -36,7 +36,7 @@
  * 
  • login using gcloud SDK - {@code gcloud auth login}.
    • 
  * 
  • compile using maven - {@code mvn compile}
    • 
  * 
  • run using maven - {@code mvn exec:java
- * -Dexec.mainClass="com.google.gcloud.examples.resourcemanager.ResourceManagerExample"
+ * -Dexec.mainClass="com.google.gcloud.example.resourcemanager.ResourceManagerExample"
  * -Dexec.args="[list | [create | delete | get] projectId]"}
    • 
  * 
  */
diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/StorageExample.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/StorageExample.java
index a7260134202d..562044a2328d 100644
--- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/StorageExample.java
+++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/StorageExample.java
@@ -65,7 +65,7 @@
  * 
  • login using gcloud SDK - {@code gcloud auth login}.
    • 
  * 
  • compile using maven - {@code mvn compile}
    • 
  * 
  • run using maven -
- * 
    {@code mvn exec:java -Dexec.mainClass="com.google.gcloud.examples.storage.StorageExample"
+ * 
    {@code mvn exec:java -Dexec.mainClass="com.google.gcloud.example.storage.StorageExample"
  *  -Dexec.args="[]
  *  list [] |
  *  info [ []] |
diff --git a/gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/ResourceManager.java b/gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/ResourceManager.java
index a463937f875c..917c4e8580a8 100644
--- a/gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/ResourceManager.java
+++ b/gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/ResourceManager.java
@@ -116,7 +116,7 @@ private ProjectListOption(ResourceManagerRpc.Option option, Object value) {
      * 
    You can specify multiple filters by adding a space between each filter. Multiple filters
      * are composed using "and".
      *
-     * 
    Some examples of filters:
+     * 
    Some example of filters:
      *