Add snippets to Blob's javadoc and BlobSnippets class to gcloud-java-examples

Author: mziccard

gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java

@@ -0,0 +1,178 @@
+/*
+ * 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.
+ */
+
+/*
+ * EDITING INSTRUCTIONS
+ * This file is referenced in Blob's javadoc. Any change to this file should be reflected in Blob's
+ * javadoc.
+ */
+
+package com.google.cloud.examples.storage.snippets;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import com.google.cloud.AuthCredentials;
+import com.google.cloud.ReadChannel;
+import com.google.cloud.ServiceAccountSigner;
+import com.google.cloud.WriteChannel;
+import com.google.cloud.storage.Blob;
+import com.google.cloud.storage.Blob.BlobSourceOption;
+import com.google.cloud.storage.BlobId;
+import com.google.cloud.storage.CopyWriter;
+import com.google.cloud.storage.Storage.SignUrlOption;
+import com.google.cloud.storage.StorageException;
+
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * This class contains a number of snippets for the {@link Blob} class.
+ */
+public class BlobSnippets {
+
+  private final Blob blob;
+
+  public BlobSnippets(Blob blob) {
+    this.blob = blob;
+  }
+
+  /**
+   * Example of checking if the blob exists.
+   */
+  public void exists() {
+    boolean exists = blob.exists();
+    if (exists) {
+      // the blob exists
+    } else {
+      // the blob was not found
+    }
+  }
+
+  /**
+   * Example of reading all bytes of the blob, if its generation matches the
+   * {@link Blob#generation()} value, otherwise a {@link StorageException} is thrown.
+   */
+  public void content() {
+    byte[] content = blob.content(BlobSourceOption.generationMatch());
+  }
+
+  /**
+   * Example of getting the blob's latest information, if its generation does not match the
+   * {@link Blob#generation()} value, otherwise a {@link StorageException} is thrown.
+   */
+  public void reload() {
+    Blob latestBlob = blob.reload(BlobSourceOption.generationNotMatch());
+    if (latestBlob == null) {
+      // the blob was not found
+    }
+  }
+
+  /**
+   * Example of replacing blob's metadata.
+   */
+  public void update() {
+    Map<String, String> newMetadata = new HashMap<>();
+    newMetadata.put("key", "value");
+    blob.toBuilder().metadata(null).build().update();
+    blob.toBuilder().metadata(newMetadata).build().update();
+  }
+
+  /**
+   * Example of deleting the blob, if its generation matches the {@link Blob#generation()} value,
+   * otherwise a {@link StorageException} is thrown.
+   */
+  public void delete() {
+    boolean deleted = blob.delete(BlobSourceOption.generationMatch());
+    if (deleted) {
+      // the blob was deleted
+    } else {
+      // the blob was not found
+    }
+  }
+
+  /**
+   * Example of copying the blob to a different bucket with a different name.
+   */
+  public void copyToId() {
+    CopyWriter copyWriter = blob.copyTo(BlobId.of("my_other_unique_bucket", "copy_blob_name"));
+    Blob copiedBlob = copyWriter.result();
+  }
+
+  /**
+   * Example of copying the blob to a different bucket, keeping the original name.
+   */
+  public void copyToBucket() {
+    CopyWriter copyWriter = blob.copyTo("my_other_unique_bucket");
+    Blob copiedBlob = copyWriter.result();
+  }
+
+  /**
+   * Example of copying the blob to a different bucket with a different name.
+   */
+  public void copyToStrings() {
+    CopyWriter copyWriter = blob.copyTo("my_other_unique_bucket", "copy_blob_name");
+    Blob copiedBlob = copyWriter.result();
+  }
+
+  /**
+   * Example of reading the blob's content through a reader.
+   */
+  public void reader() throws IOException {
+    try (ReadChannel reader = blob.reader()) {
+      ByteBuffer bytes = ByteBuffer.allocate(64 * 1024);
+      while (reader.read(bytes) > 0) {
+        bytes.flip();
+        // do something with bytes
+        bytes.clear();
+      }
+    }
+  }
+
+  /**
+   * Example of writing the blob's content through a writer.
+   */
+  public void writer() throws IOException {
+    byte[] content = "Hello, World!".getBytes(UTF_8);
+    try (WriteChannel writer = blob.writer()) {
+      try {
+        writer.write(ByteBuffer.wrap(content, 0, content.length));
+      } catch (Exception ex) {
+        // handle exception
+      }
+    }
+  }
+
+  /**
+   * Example of creating a signed URL for the blob that is valid for 2 weeks, using the default
+   * credentials for signing the URL.
+   */
+  public void signUrl() {
+    blob.signUrl(14, TimeUnit.DAYS);
+  }
+
+  /**
+   * Example of creating a signed URL for the blob passing the
+   * {@link SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used to sign the URL.
+   */
+  public void signUrlWithSigner() throws IOException {
+    blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.signWith(
+        AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
+  }
+}

gcloud-java-storage/src/main/java/com/google/cloud/storage/Blob.java

@@ -322,6 +322,17 @@ public Blob build() {
   /**
    * Checks if this blob exists.
    *
+   * <p>Example of checking if the blob exists (see {@code exists()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * boolean exists = blob.exists();
+   * if (exists) {
+   *   // the blob exists
+   * } else {
+   *   // the blob was not found
+   * }}</pre>
+   *
    * @param options blob read options
    * @return true if this blob exists, false otherwise
    * @throws StorageException upon failure
@@ -336,16 +347,36 @@ public boolean exists(BlobSourceOption... options) {
   /**
    * Returns this blob's content.
    *
+   * <p>Example of reading all bytes of the blob, if its generation matches the
+   * {@link Blob#generation()} value, otherwise a {@link StorageException} is thrown (see
+   * {@code content()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * byte[] content = blob.content(BlobSourceOption.generationMatch());
+   * }</pre>
+   *
    * @param options blob read options
    * @throws StorageException upon failure
    */
-  public byte[] content(Storage.BlobSourceOption... options) {
-    return storage.readAllBytes(blobId(), options);
+  public byte[] content(BlobSourceOption... options) {
+    return storage.readAllBytes(blobId(), toSourceOptions(this, options));
   }
 
   /**
    * Fetches current blob's latest information. Returns {@code null} if the blob does not exist.
    *
+   * <p>Example of getting the blob's latest information, if its generation does not match the
+   * {@link Blob#generation()} value, otherwise a {@link StorageException} is thrown (see
+   * {@code reload()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * Blob latestBlob = blob.reload(BlobSourceOption.generationNotMatch());
+   * if (latestBlob == null) {
+   *   // the blob was not found
+   * }}</pre>
+   *
    * @param options blob read options
    * @return a {@code Blob} object with latest information or {@code null} if not found
    * @throws StorageException upon failure
@@ -367,12 +398,15 @@ public Blob reload(BlobSourceOption... options) {
    * {@code blob}'s metadata to {@code null}.
    * </p>
    *
-   * <p>Example usage of replacing blob's metadata:
+   * <p>Example of replacing blob's metadata (see {@code update()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
    * <pre> {@code
+   * Map<String, String> newMetadata = new HashMap<>();
+   * newMetadata.put("key", "value");
    * blob.toBuilder().metadata(null).build().update();
    * blob.toBuilder().metadata(newMetadata).build().update();
-   * }
-   * </pre>
+   * }</pre>
    *
    * @param options update options
    * @return a {@code Blob} object with updated information
@@ -385,6 +419,18 @@ public Blob update(BlobTargetOption... options) {
   /**
    * Deletes this blob.
    *
+   * <p>Example of deleting the blob, if its generation matches the {@link Blob#generation()} value,
+   * otherwise a {@link StorageException} is thrown (see {@code delete()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * boolean deleted = blob.delete(BlobSourceOption.generationMatch());
+   * if (deleted) {
+   *   // the blob was deleted
+   * } else {
+   *   // the blob was not found
+   * }}</pre>
+   *
    * @param options blob delete options
    * @return {@code true} if blob was deleted, {@code false} if it was not found
    * @throws StorageException upon failure
@@ -397,6 +443,15 @@ public boolean delete(BlobSourceOption... options) {
    * Sends a copy request for the current blob to the target blob. Possibly also some of the
    * metadata are copied (e.g. content-type).
    *
+   * <p>Example of copying the blob to a different bucket with a different name (see
+   * {@code copyToId()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * CopyWriter copyWriter = blob.copyTo(BlobId.of("my_other_unique_bucket", "copy_blob_name"));
+   * Blob copiedBlob = copyWriter.result();
+   * }</pre>
+   *
    * @param targetBlob target blob's id
    * @param options source blob options
    * @return a {@link CopyWriter} object that can be used to get information on the newly created
@@ -416,6 +471,15 @@ public CopyWriter copyTo(BlobId targetBlob, BlobSourceOption... options) {
    * Sends a copy request for the current blob to the target bucket, preserving its name. Possibly
    * copying also some of the metadata (e.g. content-type).
    *
+   * <p>Example of copying the blob to a different bucket, keeping the original name (see
+   * {@code copyToBucket()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * CopyWriter copyWriter = blob.copyTo("my_other_unique_bucket");
+   * Blob copiedBlob = copyWriter.result();
+   * }</pre>
+   *
    * @param targetBucket target bucket's name
    * @param options source blob options
    * @return a {@link CopyWriter} object that can be used to get information on the newly created
@@ -430,6 +494,15 @@ public CopyWriter copyTo(String targetBucket, BlobSourceOption... options) {
    * Sends a copy request for the current blob to the target blob. Possibly also some of the
    * metadata are copied (e.g. content-type).
    *
+   * <p>Example of copying the blob to a different bucket with a different name (see
+   * {@code copyToStrings()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * CopyWriter copyWriter = blob.copyTo("my_other_unique_bucket");
+   * Blob copiedBlob = copyWriter.result();
+   * }</pre>
+   *
    * @param targetBucket target bucket's name
    * @param targetBlob target blob's name
    * @param options source blob options
@@ -444,6 +517,19 @@ public CopyWriter copyTo(String targetBucket, String targetBlob, BlobSourceOptio
   /**
    * Returns a {@code ReadChannel} object for reading this blob's content.
    *
+   * <p>Example of reading the blob's content through a reader (see {@code reader()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * try (ReadChannel reader = blob.reader()) {
+   *   ByteBuffer bytes = ByteBuffer.allocate(64 * 1024);
+   *   while (reader.read(bytes) > 0) {
+   *     bytes.flip();
+   *     // do something with bytes
+   *     bytes.clear();
+   *   }
+   * }}</pre>
+   *
    * @param options blob read options
    * @throws StorageException upon failure
    */
@@ -456,6 +542,19 @@ public ReadChannel reader(BlobSourceOption... options) {
    * crc32c values in the current blob are ignored unless requested via the
    * {@code BlobWriteOption.md5Match} and {@code BlobWriteOption.crc32cMatch} options.
    *
+   * <p>Example of writing the blob's content through a writer (see {@code writer()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
+   * <pre> {@code
+   * byte[] content = "Hello, World!".getBytes(UTF_8);
+   * try (WriteChannel writer = blob.writer()) {
+   *   try {
+   *     writer.write(ByteBuffer.wrap(content, 0, content.length));
+   *   } catch (Exception ex) {
+   *     // handle exception
+   *   }
+   * }}</pre>
+   *
    * @param options target blob options
    * @throws StorageException upon failure
    */
@@ -485,15 +584,19 @@ public WriteChannel writer(BlobWriteOption... options) {
    *   <li>The default credentials, if no credentials were passed to {@link StorageOptions}
    * </ol>
    *
-   * <p>Example usage of creating a signed URL that is valid for 2 weeks, using the default
-   * credentials for signing the URL:
+   * <p>Example of creating a signed URL for the blob that is valid for 2 weeks, using the default
+   * credentials for signing the URL (see {@code signUrl()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
    * <pre> {@code
    * blob.signUrl(14, TimeUnit.DAYS);
    * }</pre>
    *
-   * <p>Example usage of creating a signed URL passing the
-   * {@link SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used for signing the
-   * URL:
+   * <p>Example of creating a signed URL for the blob passing the
+   * {@link SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used to sign the URL
+   * (see {@code signUrlWithSigner()} in
+   * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java">
+   * BlobSnippets.java</a>):
    * <pre> {@code
    * blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.signWith(
    *     AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));