diff --git a/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java b/gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BlobSnippets.java new file mode 100644 index 000000000000..f70302b7b279 --- /dev/null +++ b/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 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")))); + } +} diff --git a/gcloud-java-storage/src/main/java/com/google/cloud/storage/Blob.java b/gcloud-java-storage/src/main/java/com/google/cloud/storage/Blob.java index 3cbb3826541f..7c39a6c9a355 100644 --- a/gcloud-java-storage/src/main/java/com/google/cloud/storage/Blob.java +++ b/gcloud-java-storage/src/main/java/com/google/cloud/storage/Blob.java @@ -322,6 +322,17 @@ public Blob build() { /** * Checks if this blob exists. * + *

Example of checking if the blob exists (see {@code exists()} in + * + * BlobSnippets.java): + * 

 {@code
+   * boolean exists = blob.exists();
+   * if (exists) {
+   *   // the blob exists
+   * } else {
+   *   // the blob was not found
+   * }}
+ * * @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. * + *

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

 {@code
+   * byte[] content = blob.content(BlobSourceOption.generationMatch());
+   * }
+ * * @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. * + *

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

 {@code
+   * Blob latestBlob = blob.reload(BlobSourceOption.generationNotMatch());
+   * if (latestBlob == null) {
+   *   // the blob was not found
+   * }}
+ * * @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}. *

* - *

Example usage of replacing blob's metadata: + *

Example of replacing blob's metadata (see {@code update()} in + * + * BlobSnippets.java): * 

 {@code
+   * Map newMetadata = new HashMap<>();
+   * newMetadata.put("key", "value");
    * blob.toBuilder().metadata(null).build().update();
    * blob.toBuilder().metadata(newMetadata).build().update();
-   * }
-   *
+ * } * * @param options update options * @return a {@code Blob} object with updated information @@ -385,6 +419,18 @@ public Blob update(BlobTargetOption... options) { /** * Deletes this blob. * + *

Example of deleting the blob, if its generation matches the {@link Blob#generation()} value, + * otherwise a {@link StorageException} is thrown (see {@code delete()} in + * + * BlobSnippets.java): + * 

 {@code
+   * boolean deleted = blob.delete(BlobSourceOption.generationMatch());
+   * if (deleted) {
+   *   // the blob was deleted
+   * } else {
+   *   // the blob was not found
+   * }}
+ * * @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). * + *

Example of copying the blob to a different bucket with a different name (see + * {@code copyToId()} in + * + * BlobSnippets.java): + * 

 {@code
+   * CopyWriter copyWriter = blob.copyTo(BlobId.of("my_other_unique_bucket", "copy_blob_name"));
+   * Blob copiedBlob = copyWriter.result();
+   * }
+ * * @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). * + *

Example of copying the blob to a different bucket, keeping the original name (see + * {@code copyToBucket()} in + * + * BlobSnippets.java): + * 

 {@code
+   * CopyWriter copyWriter = blob.copyTo("my_other_unique_bucket");
+   * Blob copiedBlob = copyWriter.result();
+   * }
+ * * @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). * + *

Example of copying the blob to a different bucket with a different name (see + * {@code copyToStrings()} in + * + * BlobSnippets.java): + * 

 {@code
+   * CopyWriter copyWriter = blob.copyTo("my_other_unique_bucket");
+   * Blob copiedBlob = copyWriter.result();
+   * }
+ * * @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. * + *

Example of reading the blob's content through a reader (see {@code reader()} in + * + * BlobSnippets.java): + * 

 {@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();
+   *   }
+   * }}
+ * * @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. * + *

Example of writing the blob's content through a writer (see {@code writer()} in + * + * BlobSnippets.java): + * 

 {@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
+   *   }
+   * }}
+ * * @param options target blob options * @throws StorageException upon failure */ @@ -485,15 +584,19 @@ public WriteChannel writer(BlobWriteOption... options) { *
  • The default credentials, if no credentials were passed to {@link StorageOptions} * * - *

    Example usage of creating a signed URL that is valid for 2 weeks, using the default - * credentials for signing the URL: + *

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

     {@code
    * blob.signUrl(14, TimeUnit.DAYS);
    * }
    * - *

    Example usage of creating a signed URL passing the - * {@link SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used for signing the - * URL: + *

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

     {@code
    * blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.signWith(
    *     AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));