Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 3 commits into from
Apr 16, 2020
Merged

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

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
74f2de7
fix: documentation for blob.update() and storage.update() methods is …
dmitry-fa Apr 16, 2020
6a97d29
fix: documentation for blob.update() and storage.update() methods is …
dmitry-fa Apr 16, 2020
81285fa
docs: label legacy storage classes in documentation
dmitry-fa Apr 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 12 additions & 32 deletions google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. The {@code options} parameter contains the preconditions for
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd state {@code options} is BlobTargetOption and instead of preconditions use request options and link to update API documentation: https://cloud.google.com/storage/docs/json_api/v1/objects/update

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and link to update API documentation: https://cloud.google.com/storage/docs/json_api/v1/objects/update

done

I'd state {@code options} is BlobTargetOption

I think this is clear from the parameter type

and instead of preconditions use request options

Personally for me it was hard to understand the purspose of this parameter. So, I tried to rephrase this statement to help users not very familiar with the Storage details to get the meaning. I came up to: The options parameter contains the preconditions for applying the update

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, sgtm, I think having the link will help provide information.

* 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 blob
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the updated {@code Blob}

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay

* @throws StorageException upon failure
*/
public Blob update(BlobTargetOption... options) {
Expand Down
93 changes: 51 additions & 42 deletions google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)}.
*
* <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
*/
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
*/
Expand Down Expand Up @@ -2578,10 +2587,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 +2613,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