diff --git a/google-cloud-nio-examples/README.md b/google-cloud-nio-examples/README.md deleted file mode 100644 index a8161bc64a..0000000000 --- a/google-cloud-nio-examples/README.md +++ /dev/null @@ -1,47 +0,0 @@ -Example of adding the Google Cloud Storage NIO Provider to a legacy jar -======================================================================= - -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 google-cloud-nio. You can see examples of -this in the [google-cloud-examples](../../../google-cloud-examples) project, -[under nio](../../../google-cloud-examples/src/main/java/com/google/cloud/examples/nio). - -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. - -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: - -[//]: # ({x-version-update-start:google-cloud-nio:current}) - ``` - java -cp google-cloud-clients/google-cloud-contrib/google-cloud-nio/target/google-cloud-nio-0.120.1-alpha-SNAPSHOT.jar:google-cloud-clients/google-cloud-contrib/google-cloud-nio-examples/target/google-cloud-nio-examples-0.120.1-alpha-SNAPSHOT.jar com.google.cloud.nio.examples.ListFilesystems - ``` - - Notice that it lists Google Cloud Storage, which it wouldn't if you ran it without the NIO jar: - ``` - java -cp google-cloud-clients/google-cloud-contrib/google-cloud-nio-examples/target/google-cloud-nio-examples-0.120.1-alpha-SNAPSHOT.jar com.google.cloud.nio.examples.ListFilesystems - ``` -[//]: # ({x-version-update-end}) - -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 google-cloud-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 google-cloud-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. - -[developers-console]:https://console.developers.google.com/ diff --git a/google-cloud-nio-retrofit/README.md b/google-cloud-nio-retrofit/README.md new file mode 100644 index 0000000000..cf32acd42d --- /dev/null +++ b/google-cloud-nio-retrofit/README.md @@ -0,0 +1,53 @@ +Example of adding the Google Cloud Storage NIO Provider to a legacy jar +======================================================================= + +This project shows how to add (retrofit) 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 google-cloud-nio. You can see examples of +this in the +[google-cloud-examples](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples) +project, +[under nio](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/nio). + +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. + +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: + +[//]: # ({x-version-update-start:google-cloud-nio:current}) + ``` + java -cp google-cloud-nio/target/google-cloud-nio-0.120.1-alpha-SNAPSHOT-shaded.jar:google-cloud-nio-retrofit/target/google-cloud-nio-retrofit-0.120.1-alpha-SNAPSHOT.jar com.google.cloud.nio.retrofit.ListFilesystems + ``` + + Notice that it lists Google Cloud Storage ("gs"), which it wouldn't if you ran it without the NIO jar: + ``` + java -cp google-cloud-nio-retrofit/target/google-cloud-nio-retrofit-0.120.1-alpha-SNAPSHOT.jar com.google.cloud.nio.retrofit.ListFilesystems + ``` +[//]: # ({x-version-update-end}) + +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. We use the NIO "fat shaded" jar for this purpose as it +also includes the dependencies for google-cloud-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 google-cloud-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. + +[developers-console]:https://console.developers.google.com/ diff --git a/google-cloud-nio-examples/pom.xml b/google-cloud-nio-retrofit/pom.xml similarity index 90% rename from google-cloud-nio-examples/pom.xml rename to google-cloud-nio-retrofit/pom.xml index e798a82c2e..3d19444c76 100644 --- a/google-cloud-nio-examples/pom.xml +++ b/google-cloud-nio-retrofit/pom.xml @@ -1,7 +1,7 @@ 4.0.0 - google-cloud-nio-examples + google-cloud-nio-retrofit 0.120.1-alpha-SNAPSHOT jar Google Cloud NIO Examples @@ -15,7 +15,7 @@ 0.120.1-alpha-SNAPSHOT - google-cloud-nio-examples + google-cloud-nio-retrofit diff --git a/google-cloud-nio-examples/src/main/java/com/google/cloud/nio/examples/ListFilesystems.java b/google-cloud-nio-retrofit/src/main/java/com/google/cloud/nio/retrofit/ListFilesystems.java similarity index 70% rename from google-cloud-nio-examples/src/main/java/com/google/cloud/nio/examples/ListFilesystems.java rename to google-cloud-nio-retrofit/src/main/java/com/google/cloud/nio/retrofit/ListFilesystems.java index 932ed5a3e1..831350bf8d 100644 --- a/google-cloud-nio-examples/src/main/java/com/google/cloud/nio/examples/ListFilesystems.java +++ b/google-cloud-nio-retrofit/src/main/java/com/google/cloud/nio/retrofit/ListFilesystems.java @@ -14,12 +14,20 @@ * limitations under the License. */ -package com.google.cloud.nio.examples; +package com.google.cloud.nio.retrofit; import java.io.IOException; import java.nio.file.spi.FileSystemProvider; -/** ListFilesystems is a super-simple program that lists the available NIO filesystems. */ +/** + * ListFilesystems is a simple program that lists the available NIO filesystems. + * + *

Note that the code here doesn't do anything special to link in the google-cloud-nio code. It + * doesn't use any of its methods. + * + *

The README explains how, by just adding the google-cloud-nio JAR in the classpath, this + * program will magically gain the ability to read files on Google Cloud Storage. + */ public class ListFilesystems { /** See the class documentation. */ diff --git a/pom.xml b/pom.xml index 30682aa4b0..3e10051e59 100644 --- a/pom.xml +++ b/pom.xml @@ -168,6 +168,7 @@ google-cloud-nio + google-cloud-nio-retrofit @@ -243,7 +244,7 @@ include-samples - google-cloud-nio-examples + google-cloud-nio-retrofit