Refactor nio's package-info and add snippets

Author: mziccard

gcloud-java-contrib/gcloud-java-nio/src/main/java/com/google/cloud/storage/contrib/nio/package-info.java

@@ -22,43 +22,55 @@
  *
  * <h3>How It Works</h3>
  *
- * The simplest way to get started is with {@code Paths} and {@code Files}:<pre>   {@code
- *
+ * The simplest way to get started is with {@code Paths} and {@code Files}:
+ * <pre>{@code
  *   Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
- *   List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);}</pre>
+ *   List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
+ * }</pre>
+ *
+ * <p>For the complete source code see
+ * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/ReadAllLines.java">
+ * ReadAllLines.java</a>.
  *
  * <p>If you want to configure the bucket per-environment, it might make more sense to use the
  * {@code FileSystem} API:
- * <pre>
- *   class Foo {
- *     static String bucket = System.getProperty(...);
- *     static FileSystem fs = FileSystems.getFileSystem(URI.create("gs://" + bucket));
- *     void bar() {
- *       byte[] data = "hello world".getBytes(StandardCharsets.UTF_8);
- *       Path path = fs.getPath("/object");
- *       Files.write(path, data);
- *       data = Files.readBytes(path);
- *     }
- *     void doodle() {
- *       Path path = fs.getPath("/path/to/doodle.csv");
- *       List&lt;String&gt; lines = Files.readAllLines(path, StandardCharsets.UTF_8);
- *     }
- *   }</pre>
- *
- * <p>You can also use InputStream and OutputStream for streaming:
+ * <pre>{@code
+ *   FileSystem fs = FileSystems.getFileSystem(URI.create("gs://bucket"));
+ *   byte[] data = "hello world".getBytes(StandardCharsets.UTF_8);
+ *   Path path = fs.getPath("/object");
+ *   Files.write(path, data);
+ *   List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
+ * }</pre>
+ *
+ * <p>For the complete source code see
+ * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/GetFileSystem.java">
+ * GetFileSystem.java</a>.
+ *
+ * <p>You can also use {@code InputStream} and {@code OutputStream} for streaming:
  * <pre>
  *   Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
- *   try (InputStream input = Files.openInputStream(path)) {
- *     // ...
- *   }</pre>
+ *   try (InputStream input = Files.newInputStream(path)) {
+ *     // use input stream
+ *   }
+ * </pre>
+ *
+ * <p>For the complete source code see
+ * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/CreateInputStream.java">
+ * CreateInputStream.java</a>.
  *
  * <p>You can set various attributes using
  * {@link com.google.cloud.storage.contrib.nio.CloudStorageOptions CloudStorageOptions} static
  * helpers:
  * <pre>
- *   Files.write(csvPath, csvLines, StandardCharsets.UTF_8,
- *       withMimeType(MediaType.CSV_UTF8),
- *       withoutCaching());</pre>
+ *   Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
+ *   Files.write(path, csvLines, StandardCharsets.UTF_8,
+ *       withMimeType("text/csv; charset=UTF-8"),
+ *       withoutCaching());
+ * </pre>
+ *
+ * <p>For the complete source code see
+ * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/WriteFileWithAttributes.java">
+ * WriteFileWithAttributes.java</a>.
  *
  * <p><b>NOTE:</b> Cloud Storage uses a flat namespace and therefore doesn't support real
  * directories. So this library supports what's known as "pseudo-directories". Any path that
@@ -67,32 +79,22 @@
  * would with the normal UNIX file system implementation. You can disable this feature with
  * {@link com.google.cloud.storage.contrib.nio.CloudStorageConfiguration#usePseudoDirectories()}.
  *
- * <h3>Unit Testing</h3>
- *
- * <p>Here's a simple unit test:<pre>
- *
- *   class MyTest {
- *     {@literal @}Rule
- *     public final AppEngineRule appEngine = AppEngineRule.builder().build();
- *
- *     {@literal @}Test
- *     public test_fileWrite() throws Exception {
- *       Path path = Paths.get(URI.create("gs://bucket/traditional"));
- *       Files.write(path, "eyebrow".getBytes(StandardCharsets.US_ASCII));
- *       assertEquals("eyebrow", new String(Files.readBytes(path), StandardCharsets.US_ASCII));
- *     }
- *   }</pre>
- *
  * <h3>Non-SPI Interface</h3>
  *
  * <p>If you don't want to rely on Java SPI, which requires a META-INF file in your jar generated by
- * Google Auto, you can instantiate this file system directly as follows:<pre>   {@code
+ * Google Auto, you can instantiate this file system directly as follows:
  *
- *   CloudStorageFileSystem fs = CloudStorageFileSystemProvider.forBucket("bucket");
+ * <pre>
+ *   CloudStorageFileSystem fs = CloudStorageFileSystem.forBucket("bucket");
  *   byte[] data = "hello world".getBytes(StandardCharsets.UTF_8);
  *   Path path = fs.getPath("/object");
  *   Files.write(path, data);
- *   data = Files.readBytes(path);}</pre>
+ *   data = Files.readAllBytes(path);
+ * </pre>
+ *
+ * <p>For the complete source code see
+ * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/CreateCloudStorageFileSystem.java">
+ * CreateCloudStorageFileSystem.java</a>.
  */
 @javax.annotation.ParametersAreNonnullByDefault
 package com.google.cloud.storage.contrib.nio;

gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/CreateCloudStorageFileSystem.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed 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 com.google.cloud.examples.nio.snippets;
+
+import com.google.cloud.storage.contrib.nio.CloudStorageFileSystem;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * A snippet for Google Cloud Storage NIO that shows how to create a {@link CloudStorageFileSystem}
+ * for a bucket. The snippet also shows how to create a file, given the file system.
+ */
+public class CreateCloudStorageFileSystem {
+
+  public static void main(String... args) throws IOException {
+    // Create a file system for the bucket
+    CloudStorageFileSystem fs = CloudStorageFileSystem.forBucket("bucket");
+    byte[] data = "hello world".getBytes(StandardCharsets.UTF_8);
+    Path path = fs.getPath("/object");
+    // Write a file in the bucket
+    Files.write(path, data);
+    // Read a file from the bucket
+    data = Files.readAllBytes(path);
+  }
+}

gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/CreateInputStream.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed 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 com.google.cloud.examples.nio.snippets;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+/**
+ * A snippet showing how to create an input stream for a Google Cloud Storage file using NIO.
+ */
+public class CreateInputStream {
+
+  public static void main(String... args) throws IOException {
+    Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
+    try (InputStream input = Files.newInputStream(path)) {
+      // use input stream
+    }
+  }
+}

gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/GetFileSystem.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed 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 com.google.cloud.examples.nio.snippets;
+
+import java.io.IOException;
+import java.net.URI;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.FileSystem;
+import java.nio.file.FileSystems;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * A snippet showing how to get a {@link FileSystem} instance for a Google Cloud Storage bucket.
+ * This snippet also shows how to create a file and read its lines.
+ */
+public class GetFileSystem {
+
+  public static void main(String... args) throws IOException {
+    FileSystem fs = FileSystems.getFileSystem(URI.create("gs://bucket"));
+    byte[] data = "hello world".getBytes(StandardCharsets.UTF_8);
+    Path path = fs.getPath("/object");
+    Files.write(path, data);
+    List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
+  }
+}

gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/ReadAllLines.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed 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 com.google.cloud.examples.nio.snippets;
+
+import java.io.IOException;
+import java.net.URI;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.List;
+
+/**
+ * A snippet showing how to read all lines of a Google Cloud Storage file using NIO.
+ */
+public class ReadAllLines {
+
+  public static void main(String... args) throws IOException {
+    Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
+    List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
+  }
+}

gcloud-java-examples/src/main/java/com/google/cloud/examples/nio/snippets/WriteFileWithAttributes.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed 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 com.google.cloud.examples.nio.snippets;
+
+import static com.google.cloud.storage.contrib.nio.CloudStorageOptions.withMimeType;
+import static com.google.cloud.storage.contrib.nio.CloudStorageOptions.withoutCaching;
+
+import com.google.cloud.storage.contrib.nio.CloudStorageOptions;
+
+import java.io.IOException;
+import java.net.URI;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * A snippet showing how to write a file to Google Cloud Storage using NIO. This example also shows
+ * how to set file attributes, using {@link CloudStorageOptions} static helpers.
+ */
+public class WriteFileWithAttributes {
+
+  private static final String[] LINES = {"value1,", "value"};
+
+  public static void main(String... args) throws IOException {
+    List<String> csvLines =  Arrays.asList(LINES);
+    Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
+    Files.write(path, csvLines, StandardCharsets.UTF_8,
+        withMimeType("text/csv; charset=UTF-8"),
+        withoutCaching());
+  }
+}