fix: add missing preconditions and update samples (#1753)

Author: JesseLovelace

google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java

@@ -626,6 +626,24 @@ public static BlobTargetOption generationMatch() {
       return new BlobTargetOption(UnifiedOpts.generationMatchExtractor());
     }
 
+    /**
+     * Returns an option for blob's data generation match. If this option is used the request will
+     * fail if blob's generation does not match the provided value.
+     */
+    @TransportCompatibility({Transport.HTTP, Transport.GRPC})
+    public static BlobTargetOption generationMatch(long generation) {
+      return new BlobTargetOption(UnifiedOpts.generationMatch(generation));
+    }
+
+    /**
+     * Returns an option for blob's data generation mismatch. If this option is used the request
+     * will fail if generation matches the provided value.
+     */
+    @TransportCompatibility({Transport.HTTP, Transport.GRPC})
+    public static BlobTargetOption generationNotMatch(long generation) {
+      return new BlobTargetOption(UnifiedOpts.generationNotMatch(generation));
+    }
+
     /**
      * Returns an option for blob's data generation mismatch. If this option is used the request
      * will fail if generation matches.
@@ -644,6 +662,24 @@ public static BlobTargetOption metagenerationMatch() {
       return new BlobTargetOption(UnifiedOpts.metagenerationMatchExtractor());
     }
 
+    /**
+     * Returns an option for blob's metageneration match. If this option is used the request will
+     * fail if blob's metageneration does not match the provided value.
+     */
+    @TransportCompatibility({Transport.HTTP, Transport.GRPC})
+    public static BlobTargetOption metagenerationMatch(long metageneration) {
+      return new BlobTargetOption(UnifiedOpts.metagenerationMatch(metageneration));
+    }
+
+    /**
+     * Returns an option for blob's metageneration mismatch. If this option is used the request will
+     * fail if metageneration matches the provided value.
+     */
+    @TransportCompatibility({Transport.HTTP, Transport.GRPC})
+    public static BlobTargetOption metagenerationNotMatch(long metageneration) {
+      return new BlobTargetOption(UnifiedOpts.metagenerationNotMatch(metageneration));
+    }
+
     /**
      * Returns an option for blob's metageneration mismatch. If this option is used the request will
      * fail if metageneration matches.

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

@@ -49,11 +49,19 @@ public static void composeObject(
     // 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.BlobTargetOption precondition;
+    if (storage.get(bucketName, targetObjectName) == null) {
+      // For a target object that does not yet exist, set the DoesNotExist precondition.
+      // This will cause the request to fail if the object is created before the request runs.
+      precondition = Storage.BlobTargetOption.doesNotExist();
+    } else {
+      // If the destination already exists in your bucket, instead set a generation-match
+      // precondition. This will cause the request to fail if the existing object's generation
+      // changes before the request runs.
+      precondition =
+          Storage.BlobTargetOption.generationMatch(
+              storage.get(bucketName, targetObjectName).getGeneration());
+    }
 
     Storage.ComposeRequest composeRequest =
         Storage.ComposeRequest.newBuilder()

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

@@ -46,11 +46,20 @@ public static void copyObject(
     // 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.BlobTargetOption precondition;
+    if (storage.get(targetBucketName, objectName) == null) {
+      // For a target object that does not yet exist, set the DoesNotExist precondition.
+      // This will cause the request to fail if the object is created before the request runs.
+      precondition = Storage.BlobTargetOption.doesNotExist();
+
+    } else {
+      // If the destination already exists in your bucket, instead set a generation-match
+      // precondition. This will cause the request to fail if the existing object's generation
+      // changes before the request runs.
+      precondition =
+          Storage.BlobTargetOption.generationMatch(
+              storage.get(targetBucketName, objectName).getGeneration());
+    }
 
     storage.copy(
         Storage.CopyRequest.newBuilder().setSource(source).setTarget(target, precondition).build());

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

@@ -48,11 +48,19 @@ public static void copyOldVersionOfObject(
     // 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.BlobTargetOption precondition;
+    if (storage.get(bucketName, newObjectName) == null) {
+      // For a target object that does not yet exist, set the DoesNotExist precondition.
+      // This will cause the request to fail if the object is created before the request runs.
+      precondition = Storage.BlobTargetOption.doesNotExist();
+    } else {
+      // If the destination already exists in your bucket, instead set a generation-match
+      // precondition. This will cause the request to fail if the existing object's generation
+      // changes before the request runs.
+      precondition =
+          Storage.BlobTargetOption.generationMatch(
+              storage.get(bucketName, newObjectName).getGeneration());
+    }
 
     Storage.CopyRequest copyRequest =
         Storage.CopyRequest.newBuilder()

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

@@ -52,11 +52,19 @@ public static void moveObject(
     // 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.BlobTargetOption precondition;
+    if (storage.get(targetBucketName, targetObjectName) == null) {
+      // For a target object that does not yet exist, set the DoesNotExist precondition.
+      // This will cause the request to fail if the object is created before the request runs.
+      precondition = Storage.BlobTargetOption.doesNotExist();
+    } else {
+      // If the destination already exists in your bucket, instead set a generation-match
+      // precondition. This will cause the request to fail if the existing object's generation
+      // changes before the request runs.
+      precondition =
+          Storage.BlobTargetOption.generationMatch(
+              storage.get(targetBucketName, targetObjectName).getGeneration());
+    }
 
     // Copy source object to target object
     storage.copy(

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

@@ -52,11 +52,19 @@ public static void uploadEncryptedObject(
     // 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.BlobTargetOption precondition;
+    if (storage.get(bucketName, objectName) == null) {
+      // For a target object that does not yet exist, set the DoesNotExist precondition.
+      // This will cause the request to fail if the object is created before the request runs.
+      precondition = Storage.BlobTargetOption.doesNotExist();
+    } else {
+      // If the destination already exists in your bucket, instead set a generation-match
+      // precondition. This will cause the request to fail if the existing object's generation
+      // changes before the request runs.
+      precondition =
+          Storage.BlobTargetOption.generationMatch(
+              storage.get(bucketName, objectName).getGeneration());
+    }
 
     storage.create(
         blobInfo,

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

@@ -49,11 +49,19 @@ public static void uploadKmsEncryptedObject(
     // 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.BlobTargetOption precondition;
+    if (storage.get(bucketName, objectName) == null) {
+      // For a target object that does not yet exist, set the DoesNotExist precondition.
+      // This will cause the request to fail if the object is created before the request runs.
+      precondition = Storage.BlobTargetOption.doesNotExist();
+    } else {
+      // If the destination already exists in your bucket, instead set a generation-match
+      // precondition. This will cause the request to fail if the existing object's generation
+      // changes before the request runs.
+      precondition =
+          Storage.BlobTargetOption.generationMatch(
+              storage.get(bucketName, objectName).getGeneration());
+    }
 
     storage.create(blobInfo, data, Storage.BlobTargetOption.kmsKeyName(kmsKeyName), precondition);
 

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

@@ -41,18 +41,26 @@ public static void uploadObject(
     // The path to your file to upload
     // String filePath = "path/to/your/file"
 
-    // 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 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.
+    Storage.BlobTargetOption precondition;
+    if (storage.get(bucketName, objectName) == null) {
+      // For a target object that does not yet exist, set the DoesNotExist precondition.
+      // This will cause the request to fail if the object is created before the request runs.
+      precondition = Storage.BlobTargetOption.doesNotExist();
+    } else {
+      // If the destination already exists in your bucket, instead set a generation-match
+      // precondition. This will cause the request to fail if the existing object's generation
+      // changes before the request runs.
+      precondition =
+          Storage.BlobTargetOption.generationMatch(
+              storage.get(bucketName, objectName).getGeneration());
+    }
     storage.create(blobInfo, Files.readAllBytes(Paths.get(filePath)), precondition);
 
     System.out.println(