samples(feat): add storage_move_object sample (#3191)

Rename existing MoveObject class to CopyDeleteObject to make it clear there is a copy and delete happening, not a move. (sample name is left `storage_move_file`).

Author: BenWhitehead

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

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.storage.object;
+
+// [START storage_move_object]
+
+import com.google.cloud.storage.BlobId;
+import com.google.cloud.storage.BlobInfo;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.Storage.MoveBlobRequest;
+import com.google.cloud.storage.StorageOptions;
+
+public final class AtomicMoveObject {
+
+  public static void moveObject(
+      String projectId, String bucketName, String sourceObjectName, String targetObjectName) {
+
+    // The ID of your GCP project
+    // String projectId = "your-project-id";
+
+    // The ID of your GCS bucket
+    // String bucketName = "your-unique-bucket-name";
+
+    // The ID of your GCS object
+    // String sourceObjectName = "your-object-name";
+
+    // The ID of your GCS object
+    // String targetObjectName = "your-new-object-name";
+
+    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+    BlobId source = BlobId.of(bucketName, sourceObjectName);
+    BlobId target = BlobId.of(bucketName, 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.
+    Storage.BlobTargetOption precondition;
+    BlobInfo existingTarget = storage.get(target);
+    if (existingTarget == 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(existingTarget.getGeneration());
+    }
+
+    // Atomically move source object to target object within the bucket
+    MoveBlobRequest moveBlobRequest =
+        MoveBlobRequest.newBuilder()
+            .setSource(source)
+            .setTarget(target)
+            .setTargetOptions(precondition)
+            .build();
+    BlobInfo movedBlob = storage.moveBlob(moveBlobRequest);
+
+    System.out.println(
+        "Moved object "
+            + source.toGsUtilUri()
+            + " to "
+            + movedBlob.getBlobId().toGsUtilUriWithGeneration());
+  }
+}
+// [END storage_move_object]

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

@@ -20,11 +20,12 @@
 
 import com.google.cloud.storage.Blob;
 import com.google.cloud.storage.BlobId;
+import com.google.cloud.storage.BlobInfo;
 import com.google.cloud.storage.Storage;
 import com.google.cloud.storage.StorageOptions;
 
-public class MoveObject {
-  public static void moveObject(
+public class CopyDeleteObject {
+  public static void copyDeleteObject(
       String projectId,
       String sourceBucketName,
       String sourceObjectName,
@@ -34,7 +35,7 @@ public static void moveObject(
     // String projectId = "your-project-id";
 
     // The ID of your GCS bucket
-    // String bucketName = "your-unique-bucket-name";
+    // String sourceBucketName = "your-unique-bucket-name";
 
     // The ID of your GCS object
     // String sourceObjectName = "your-object-name";
@@ -53,17 +54,16 @@ public static void moveObject(
     // conditions and data corruptions. The request returns a 412 error if the
     // preconditions are not met.
     Storage.BlobTargetOption precondition;
-    if (storage.get(targetBucketName, targetObjectName) == null) {
+    BlobInfo existingTarget = storage.get(targetBucketName, targetObjectName);
+    if (existingTarget == 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());
+      precondition = Storage.BlobTargetOption.generationMatch(existingTarget.getGeneration());
     }
 
     // Copy source object to target object

samples/snippets/src/test/java/com/example/storage/ITObjectSnippets.java

@@ -26,10 +26,12 @@
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertTrue;
 
+import com.example.storage.object.AtomicMoveObject;
 import com.example.storage.object.BatchSetObjectMetadata;
 import com.example.storage.object.ChangeObjectCsekToKms;
 import com.example.storage.object.ChangeObjectStorageClass;
 import com.example.storage.object.ComposeObject;
+import com.example.storage.object.CopyDeleteObject;
 import com.example.storage.object.CopyObject;
 import com.example.storage.object.CopyOldVersionOfObject;
 import com.example.storage.object.DeleteObject;
@@ -48,7 +50,6 @@
 import com.example.storage.object.ListSoftDeletedObjects;
 import com.example.storage.object.ListSoftDeletedVersionsOfObject;
 import com.example.storage.object.MakeObjectPublic;
-import com.example.storage.object.MoveObject;
 import com.example.storage.object.RestoreSoftDeletedObject;
 import com.example.storage.object.RotateObjectEncryptionKey;
 import com.example.storage.object.SetObjectMetadata;
@@ -258,7 +259,7 @@ public void testListObjectsWithPrefix() {
   }
 
   @Test
-  public void testMoveObject() throws Exception {
+  public void testCopyDeleteObject() throws Exception {
     String blob = generator.randomObjectName();
     String newBlob = generator.randomObjectName();
 
@@ -270,12 +271,25 @@ public void testMoveObject() throws Exception {
 
       String newBucket = tmpBucket.getBucket().getName();
       BlobInfo gen1 = storage.create(BlobInfo.newBuilder(BlobId.of(newBucket, blob)).build());
-      MoveObject.moveObject(GOOGLE_CLOUD_PROJECT, newBucket, blob, newBucket, newBlob);
+      CopyDeleteObject.copyDeleteObject(GOOGLE_CLOUD_PROJECT, newBucket, blob, newBucket, newBlob);
       assertNotNull(storage.get(newBucket, newBlob));
       assertNull(storage.get(bucket.getName(), blob));
     }
   }
 
+  @Test
+  public void testAtomicMoveObject() {
+    String blob1 = generator.randomObjectName();
+    String blob2 = generator.randomObjectName();
+
+    String bucketName = bucket.getName();
+    BlobInfo gen1 = storage.create(BlobInfo.newBuilder(BlobId.of(bucketName, blob1)).build());
+    AtomicMoveObject.moveObject(GOOGLE_CLOUD_PROJECT, bucketName, blob1, blob2);
+    assertThat(storage.get(bucketName, blob1)).isNull();
+    assertThat(storage.get(bucketName, blob2)).isNotNull();
+    assertThat(stdOut.getCapturedOutputAsUtf8String()).contains("Moved object");
+  }
+
   @Test
   public void testSetObjectMetadata() {
     String bucketName = bucket.getName();