docs: add samples for soft delete (objects)

samples/snippets/src/main/java/com/example/storage/bucket/DisableSoftDelete.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2024 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.bucket;
+
+// [START storage_disable_soft_delete]
+import com.google.cloud.storage.BucketInfo;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+
+import java.time.Duration;
+
+public class DisableSoftDelete {
+    public static void disableSoftDelete(String projectId, String bucketName) {
+        // The ID of your GCP project
+        // String projectId = "your-project-id";
+
+        // The ID of your GCS bucket
+        // String bucketName = "your-unique-bucket-name";
+
+        Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+        storage.get(bucketName).toBuilder().setSoftDeletePolicy(
+                // Setting the retention duration to 0 disables Soft Delete.
+                BucketInfo.SoftDeletePolicy.newBuilder().setRetentionDuration(Duration.ofSeconds(0)).build()
+        ).build().update();
+
+        System.out.println("Soft delete for " + bucketName + " was disabled");
+    }
+}
+// [END storage_disable_soft_delete]
+

samples/snippets/src/main/java/com/example/storage/bucket/GetSoftDeletePolicy.java

@@ -0,0 +1,30 @@
+package com.example.storage.bucket;
+
+// [START storage_get_soft_delete_policy]
+import com.google.cloud.storage.BucketInfo.SoftDeletePolicy;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+
+import java.time.Duration;
+
+public class GetSoftDeletePolicy {
+    public static void getSoftDeletePolicy(String projectId, String bucketName) {
+        // The ID of your GCP project
+        // String projectId = "your-project-id";
+
+        // The ID of your GCS bucket
+        // String bucketName = "your-unique-bucket-name";
+
+        Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+        SoftDeletePolicy policy = storage.get(bucketName).getSoftDeletePolicy();
+
+        if (Duration.ofSeconds(0).equals(policy.getRetentionDuration())){
+            System.out.println("Soft delete is disabled for " + bucketName);
+        } else {
+            System.out.println("The soft delete policy for "+ bucketName + " is:");
+            System.out.println(policy);
+        }
+    }
+}
+// [END storage_get_soft_delete_policy]
+

samples/snippets/src/main/java/com/example/storage/bucket/SetSoftDeletePolicy.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2024 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.bucket;
+
+// [START storage_set_soft_delete_policy]
+import com.google.cloud.storage.BucketInfo;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+
+import java.time.Duration;
+
+public class SetSoftDeletePolicy {
+    public static void setSoftDeletePolicy(String projectId, String bucketName) {
+        // The ID of your GCP project
+        // String projectId = "your-project-id";
+
+        // The ID of your GCS bucket
+        // String bucketName = "your-unique-bucket-name";
+
+        Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+        storage.get(bucketName).toBuilder().setSoftDeletePolicy(
+                BucketInfo.SoftDeletePolicy.newBuilder().setRetentionDuration(Duration.ofDays(10)).build()
+        ).build().update();
+
+        System.out.println("Soft delete policy for " + bucketName + " was set to a 10-day retention period");
+    }
+}
+// [END storage_set_soft_delete_policy]
+

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

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2024 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_list_soft_deleted_objects]
+import com.google.api.gax.paging.Page;
+import com.google.cloud.storage.Blob;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+
+public class ListSoftDeletedObjects {
+    public static void listSoftDeletedObjects(String projectId, String bucketName) {
+        // The ID of your GCP project
+        // String projectId = "your-project-id";
+
+        // The ID of your GCS bucket
+        // String bucketName = "your-unique-bucket-name";
+
+        Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+        Page<Blob> blobs =
+                storage.list(
+                        bucketName,
+                        Storage.BlobListOption.softDeleted(true));
+
+        for (Blob blob : blobs.iterateAll()) {
+            System.out.println(blob.getName());
+        }
+    }
+}
+// [END storage_list_soft_deleted_objects]
+

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

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2024 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_list_soft_deleted_object_versions]
+import com.google.api.gax.paging.Page;
+import com.google.cloud.storage.Blob;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+
+public class ListSoftDeletedVersionsOfObject {
+
+    public static void listSoftDeletedVersionOfObject(String projectId, String bucketName, String objectName) {
+        // The ID of your GCP project
+        // String projectId = "your-project-id";
+
+        // The ID of your GCS bucket
+        // String bucketName = "your-unique-bucket-name";
+
+        // The name of your GCS object
+        // String objectName = "your-object-name";
+
+        Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+        Page<Blob> blobs =
+                storage.list(
+                        bucketName,
+                        Storage.BlobListOption.softDeleted(true),
+                        // See https://cloud.google.com/storage/docs/json_api/v1/objects/list#matchGlob
+                        Storage.BlobListOption.matchGlob(objectName));
+
+        for (Blob blob : blobs.iterateAll()) {
+            System.out.println(blob.getName());
+        }
+    }
+}
+// [END storage_list_soft_deleted_object_versions]

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

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2024 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_restore_object]
+import com.google.cloud.storage.Blob;
+import com.google.cloud.storage.BlobId;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+
+public class RestoreSoftDeletedObject {
+    public static void RestoreSoftDeletedObject(String projectId, String bucketName, String objectName, long generation) {
+        // The ID of your GCP project
+        // String projectId = "your-project-id";
+
+        // The ID of your GCS bucket
+        // String bucketName = "your-unique-bucket-name";
+
+        // The name of your GCS object
+        // String objectName = "your-object-name";
+
+        Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+        Blob blob = storage.restore(BlobId.of(bucketName, objectName, generation));
+
+        System.out.println("Restored previously soft-deleted object " + blob.getName());
+    }
+}
+// [END storage_restore_object]

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

@@ -20,6 +20,7 @@
 import static org.junit.Assert.assertArrayEquals;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertTrue;
@@ -38,6 +39,7 @@
 import com.example.storage.bucket.DisableDefaultEventBasedHold;
 import com.example.storage.bucket.DisableLifecycleManagement;
 import com.example.storage.bucket.DisableRequesterPays;
+import com.example.storage.bucket.DisableSoftDelete;
 import com.example.storage.bucket.DisableUniformBucketLevelAccess;
 import com.example.storage.bucket.EnableBucketVersioning;
 import com.example.storage.bucket.EnableDefaultEventBasedHold;
@@ -68,6 +70,7 @@
 import com.example.storage.bucket.SetPublicAccessPreventionEnforced;
 import com.example.storage.bucket.SetPublicAccessPreventionInherited;
 import com.example.storage.bucket.SetRetentionPolicy;
+import com.example.storage.bucket.SetSoftDeletePolicy;
 import com.example.storage.object.DownloadRequesterPaysObject;
 import com.example.storage.object.ReleaseEventBasedHold;
 import com.example.storage.object.ReleaseTemporaryHold;
@@ -77,6 +80,7 @@
 import com.google.cloud.Identity;
 import com.google.cloud.ServiceOptions;
 import com.google.cloud.storage.Blob;
+import com.google.cloud.storage.BlobId;
 import com.google.cloud.storage.BlobInfo;
 import com.google.cloud.storage.Bucket;
 import com.google.cloud.storage.BucketInfo;
@@ -702,4 +706,30 @@ public void testCreateBucketWithObjectRetention() {
       storage.delete(tempBucket);
     }
   }
+
+  @Test
+  public void testSetSoftDeletePolicy() {
+    String tempBucket = RemoteStorageHelper.generateBucketName();
+    Bucket bucket = storage.create(BucketInfo.of(tempBucket));
+    try {
+      assertNotEquals(java.time.Duration.ofDays(10), bucket.getSoftDeletePolicy().getRetentionDuration());
+      SetSoftDeletePolicy.setSoftDeletePolicy(PROJECT_ID, tempBucket);
+      assertEquals(java.time.Duration.ofDays(10), storage.get(tempBucket).getSoftDeletePolicy().getRetentionDuration());
+    } finally {
+      storage.delete(tempBucket);
+    }
+  }
+
+  @Test
+  public void testDisableSoftDelete() {
+    String tempBucket = RemoteStorageHelper.generateBucketName();
+    Bucket bucket = storage.create(BucketInfo.of(tempBucket));
+    try {
+      assertNotEquals(java.time.Duration.ofDays(0), bucket.getSoftDeletePolicy().getRetentionDuration());
+      DisableSoftDelete.disableSoftDelete(PROJECT_ID, tempBucket);
+      assertEquals(java.time.Duration.ofSeconds(0), storage.get(tempBucket).getSoftDeletePolicy().getRetentionDuration());
+    } finally {
+      storage.delete(tempBucket);
+    }
+  }
 }