From 74f2de77768efc63d2ed6d0dc91d7a591686ebdd Mon Sep 17 00:00:00 2001 From: dmitry-fa Date: Thu, 16 Apr 2020 15:16:51 +0300 Subject: [PATCH 1/3] fix: documentation for blob.update() and storage.update() methods is confusing/incorrect --- .../java/com/google/cloud/storage/Blob.java | 44 +++------ .../com/google/cloud/storage/Storage.java | 93 ++++++++++--------- 2 files changed, 63 insertions(+), 74 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 3cb99e61d..d23939877 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 @@ -546,44 +546,24 @@ public Blob reload(BlobSourceOption... options) { } /** - * Updates the blob's information. Bucket or blob's name cannot be changed by this method. If you - * want to rename the blob or move it to a different bucket use the {@link #copyTo} and {@link - * #delete} operations. A new {@code Blob} object is returned. By default no checks are made on - * the metadata generation of the current blob. If you want to update the information only if the - * current blob metadata are at their latest version use the {@code metagenerationMatch} option: - * {@code newBlob.update(BlobTargetOption.metagenerationMatch())}. + * Updates the blob properties. Optional {@code options} parameter can contain the preconditions + * for applying the update. To update the properties you need to call {@link #toBuilder()}, set + * the properties you want to change, build the new {@code Blob} instance and then call {@link + * #update(BlobTargetOption...)}. * - *

Original metadata are merged with metadata in the provided {@code blobInfo}. If the original - * metadata already contains a key specified in the provided {@code blobInfo's} metadata map, it - * will be replaced by the new value. Removing metadata can be done by setting that metadata's - * value to {@code null}. + *

The property update details are described in {@link Storage#update(BlobInfo)}. {@link + * Storage#update(BlobInfo, BlobTargetOption...)} describes how to specify preconditions. * - *

Example of adding new metadata values or updating existing ones. + *

Example of updating the content type: * * 

{@code
-   * String bucketName = "my_unique_bucket";
-   * String blobName = "my_blob_name";
-   * Map newMetadata = new HashMap<>();
-   * newMetadata.put("keyToAddOrUpdate", "value");
-   * Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
-   *     .setMetadata(newMetadata)
-   *     .build());
-   * }
- * - *

Example of removing metadata values. - * - * 

{@code
-   * String bucketName = "my_unique_bucket";
-   * String blobName = "my_blob_name";
-   * Map newMetadata = new HashMap<>();
-   * newMetadata.put("keyToRemove", null);
-   * Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
-   *     .setMetadata(newMetadata)
-   *     .build());
+   * BlobId blobId = BlobId.of(bucketName, blobName);
+   * Blob blob = storage.get(blobId);
+   * blob.toBuilder().setContentType("text/plain").build().update();
    * }
* - * @param options update options - * @return a {@code Blob} object with updated information + * @param options preconditions to apply the update + * @return the updated blob * @throws StorageException upon failure */ public Blob update(BlobTargetOption... options) { diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java index a9bb589a2..9317033c6 100644 --- a/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java +++ b/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java @@ -1989,58 +1989,67 @@ Blob create( Bucket update(BucketInfo bucketInfo, BucketTargetOption... options); /** - * Updates blob information. Original metadata are merged with metadata in the provided {@code - * blobInfo}. To replace metadata instead you first have to unset them. Unsetting metadata can be - * done by setting the provided {@code blobInfo}'s metadata to {@code null}. Accepts an optional - * userProject {@link BlobTargetOption} option which defines the project id to assign operational - * costs. + * Updates the blob properties if the preconditions specified by {@code options} are met. The + * property update works as described in {@link #update(BlobInfo)}. * - *

Example of udating a blob, only if the blob's metageneration matches a value, otherwise a - * {@link StorageException} is thrown. + *

{@code options} parameter can contain the preconditions for applying the update. E.g. update + * of the blob properties might be required only if the properties have not been updated + * externally. {@code StorageException} with the code {@code 412} is thrown if preconditions fail. + * + *

Example of updating the content type only if the properties are not updated externally: * * 

{@code
-   * String bucketName = "my-unique-bucket";
-   * String blobName = "my-blob-name";
-   * Blob blob = storage.get(bucketName, blobName);
-   * BlobInfo updatedInfo = blob.toBuilder().setContentType("text/plain").build();
-   * storage.update(updatedInfo, BlobTargetOption.metagenerationMatch());
+   * BlobId blobId = BlobId.of(bucketName, blobName);
+   * BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
+   * Blob blob = storage.create(blobInfo);
+   *
+   * doSomething();
+   *
+   * BlobInfo update = blob.toBuilder().setContentType("multipart/form-data").build();
+   * Storage.BlobTargetOption option = Storage.BlobTargetOption.metagenerationMatch();
+   * try {
+   *   storage.update(update, option);
+   * } catch (StorageException e) {
+   *   if (e.getCode() == 412) {
+   *     // the properties were updated externally
+   *   } else {
+   *     throw e;
+   *   }
+   * }
    * }
* + * @param blobInfo information to update + * @param options preconditions to apply the update * @return the updated blob * @throws StorageException upon failure */ Blob update(BlobInfo blobInfo, BlobTargetOption... options); /** - * Updates blob information. Original metadata are merged with metadata in the provided {@code - * blobInfo}. If the original metadata already contains a key specified in the provided {@code - * blobInfo's} metadata map, it will be replaced by the new value. Removing metadata can be done - * by setting that metadata's value to {@code null}. + * Updates the properties of the blob. This method issues an RPC request to merge the current blob + * properties with the properties in the provided {@code blobInfo}. Properties not defined in + * {@code blobInfo} will not be updated. To unset a blob property this property in {@code + * blobInfo} should be explicitly set to {@code null}. * - *

Example of adding new metadata values or updating existing ones. + *

Bucket or blob's name cannot be changed by this method. If you want to rename the blob or + * move it to a different bucket use the {@link Blob#copyTo} and {@link #delete} operations. * - * 

{@code
-   * String bucketName = "my-unique-bucket";
-   * String blobName = "my-blob-name";
-   * Map newMetadata = new HashMap<>();
-   * newMetadata.put("keyToAddOrUpdate", "value");
-   * Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
-   *     .setMetadata(newMetadata)
-   *     .build());
-   * }
+ *

Property update alters the blob metadata generation and doesn't alter the blob generation. * - *

Example of removing metadata values. + *

Example of how to update blob's user provided metadata and unset the content type: * * 

{@code
-   * String bucketName = "my-unique-bucket";
-   * String blobName = "my-blob-name";
-   * Map newMetadata = new HashMap<>();
-   * newMetadata.put("keyToRemove", null);
-   * Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
-   *     .setMetadata(newMetadata)
-   *     .build());
+   * Map metadataUpdate = new HashMap<>();
+   * metadataUpdate.put("keyToAdd", "new value");
+   * metadataUpdate.put("keyToRemove", null);
+   * BlobInfo blobUpdate = BlobInfo.newBuilder(bucketName, blobName)
+   *     .setMetadata(metadataUpdate)
+   *     .setContentType(null)
+   *     .build();
+   * Blob blob = storage.update(blobUpdate);
    * }
* + * @param blobInfo information to update * @return the updated blob * @throws StorageException upon failure */ @@ -2578,10 +2587,10 @@ Blob create( List get(Iterable blobIds); /** - * Updates the requested blobs. A batch request is used to perform this call. Original metadata - * are merged with metadata in the provided {@code BlobInfo} objects. To replace metadata instead - * you first have to unset them. Unsetting metadata can be done by setting the provided {@code - * BlobInfo} objects metadata to {@code null}. See {@link #update(BlobInfo)} for a code example. + * Updates the requested blobs. A batch request is used to perform this call. The original + * properties are merged with the properties in the provided {@code BlobInfo} objects. Unsetting a + * property can be done by setting the property of the provided {@code BlobInfo} objects to {@code + * null}. See {@link #update(BlobInfo)} for a code example. * *

Example of updating information on several blobs using a single batch request. * @@ -2604,10 +2613,10 @@ Blob create( List update(BlobInfo... blobInfos); /** - * Updates the requested blobs. A batch request is used to perform this call. Original metadata - * are merged with metadata in the provided {@code BlobInfo} objects. To replace metadata instead - * you first have to unset them. Unsetting metadata can be done by setting the provided {@code - * BlobInfo} objects metadata to {@code null}. See {@link #update(BlobInfo)} for a code example. + * Updates the requested blobs. A batch request is used to perform this call. The original + * properties are merged with the properties in the provided {@code BlobInfo} objects. Unsetting a + * property can be done by setting the property of the provided {@code BlobInfo} objects to {@code + * null}. See {@link #update(BlobInfo)} for a code example. * *

Example of updating information on several blobs using a single batch request. * From 6a97d29a08297130f6d4b4964e7c9e8f429b76a4 Mon Sep 17 00:00:00 2001 From: dmitry-fa Date: Thu, 16 Apr 2020 15:30:43 +0300 Subject: [PATCH 2/3] fix: documentation for blob.update() and storage.update() methods is confusing/incorrect --- .../src/main/java/com/google/cloud/storage/Blob.java | 6 +++--- 1 file changed, 3 insertions(+), 3 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 d23939877..cb4de57dd 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 @@ -546,9 +546,9 @@ public Blob reload(BlobSourceOption... options) { } /** - * Updates the blob properties. Optional {@code options} parameter can contain the preconditions - * for applying the update. To update the properties you need to call {@link #toBuilder()}, set - * the properties you want to change, build the new {@code Blob} instance and then call {@link + * Updates the blob properties. The {@code options} parameter contains the preconditions for + * applying the update. To update the properties call {@link #toBuilder()}, set the properties you + * want to change, build the new {@code Blob} instance, and then call {@link * #update(BlobTargetOption...)}. * *

The property update details are described in {@link Storage#update(BlobInfo)}. {@link From 81285fa08869841f014851c783ab8abd198f9e3c Mon Sep 17 00:00:00 2001 From: dmitry-fa Date: Fri, 17 Apr 2020 01:17:27 +0300 Subject: [PATCH 3/3] docs: label legacy storage classes in documentation --- .../src/main/java/com/google/cloud/storage/Blob.java | 4 +++- .../src/main/java/com/google/cloud/storage/Storage.java | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) 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 cb4de57dd..743f3e7b4 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 @@ -563,8 +563,10 @@ public Blob reload(BlobSourceOption... options) { * } * * @param options preconditions to apply the update - * @return the updated blob + * @return the updated {@code Blob} * @throws StorageException upon failure + * @see https://cloud.google.com/storage/docs/json_api/v1/objects/update */ public Blob update(BlobTargetOption... options) { return storage.update(this, options); diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java index 9317033c6..eb22eddc1 100644 --- a/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java +++ b/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java @@ -2022,6 +2022,8 @@ Blob create( * @param options preconditions to apply the update * @return the updated blob * @throws StorageException upon failure + * @see https://cloud.google.com/storage/docs/json_api/v1/objects/update */ Blob update(BlobInfo blobInfo, BlobTargetOption... options); @@ -2052,6 +2054,8 @@ Blob create( * @param blobInfo information to update * @return the updated blob * @throws StorageException upon failure + * @see https://cloud.google.com/storage/docs/json_api/v1/objects/update */ Blob update(BlobInfo blobInfo);