From df57705bf37e430d66ff6c7be4ee4a6246d8616e Mon Sep 17 00:00:00 2001 From: JesseLovelace <43148100+JesseLovelace@users.noreply.github.com> Date: Fri, 17 Mar 2023 11:07:24 -0700 Subject: [PATCH] docs: add clarification on non-editable metadata (#1939) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: add clarification on non-editable metadata * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot --- .../com/google/cloud/storage/Storage.java | 36 +++++++++++++++---- 1 file changed, 29 insertions(+), 7 deletions(-) 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 554611e985..0cd1ff07bf 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 @@ -2112,7 +2112,10 @@ public static Builder newBuilder() { Bucket create(BucketInfo bucketInfo, BucketTargetOption... options); /** - * Creates a new blob with no content. + * Creates a new blob with no content. Note that all non-editable metadata, such as + * generation or metageneration, will be ignored even if it's present in the provided BlobInfo + * object. * *

Example of creating a blob with no content. * @@ -2135,7 +2138,10 @@ public static Builder newBuilder() { * #writer} is recommended as it uses resumable upload. MD5 and CRC32C hashes of {@code content} * are computed and used for validating transferred data. Accepts an optional userProject {@link * BlobGetOption} option which defines the project id to assign operational costs. The content - * type is detected from the blob name if not explicitly set. + * type is detected from the blob name if not explicitly set. Note that all non-editable metadata, such as + * generation or metageneration, will be ignored even if it's present in the provided BlobInfo + * object. * *

Example of creating a blob from a byte array: * @@ -2159,7 +2165,10 @@ public static Builder newBuilder() { * {@code content}. For large content, {@link #writer} is recommended as it uses resumable upload. * MD5 and CRC32C hashes of {@code content} are computed and used for validating transferred data. * Accepts a userProject {@link BlobGetOption} option, which defines the project id to assign - * operational costs. + * operational costs. Note that all non-editable metadata, such as + * generation or metageneration, will be ignored even if it's present in the provided BlobInfo + * object. * *

Example of creating a blob from a byte array: * @@ -2184,7 +2193,10 @@ Blob create( * #writer} is recommended as it uses resumable upload. By default any MD5 and CRC32C values in * the given {@code blobInfo} are ignored unless requested via the {@code * BlobWriteOption.md5Match} and {@code BlobWriteOption.crc32cMatch} options. The given input - * stream is closed upon success. + * stream is closed upon success. Note that all non-editable metadata, such as + * generation or metageneration, will be ignored even if it's present in the provided BlobInfo + * object. * *

This method is marked as {@link Deprecated} because it cannot safely retry, given that it * accepts an {@link InputStream} which can only be consumed once. @@ -2226,7 +2238,9 @@ Blob create( * Uploads {@code path} to the blob using {@link #writer}. By default any MD5 and CRC32C values in * the given {@code blobInfo} are ignored unless requested via the {@link * BlobWriteOption#md5Match()} and {@link BlobWriteOption#crc32cMatch()} options. Folder upload is - * not supported. + * not supported. Note that all + * non-editable metadata, such as generation or metageneration, will be ignored even if it's + * present in the provided BlobInfo object. * *

Example of uploading a file: * @@ -2253,7 +2267,9 @@ Blob create( * Uploads {@code path} to the blob using {@link #writer} and {@code bufferSize}. By default any * MD5 and CRC32C values in the given {@code blobInfo} are ignored unless requested via the {@link * BlobWriteOption#md5Match()} and {@link BlobWriteOption#crc32cMatch()} options. Folder upload is - * not supported. + * not supported. Note that all + * non-editable metadata, such as generation or metageneration, will be ignored even if it's + * present in the provided BlobInfo object. * *

{@link #createFrom(BlobInfo, Path, BlobWriteOption...)} invokes this method with a buffer * size of 15 MiB. Users can pass alternative values. Larger buffer sizes might improve the upload @@ -2288,6 +2304,9 @@ Blob createFrom(BlobInfo blobInfo, Path path, int bufferSize, BlobWriteOption... * Reads bytes from an input stream and uploads those bytes to the blob using {@link #writer}. By * default any MD5 and CRC32C values in the given {@code blobInfo} are ignored unless requested * via the {@link BlobWriteOption#md5Match()} and {@link BlobWriteOption#crc32cMatch()} options. + * Note that all non-editable + * metadata, such as generation or metageneration, will be ignored even if it's present in the + * provided BlobInfo object. * *

Example of uploading data with CRC32C checksum: * @@ -2316,7 +2335,10 @@ Blob createFrom(BlobInfo blobInfo, InputStream content, BlobWriteOption... optio * Reads bytes from an input stream and uploads those bytes to the blob using {@link #writer} and * {@code bufferSize}. By default any MD5 and CRC32C values in the given {@code blobInfo} are * ignored unless requested via the {@link BlobWriteOption#md5Match()} and {@link - * BlobWriteOption#crc32cMatch()} options. + * BlobWriteOption#crc32cMatch()} options. Note that all non-editable metadata, such as + * generation or metageneration, will be ignored even if it's present in the provided BlobInfo + * object. * *

{@link #createFrom(BlobInfo, InputStream, BlobWriteOption...)} )} invokes this method with a * buffer size of 15 MiB. Users can pass alternative values. Larger buffer sizes might improve the