Skip to content

Commit

Permalink
fix: Documentation for Blob.update() and Storage.update() methods is …
Browse files Browse the repository at this point in the history 
…confusing/incorrect (#261)

Fixes #252
  • Loading branch information
@dmitry-fa
dmitry-fa committed Apr 16, 2020
1 parent 5748428 commit 876405f
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 74 deletions.
46 changes: 14 additions & 32 deletions google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java
View file
Expand Up @@ -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);
Expand Down
97 changes: 55 additions & 42 deletions google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java
View file
Expand Up @@ -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);

Expand Down Expand Up @@ -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.
*
Expand All @@ -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.
*
Expand Down

0 comments on commit 876405f

Please sign in to comment.