From b5208b87e5469bfdf684bd5f250921be99a59ac8 Mon Sep 17 00:00:00 2001 From: Dmitry <58846611+dmitry-fa@users.noreply.github.com> Date: Tue, 14 Apr 2020 23:03:16 +0300 Subject: [PATCH] fix: Blob API Doc is confusing (#233) * fix: blob api doc is confusing * fix: blob api doc is confusing * fix: blob api doc is confusing * fix: blob api doc is confusing * fix: deprecate blob.update() and modify documentation of storage.update() methods --- .../java/com/google/cloud/storage/Blob.java | 22 +++++++++++++++---- .../com/google/cloud/storage/BlobInfo.java | 16 +++++++++++++- 2 files changed, 33 insertions(+), 5 deletions(-) diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java index 7efc24c96..3cb99e61d 100644 --- a/google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java +++ b/google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java @@ -52,12 +52,26 @@ import java.util.concurrent.TimeUnit; /** - * A Google cloud storage object. + * An object in Google Cloud Storage. A {@code Blob} object includes the {@code BlobId} instance, + * the set of properties inherited from the {@link BlobInfo} class and the {@code Storage} instance. + * The class provides methods to perform operations on the object. Reading a property value does not + * issue any RPC calls. The object content is not stored within the {@code Blob} instance. + * Operations that access the content issue one or multiple RPC calls, depending on the content + * size. * *

Objects of this class are immutable. Operations that modify the blob like {@link #update} and - * {@link #copyTo} return a new object. To get a {@code Blob} object with the most recent - * information use {@link #reload}. {@code Blob} adds a layer of service-related functionality over - * {@link BlobInfo}. + * {@link #copyTo} return a new object. Any changes to the object in Google Cloud Storage made after + * creation of the {@code Blob} are not visible in the {@code Blob}. To get a {@code Blob} object + * with the most recent information use {@link #reload}. + * + *

Example of getting the content of the object in Google Cloud Storage: + * + * 

{@code
+ * BlobId blobId = BlobId.of(bucketName, blobName);
+ * Blob blob = storage.get(blobId);
+ * long size = blob.getSize(); // no RPC call is required
+ * byte[] content = blob.getContent(); // one or multiple RPC calls will be issued
+ * }
*/ public class Blob extends BlobInfo { diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/BlobInfo.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/BlobInfo.java index 463f34f90..ef38ba033 100644 --- a/google-cloud-storage/src/main/java/com/google/cloud/storage/BlobInfo.java +++ b/google-cloud-storage/src/main/java/com/google/cloud/storage/BlobInfo.java @@ -44,7 +44,21 @@ import java.util.Set; /** - * Google Storage object metadata. + * Information about an object in Google Cloud Storage. A {@code BlobInfo} object includes the + * {@code BlobId} instance and the set of properties, such as the blob's access control + * configuration, user provided metadata, the CRC32C checksum, etc. Instances of this class are used + * to create a new object in Google Cloud Storage or update the properties of an existing object. To + * deal with existing Storage objects the API includes the {@link Blob} class which extends {@code + * BlobInfo} and declares methods to perform operations on the object. Neither {@code BlobInfo} nor + * {@code Blob} instances keep the object content, just the object properties. + * + *

Example of usage {@code BlobInfo} to create an object in Google Cloud Storage: + * + * 

{@code
+ * BlobId blobId = BlobId.of(bucketName, blobName);
+ * BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
+ * Blob blob = storage.create(blobInfo, "Hello, world".getBytes(StandardCharsets.UTF_8));
+ * }
* * @see Concepts and * Terminology