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(