docs: add samples for soft delete (objects) (#2754)

* feat: add samples for soft delete (objects)

* seperate calls; run lint

* style issues

* one more lint issue

* fix test issue

* create test-specific bucket in restore test

* format

samples/snippets/src/main/java/com/example/storage/ConfigureRetries.java

@@ -35,8 +35,7 @@ public static void main(String[] args) {
   static void deleteBlob(String bucketName, String blobName) {
     // Customize retry behavior
     RetrySettings retrySettings =
-        StorageOptions.getDefaultRetrySettings()
-            .toBuilder()
+        StorageOptions.getDefaultRetrySettings().toBuilder()
             // Set the max number of attempts to 10 (initial attempt plus 9 retries)
             .setMaxAttempts(10)
             // Set the backoff multiplier to 3.0

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

@@ -31,8 +31,7 @@ public static void disableRequesterPays(String projectId, String bucketName) {
 
     Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
     Bucket bucket = storage.get(bucketName, Storage.BucketGetOption.userProject(projectId));
-    bucket
-        .toBuilder()
+    bucket.toBuilder()
         .setRequesterPays(false)
         .build()
         .update(Storage.BucketTargetOption.userProject(projectId));

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

@@ -0,0 +1,48 @@
+/*
+ * 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.Bucket;
+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();
+    Bucket bucket = storage.get(bucketName);
+    bucket.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/EnableLifecycleManagement.java

@@ -40,8 +40,7 @@ public static void enableLifecycleManagement(String projectId, String bucketName
     // See the LifecycleRule documentation for additional info on what you can do with lifecycle
     // management rules. This one deletes objects that are over 100 days old.
     // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/BucketInfo.LifecycleRule.html
-    bucket
-        .toBuilder()
+    bucket.toBuilder()
         .setLifecycleRules(
             ImmutableList.of(
                 new LifecycleRule(

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

@@ -43,8 +43,7 @@ public static void enableUniformBucketLevelAccess(String projectId, String bucke
         BucketInfo.IamConfiguration.newBuilder().setIsUniformBucketLevelAccessEnabled(true).build();
 
     storage.update(
-        bucket
-            .toBuilder()
+        bucket.toBuilder()
             .setIamConfiguration(iamConfiguration)
             .setAcl(null)
             .setDefaultAcl(null)

samples/snippets/src/main/java/com/example/storage/bucket/GetSoftDeletePolicy.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_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/MakeBucketPublic.java

@@ -35,8 +35,7 @@ public static void makeBucketPublic(String projectId, String bucketName) {
     Policy originalPolicy = storage.getIamPolicy(bucketName);
     storage.setIamPolicy(
         bucketName,
-        originalPolicy
-            .toBuilder()
+        originalPolicy.toBuilder()
             .addIdentity(StorageRoles.objectViewer(), Identity.allUsers()) // All users can view
             .build());
 

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

@@ -49,8 +49,7 @@ public static void setBucketAutoclass(
       Bucket bucket = storage.get(bucketName);
 
       Bucket toUpdate =
-          bucket
-              .toBuilder()
+          bucket.toBuilder()
               .setAutoclass(
                   Autoclass.newBuilder()
                       .setEnabled(enabled)

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

@@ -34,8 +34,7 @@ public static void setPublicAccessPreventionEnforced(String projectId, String bu
     Bucket bucket = storage.get(bucketName);
 
     // Enforces public access prevention for the bucket
-    bucket
-        .toBuilder()
+    bucket.toBuilder()
         .setIamConfiguration(
             BucketInfo.IamConfiguration.newBuilder()
                 .setPublicAccessPrevention(BucketInfo.PublicAccessPrevention.ENFORCED)

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

@@ -34,8 +34,7 @@ public static void setPublicAccessPreventionInherited(String projectId, String b
     Bucket bucket = storage.get(bucketName);
 
     // Sets public access prevention to 'inherited' for the bucket
-    bucket
-        .toBuilder()
+    bucket.toBuilder()
         .setIamConfiguration(
             BucketInfo.IamConfiguration.newBuilder()
                 .setPublicAccessPrevention(BucketInfo.PublicAccessPrevention.INHERITED)

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

@@ -43,8 +43,7 @@ public static void setRetentionPolicy(
     Bucket bucket = storage.get(bucketName);
     Bucket bucketWithRetentionPolicy =
         storage.update(
-            bucket
-                .toBuilder()
+            bucket.toBuilder()
                 .setRetentionPeriodDuration(Duration.ofSeconds(retentionPeriodSeconds))
                 .build(),
             BucketTargetOption.metagenerationMatch());

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

@@ -0,0 +1,48 @@
+/*
+ * 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.Bucket;
+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();
+    Bucket bucket = storage.get(bucketName);
+    bucket.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,41 @@
+/*
+ * 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,51 @@
+/*
+ * 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,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.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]