docs: Add preconditions to some samples (#1600)

* docs: Add preconditions to some samples

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* remove star import

* add null checks

* 🦉 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 <gcf-owl-bot[bot]@users.noreply.github.com>

Author: JesseLovelace

samples/snippets/src/main/java/com/example/storage/object/ChangeObjectCsekToKms.java

@@ -17,6 +17,7 @@
 package com.example.storage.object;
 
 // [START storage_object_csek_to_cmek]
+import com.google.cloud.storage.Blob;
 import com.google.cloud.storage.BlobId;
 import com.google.cloud.storage.Storage;
 import com.google.cloud.storage.StorageOptions;
@@ -47,10 +48,22 @@ public static void changeObjectFromCsekToKms(
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
     BlobId blobId = BlobId.of(bucketName, objectName);
+    Blob blob = storage.get(blobId);
+    if (blob == null) {
+      System.out.println("The object " + objectName + " wasn't found in " + bucketName);
+      return;
+    }
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request to upload returns a 412 error if
+    // the object's generation number does not match your precondition.
+    Storage.BlobSourceOption precondition =
+        Storage.BlobSourceOption.generationMatch(blob.getGeneration());
+
     Storage.CopyRequest request =
         Storage.CopyRequest.newBuilder()
             .setSource(blobId)
-            .setSourceOptions(Storage.BlobSourceOption.decryptionKey(decryptionKey))
+            .setSourceOptions(Storage.BlobSourceOption.decryptionKey(decryptionKey), precondition)
             .setTarget(blobId, Storage.BlobTargetOption.kmsKeyName(kmsKeyName))
             .build();
     storage.copy(request);

samples/snippets/src/main/java/com/example/storage/object/ChangeObjectStorageClass.java

@@ -38,18 +38,32 @@ public static void changeObjectStorageClass(
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
     BlobId blobId = BlobId.of(bucketName, objectName);
+    Blob sourceBlob = storage.get(blobId);
+    if (sourceBlob == null) {
+      System.out.println("The object " + objectName + " wasn't found in " + bucketName);
+      return;
+    }
 
     // See the StorageClass documentation for other valid storage classes:
     // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
     StorageClass storageClass = StorageClass.COLDLINE;
 
     // You can't change an object's storage class directly, the only way is to rewrite the object
-    // with the
-    // desired storage class
+    // with the desired storage class
+
+    BlobInfo targetBlob = BlobInfo.newBuilder(blobId).setStorageClass(storageClass).build();
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request to upload returns a 412 error if
+    // the object's generation number does not match your precondition.
+    Storage.BlobSourceOption precondition =
+        Storage.BlobSourceOption.generationMatch(sourceBlob.getGeneration());
+
     Storage.CopyRequest request =
         Storage.CopyRequest.newBuilder()
             .setSource(blobId)
-            .setTarget(BlobInfo.newBuilder(blobId).setStorageClass(storageClass).build())
+            .setSourceOptions(precondition) // delete this line to run without preconditions
+            .setTarget(targetBlob)
             .build();
     Blob updatedBlob = storage.copy(request).getResult();
 

samples/snippets/src/main/java/com/example/storage/object/ComposeObject.java

@@ -46,12 +46,22 @@ public static void composeObject(
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
 
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request returns a 412 error if the
+    // preconditions are not met.
+    // For a target object that does not yet exist, set the DoesNotExist precondition.
+    Storage.BlobTargetOption precondition = Storage.BlobTargetOption.doesNotExist();
+    // If the destination already exists in your bucket, instead set a generation-match
+    // precondition:
+    // Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();
+
     Storage.ComposeRequest composeRequest =
         Storage.ComposeRequest.newBuilder()
             // addSource takes varargs, so you can put as many objects here as you want, up to the
             // max of 32
             .addSource(firstObjectName, secondObjectName)
             .setTarget(BlobInfo.newBuilder(bucketName, targetObjectName).build())
+            .setTargetOptions(precondition)
             .build();
 
     Blob compositeObject = storage.compose(composeRequest);

samples/snippets/src/main/java/com/example/storage/object/CopyObject.java

@@ -17,7 +17,8 @@
 package com.example.storage.object;
 
 // [START storage_copy_file]
-import com.google.cloud.storage.Blob;
+
+import com.google.cloud.storage.BlobId;
 import com.google.cloud.storage.Storage;
 import com.google.cloud.storage.StorageOptions;
 
@@ -34,14 +35,25 @@ public static void copyObject(
     // String objectName = "your-object-name";
 
     // The ID of the bucket to copy the object to
-    // String targetBucketName = "target-object-bucket"
+    // String targetBucketName = "target-object-bucket";
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
-    Blob blob = storage.get(sourceBucketName, objectName);
+    BlobId source = BlobId.of(sourceBucketName, objectName);
+    BlobId target =
+        BlobId.of(
+            targetBucketName, objectName); // you could change "objectName" to rename the object
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request returns a 412 error if the
+    // preconditions are not met.
+    // For a target object that does not yet exist, set the DoesNotExist precondition.
+    Storage.BlobTargetOption precondition = Storage.BlobTargetOption.doesNotExist();
+    // If the destination already exists in your bucket, instead set a generation-match
+    // precondition:
+    // Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();
 
-    // This keeps the original name, you could also do
-    // copyTo(targetBucketName, "target-object-name") to change the name
-    blob.copyTo(targetBucketName);
+    storage.copy(
+        Storage.CopyRequest.newBuilder().setSource(source).setTarget(target, precondition).build());
 
     System.out.println(
         "Copied object "

samples/snippets/src/main/java/com/example/storage/object/CopyOldVersionOfObject.java

@@ -44,10 +44,20 @@ public static void copyOldVersionOfObject(
     // String newObjectName = "your-new-object";
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request returns a 412 error if the
+    // preconditions are not met.
+    // For a target object that does not yet exist, set the DoesNotExist precondition.
+    Storage.BlobTargetOption precondition = Storage.BlobTargetOption.doesNotExist();
+    // If the destination already exists in your bucket, instead set a generation-match
+    // precondition:
+    // Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();
+
     Storage.CopyRequest copyRequest =
         Storage.CopyRequest.newBuilder()
             .setSource(BlobId.of(bucketName, objectToCopy, generationToCopy))
-            .setTarget(BlobId.of(bucketName, newObjectName))
+            .setTarget(BlobId.of(bucketName, newObjectName), precondition)
             .build();
     storage.copy(copyRequest);
 

samples/snippets/src/main/java/com/example/storage/object/DeleteObject.java

@@ -17,6 +17,7 @@
 package com.example.storage.object;
 
 // [START storage_delete_file]
+import com.google.cloud.storage.Blob;
 import com.google.cloud.storage.Storage;
 import com.google.cloud.storage.StorageOptions;
 
@@ -32,7 +33,19 @@ public static void deleteObject(String projectId, String bucketName, String obje
     // String objectName = "your-object-name";
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
-    storage.delete(bucketName, objectName);
+    Blob blob = storage.get(bucketName, objectName);
+    if (blob == null) {
+      System.out.println("The object " + objectName + " wasn't found in " + bucketName);
+      return;
+    }
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request to upload returns a 412 error if
+    // the object's generation number does not match your precondition.
+    Storage.BlobSourceOption precondition =
+        Storage.BlobSourceOption.generationMatch(blob.getGeneration());
+
+    storage.delete(bucketName, objectName, precondition);
 
     System.out.println("Object " + objectName + " was deleted from " + bucketName);
   }

samples/snippets/src/main/java/com/example/storage/object/MoveObject.java

@@ -17,8 +17,9 @@
 package com.example.storage.object;
 
 // [START storage_move_file]
+
 import com.google.cloud.storage.Blob;
-import com.google.cloud.storage.CopyWriter;
+import com.google.cloud.storage.BlobId;
 import com.google.cloud.storage.Storage;
 import com.google.cloud.storage.StorageOptions;
 
@@ -45,13 +46,25 @@ public static void moveObject(
     // String targetObjectName = "your-new-object-name";
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
-    Blob blob = storage.get(sourceBucketName, sourceObjectName);
-    // Write a copy of the object to the target bucket
-    CopyWriter copyWriter = blob.copyTo(targetBucketName, targetObjectName);
-    Blob copiedBlob = copyWriter.getResult();
+    BlobId source = BlobId.of(sourceBucketName, sourceObjectName);
+    BlobId target = BlobId.of(targetBucketName, targetObjectName);
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request returns a 412 error if the
+    // preconditions are not met.
+    // For a target object that does not yet exist, set the DoesNotExist precondition.
+    Storage.BlobTargetOption precondition = Storage.BlobTargetOption.doesNotExist();
+    // If the destination already exists in your bucket, instead set a generation-match
+    // precondition:
+    // Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();
+
+    // Copy source object to target object
+    storage.copy(
+        Storage.CopyRequest.newBuilder().setSource(source).setTarget(target, precondition).build());
+    Blob copiedObject = storage.get(target);
     // Delete the original blob now that we've copied to where we want it, finishing the "move"
     // operation
-    blob.delete();
+    storage.get(source).delete();
 
     System.out.println(
         "Moved object "
@@ -61,7 +74,7 @@ public static void moveObject(
             + " to "
             + targetObjectName
             + " in bucket "
-            + copiedBlob.getBucket());
+            + copiedObject.getBucket());
   }
 }
 // [END storage_move_file]

samples/snippets/src/main/java/com/example/storage/object/RotateObjectEncryptionKey.java

@@ -17,6 +17,7 @@
 package com.example.storage.object;
 
 // [START storage_rotate_encryption_key]
+import com.google.cloud.storage.Blob;
 import com.google.cloud.storage.BlobId;
 import com.google.cloud.storage.Storage;
 import com.google.cloud.storage.StorageOptions;
@@ -48,11 +49,24 @@ public static void rotateObjectEncryptionKey(
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
     BlobId blobId = BlobId.of(bucketName, objectName);
+    Blob blob = storage.get(blobId);
+    if (blob == null) {
+      System.out.println("The object " + objectName + " wasn't found in " + bucketName);
+      return;
+    }
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request to upload returns a 412 error if
+    // the object's generation number does not match your precondition.
+    Storage.BlobSourceOption precondition =
+        Storage.BlobSourceOption.generationMatch(blob.getGeneration());
+
     // You can't change an object's encryption key directly, the only way is to overwrite the object
     Storage.CopyRequest request =
         Storage.CopyRequest.newBuilder()
             .setSource(blobId)
-            .setSourceOptions(Storage.BlobSourceOption.decryptionKey(oldEncryptionKey))
+            .setSourceOptions(
+                Storage.BlobSourceOption.decryptionKey(oldEncryptionKey), precondition)
             .setTarget(blobId, Storage.BlobTargetOption.encryptionKey(newEncryptionKey))
             .build();
     storage.copy(request);

samples/snippets/src/main/java/com/example/storage/object/UploadEncryptedObject.java

@@ -48,10 +48,21 @@ public static void uploadEncryptedObject(
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
     BlobId blobId = BlobId.of(bucketName, objectName);
     BlobInfo blobInfo = BlobInfo.newBuilder(blobId).build();
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request returns a 412 error if the
+    // preconditions are not met.
+    // For a target object that does not yet exist, set the DoesNotExist precondition.
+    Storage.BlobTargetOption precondition = Storage.BlobTargetOption.doesNotExist();
+    // If the destination already exists in your bucket, instead set a generation-match
+    // precondition:
+    // Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();
+
     storage.create(
         blobInfo,
         Files.readAllBytes(Paths.get(filePath)),
-        Storage.BlobTargetOption.encryptionKey(encryptionKey));
+        Storage.BlobTargetOption.encryptionKey(encryptionKey),
+        precondition);
 
     System.out.println(
         "File "

samples/snippets/src/main/java/com/example/storage/object/UploadKmsEncryptedObject.java

@@ -45,7 +45,17 @@ public static void uploadKmsEncryptedObject(
 
     BlobId blobId = BlobId.of(bucketName, objectName);
     BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
-    storage.create(blobInfo, data, Storage.BlobTargetOption.kmsKeyName(kmsKeyName));
+
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request returns a 412 error if the
+    // preconditions are not met.
+    // For a target object that does not yet exist, set the DoesNotExist precondition.
+    Storage.BlobTargetOption precondition = Storage.BlobTargetOption.doesNotExist();
+    // If the destination already exists in your bucket, instead set a generation-match
+    // precondition:
+    // Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();
+
+    storage.create(blobInfo, data, Storage.BlobTargetOption.kmsKeyName(kmsKeyName), precondition);
 
     System.out.println(
         "Uploaded object "