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 {@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 a9bb589a2..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
@@ -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)}.
*
- * 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
+ * @see https://cloud.google.com/storage/docs/json_api/v1/objects/update
*/
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
+ * @see https://cloud.google.com/storage/docs/json_api/v1/objects/update
*/
Blob update(BlobInfo blobInfo);
@@ -2578,10 +2591,10 @@ Blob create(
ListExample of updating information on several blobs using a single batch request.
*
@@ -2604,10 +2617,10 @@ Blob create(
List Example of updating information on several blobs using a single batch request.
*