Document patch behaviour in Blob and Storage javadoc

mziccard · mziccard · commit 3b917417d6ca · 2015-10-22T15:06:04.000+02:00
diff --git a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java
@@ -190,6 +190,16 @@ public Blob reload(BlobSourceOption... options) {
    * 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 blob.update(newInfo, BlobTargetOption.metagenerationMatch())}.
+   * <p>
+   * 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}.
+   * </p>
+   * <p>
+   * Example usage of replacing blob's metadata:
+   * <pre>    {@code blob.update(blob.info().toBuilder().metadata(null).build());}
+   *    {@code blob.update(blob.info().toBuilder().metadata(newMetadata).build());}
+   * </pre>
    *
    * @param blobInfo new blob's information. Bucket and blob names must match the current ones
    * @param options update options
@@ -306,8 +316,7 @@ public Storage storage() {
   }
 
   /**
-   * Gets the requested blobs. If {@code infos.length == 0} an empty list is returned. If
-   * {@code infos.length > 1} a batch request is used to fetch blobs.
+   * Gets the requested blobs. A batch request is used to fetch blobs.
    *
    * @param storage the storage service used to issue the request
    * @param blobs the blobs to get
@@ -331,8 +340,12 @@ public Blob apply(BlobInfo f) {
   }
 
   /**
-   * Updates the requested blobs. If {@code infos.length == 0} an empty list is returned. If
-   * {@code infos.length > 1} a batch request is used to update blobs.
+   * Updates the requested blobs. A batch request is used to update blobs. 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(com.google.gcloud.storage.BlobInfo,
+   * com.google.gcloud.storage.Storage.BlobTargetOption...) } for a code example.
    *
    * @param storage the storage service used to issue the request
    * @param infos the blobs to update
@@ -356,8 +369,7 @@ public Blob apply(BlobInfo f) {
   }
 
   /**
-   * Deletes the requested blobs. If {@code infos.length == 0} an empty list is returned. If
-   * {@code infos.length > 1} a batch request is used to delete blobs.
+   * Deletes the requested blobs. A batch request is used to delete blobs.
    *
    * @param storage the storage service used to issue the request
    * @param blobs the blobs to delete
diff --git a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java
@@ -683,15 +683,29 @@ public static Builder builder() {
   BucketInfo update(BucketInfo bucketInfo, BucketTargetOption... options);
 
   /**
-   * Update blob information.
+   * Update 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}.
+   * <p>
+   * Example usage of replacing blob's metadata:
+   * <pre>    {@code service.update(BlobInfo.builder("bucket", "name").metadata(null).build());}
+   *    {@code service.update(BlobInfo.builder("bucket", "name").metadata(newMetadata).build());}
+   * </pre>
    *
    * @return the updated blob
    * @throws StorageException upon failure
    */
   BlobInfo update(BlobInfo blobInfo, BlobTargetOption... options);
 
   /**
-   * Update blob information.
+   * Update 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}.
+   * <p>
+   * Example usage of replacing blob's metadata:
+   * <pre>    {@code service.update(BlobInfo.builder("bucket", "name").metadata(null).build());}
+   *    {@code service.update(BlobInfo.builder("bucket", "name").metadata(newMetadata).build());}
+   * </pre>
    *
    * @return the updated blob
    * @throws StorageException upon failure
@@ -826,7 +840,11 @@ public static Builder builder() {
   List<BlobInfo> get(BlobId... blobIds);
 
   /**
-   * Updates the requested blobs. A batch request is used to perform this call.
+   * 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(com.google.gcloud.storage.BlobInfo)} for a code example.
    *
    * @param blobInfos blobs to update
    * @return an immutable list of {@code BlobInfo} objects. If a blob does not exist or access to it
