fix: Documentation for Blob.update() and Storage.update() methods is confusing/incorrect (#261)

Fixes #252

Author: dmitry-fa

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

@@ -546,45 +546,27 @@ 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. 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...)}.
    *
-   * <p>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}.
+   * <p>The property update details are described in {@link Storage#update(BlobInfo)}. {@link
+   * Storage#update(BlobInfo, BlobTargetOption...)} describes how to specify preconditions.
    *
-   * <p>Example of adding new metadata values or updating existing ones.
+   * <p>Example of updating the content type:
    *
    * <pre>{@code
-   * String bucketName = "my_unique_bucket";
-   * String blobName = "my_blob_name";
-   * Map<String, String> newMetadata = new HashMap<>();
-   * newMetadata.put("keyToAddOrUpdate", "value");
-   * Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
-   *     .setMetadata(newMetadata)
-   *     .build());
-   * }</pre>
-   *
-   * <p>Example of removing metadata values.
-   *
-   * <pre>{@code
-   * String bucketName = "my_unique_bucket";
-   * String blobName = "my_blob_name";
-   * Map<String, String> 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();
    * }</pre>
    *
-   * @param options update options
-   * @return a {@code Blob} object with updated information
+   * @param options preconditions to apply the update
+   * @return the updated {@code Blob}
    * @throws StorageException upon failure
+   * @see <a
+   *     href="https://cloud.google.com/storage/docs/json_api/v1/objects/update">https://cloud.google.com/storage/docs/json_api/v1/objects/update</a>
    */
   public Blob update(BlobTargetOption... options) {
     return storage.update(this, options);

google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java

@@ -1989,60 +1989,73 @@ 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)}.
    *
-   * <p>Example of udating a blob, only if the blob's metageneration matches a value, otherwise a
-   * {@link StorageException} is thrown.
+   * <p>{@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.
+   *
+   * <p>Example of updating the content type only if the properties are not updated externally:
    *
    * <pre>{@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;
+   *   }
+   * }
    * }</pre>
    *
+   * @param blobInfo information to update
+   * @param options preconditions to apply the update
    * @return the updated blob
    * @throws StorageException upon failure
+   * @see <a
+   *     href="https://cloud.google.com/storage/docs/json_api/v1/objects/update">https://cloud.google.com/storage/docs/json_api/v1/objects/update</a>
    */
   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}.
    *
-   * <p>Example of adding new metadata values or updating existing ones.
+   * <p>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.
    *
-   * <pre>{@code
-   * String bucketName = "my-unique-bucket";
-   * String blobName = "my-blob-name";
-   * Map<String, String> newMetadata = new HashMap<>();
-   * newMetadata.put("keyToAddOrUpdate", "value");
-   * Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
-   *     .setMetadata(newMetadata)
-   *     .build());
-   * }</pre>
+   * <p>Property update alters the blob metadata generation and doesn't alter the blob generation.
    *
-   * <p>Example of removing metadata values.
+   * <p>Example of how to update blob's user provided metadata and unset the content type:
    *
    * <pre>{@code
-   * String bucketName = "my-unique-bucket";
-   * String blobName = "my-blob-name";
-   * Map<String, String> newMetadata = new HashMap<>();
-   * newMetadata.put("keyToRemove", null);
-   * Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
-   *     .setMetadata(newMetadata)
-   *     .build());
+   * Map<String, String> 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);
    * }</pre>
    *
+   * @param blobInfo information to update
    * @return the updated blob
    * @throws StorageException upon failure
+   * @see <a
+   *     href="https://cloud.google.com/storage/docs/json_api/v1/objects/update">https://cloud.google.com/storage/docs/json_api/v1/objects/update</a>
    */
   Blob update(BlobInfo blobInfo);
 
@@ -2578,10 +2591,10 @@ Blob create(
   List<Blob> get(Iterable<BlobId> 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.
    *
    * <p>Example of updating information on several blobs using a single batch request.
    *
@@ -2604,10 +2617,10 @@ Blob create(
   List<Blob> 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.
    *
    * <p>Example of updating information on several blobs using a single batch request.
    *