From ce34eb44fdc0a4f8a694233998604af7d872673b Mon Sep 17 00:00:00 2001 From: dmitry-fa Date: Wed, 8 Apr 2020 16:40:38 +0300 Subject: [PATCH 1/5] fix: blob api doc is confusing --- .../main/java/com/google/cloud/storage/Blob.java | 13 +++++++++---- .../java/com/google/cloud/storage/BlobInfo.java | 16 +++++++++++++++- 2 files changed, 24 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..b880edba0 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,17 @@ import java.util.concurrent.TimeUnit; /** - * A Google cloud storage object. + * A Google cloud storage object. 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 on obtaining the content will 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 a Storage object made after creation of the + * {@code Blob} is not visible in the {@code Blob}. To get a {@code Blob} object with the most + * recent information use {@link #reload}. */ 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 f21e02153..04d3310fb 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. + * Google Storage object information. 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 Storage + * object 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 crate a Storage object: + * + * 

{@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 From bec01a3f72d7e4783c36358f3af1dc7e519005a0 Mon Sep 17 00:00:00 2001 From: dmitry-fa Date: Wed, 8 Apr 2020 17:16:03 +0300 Subject: [PATCH 2/5] fix: blob api doc is confusing --- .../src/main/java/com/google/cloud/storage/Blob.java | 9 +++++++++ 1 file changed, 9 insertions(+) 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 b880edba0..fd22392c8 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 @@ -63,6 +63,15 @@ * {@link #copyTo} return a new object. Any changes to a Storage object made after creation of the * {@code Blob} is 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 a Storage object: + * + * 

{@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 { From a49ac686c281850b97b1ede88e79a1acd3c8e69c Mon Sep 17 00:00:00 2001 From: dmitry-fa Date: Wed, 8 Apr 2020 19:40:46 +0300 Subject: [PATCH 3/5] fix: blob api doc is confusing --- .../src/main/java/com/google/cloud/storage/Blob.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 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 fd22392c8..ba36abae2 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 @@ -55,13 +55,13 @@ * A Google cloud storage object. 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 on obtaining the content will issue one or multiple RPC calls, depending on the - * content size. + * 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. Any changes to a Storage object made after creation of the - * {@code Blob} is not visible in the {@code Blob}. To get a {@code Blob} object with the most + * {@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 a Storage object: From 754c6c8e6e1258cff2ace0f1c992bde6ff4270b2 Mon Sep 17 00:00:00 2001 From: dmitry-fa Date: Thu, 9 Apr 2020 20:27:08 +0300 Subject: [PATCH 4/5] fix: blob api doc is confusing --- .../main/java/com/google/cloud/storage/Blob.java | 14 +++++++------- .../java/com/google/cloud/storage/BlobInfo.java | 16 ++++++++-------- 2 files changed, 15 insertions(+), 15 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 ba36abae2..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,19 +52,19 @@ import java.util.concurrent.TimeUnit; /** - * A Google cloud storage object. 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 + * 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. Any changes to a Storage object 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}. + * {@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 a Storage object: + *

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

{@code
  * BlobId blobId = BlobId.of(bucketName, blobName);
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 04d3310fb..a4c151084 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,15 +44,15 @@
 import java.util.Set;
 
 /**
- * Google Storage object information. 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 Storage
- * object 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.
+ * 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 crate a Storage object:
+ * 
Example of usage {@code BlobInfo} to crate an object in Google Cloud Storage:
  *
  * 
{@code
  * BlobId blobId = BlobId.of(bucketName, blobName);

From 4d37e98de89b6457fb5b9991bad7141810ce31e6 Mon Sep 17 00:00:00 2001
From: dmitry-fa 
Date: Mon, 13 Apr 2020 16:57:59 +0300
Subject: [PATCH 5/5] fix: deprecate blob.update() and modify documentation of
 storage.update() methods

---
 .../src/main/java/com/google/cloud/storage/BlobInfo.java        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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 a4c151084..930396d73 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
@@ -52,7 +52,7 @@
  * 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 crate an object in Google Cloud Storage:
+ * 
Example of usage {@code BlobInfo} to create an object in Google Cloud Storage:
  *
  * 
{@code
  * BlobId blobId = BlobId.of(bucketName, blobName);