docs: add samples for object retention (#2417)

JesseLovelace · gcf-owl-bot[bot] · web-flow · commit 45837d33a88d · 2024-02-26T13:55:14.000-08:00
* docs: add samples for object retention * docs: add samples for object retention * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * run formatter * fix checkstyle issue * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * remove unecessary tostring * add retention to metadata test * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
diff --git a/README.md b/README.md
@@ -237,6 +237,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-storage/tree/
 | Create Bucket | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/bucket/CreateBucket.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/bucket/CreateBucket.java) |
 | Create Bucket Dual Region | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketDualRegion.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketDualRegion.java) |
 | Create Bucket Pub Sub Notification | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketPubSubNotification.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketPubSubNotification.java) |
+| Create Bucket With Object Retention | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithObjectRetention.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithObjectRetention.java) |
 | Create Bucket With Storage Class And Location | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithStorageClassAndLocation.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithStorageClassAndLocation.java) |
 | Create Bucket With Turbo Replication | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithTurboReplication.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithTurboReplication.java) |
 | Delete Bucket | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/bucket/DeleteBucket.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/bucket/DeleteBucket.java) |
@@ -322,6 +323,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-storage/tree/
 | Rotate Object Encryption Key | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/object/RotateObjectEncryptionKey.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/object/RotateObjectEncryptionKey.java) |
 | Set Event Based Hold | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/object/SetEventBasedHold.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/object/SetEventBasedHold.java) |
 | Set Object Metadata | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/object/SetObjectMetadata.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/object/SetObjectMetadata.java) |
+| Set Object Retention Policy | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/object/SetObjectRetentionPolicy.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/object/SetObjectRetentionPolicy.java) |
 | Set Temporary Hold | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/object/SetTemporaryHold.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/object/SetTemporaryHold.java) |
 | Stream Object Download | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/object/StreamObjectDownload.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/object/StreamObjectDownload.java) |
 | Stream Object Upload | [source code](https://github.com/googleapis/java-storage/blob/main/samples/snippets/src/main/java/com/example/storage/object/StreamObjectUpload.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-storage&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/storage/object/StreamObjectUpload.java) |
diff --git a/samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithObjectRetention.java b/samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithObjectRetention.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_create_bucket_with_object_retention]
+
+import com.google.cloud.storage.Bucket;
+import com.google.cloud.storage.BucketInfo;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+
+public class CreateBucketWithObjectRetention {
+  public static void createBucketWithObjectRetention(String projectId, String bucketName) {
+    // The ID of your GCP project
+    // String projectId = "your-project-id";
+
+    // The ID to give your GCS bucket
+    // String bucketName = "your-unique-bucket-name";
+
+    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+
+    Bucket bucket =
+        storage.create(
+            BucketInfo.of(bucketName), Storage.BucketTargetOption.enableObjectRetention(true));
+
+    System.out.println(
+        "Created bucket "
+            + bucket.getName()
+            + " with object retention enabled setting: "
+            + bucket.getObjectRetention().getMode().toString());
+  }
+}
+
+// [END storage_create_bucket_with_object_retention]
diff --git a/samples/snippets/src/main/java/com/example/storage/bucket/GetBucketMetadata.java b/samples/snippets/src/main/java/com/example/storage/bucket/GetBucketMetadata.java
@@ -56,6 +56,7 @@ public static void getBucketMetadata(String projectId, String bucketName) {
     System.out.println("StorageClass: " + bucket.getStorageClass().name());
     System.out.println("TimeCreated: " + bucket.getCreateTime());
     System.out.println("VersioningEnabled: " + bucket.versioningEnabled());
+    System.out.println("ObjectRetention: " + bucket.getObjectRetention());
     if (bucket.getLabels() != null) {
       System.out.println("\n\n\nLabels:");
       for (Map.Entry<String, String> label : bucket.getLabels().entrySet()) {
diff --git a/samples/snippets/src/main/java/com/example/storage/object/GetObjectMetadata.java b/samples/snippets/src/main/java/com/example/storage/object/GetObjectMetadata.java
@@ -68,6 +68,7 @@ public static void getObjectMetadata(String projectId, String bucketName, String
     System.out.println("StorageClass: " + blob.getStorageClass());
     System.out.println("TimeCreated: " + new Date(blob.getCreateTime()));
     System.out.println("Last Metadata Update: " + new Date(blob.getUpdateTime()));
+    System.out.println("Object Retention Policy: " + blob.getRetention());
     Boolean temporaryHoldIsEnabled = (blob.getTemporaryHold() != null && blob.getTemporaryHold());
     System.out.println("temporaryHold: " + (temporaryHoldIsEnabled ? "enabled" : "disabled"));
     Boolean eventBasedHoldIsEnabled =
diff --git a/samples/snippets/src/main/java/com/example/storage/object/SetObjectRetentionPolicy.java b/samples/snippets/src/main/java/com/example/storage/object/SetObjectRetentionPolicy.java
@@ -0,0 +1,75 @@
+/*
+ * Copyright 2022 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_set_object_retention_policy]
+
+import static java.time.OffsetDateTime.now;
+
+import com.google.cloud.storage.Blob;
+import com.google.cloud.storage.BlobId;
+import com.google.cloud.storage.BlobInfo.Retention;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageException;
+import com.google.cloud.storage.StorageOptions;
+
+public class SetObjectRetentionPolicy {
+  public static void setObjectRetentionPolicy(
+      String projectId, String bucketName, String objectName) throws StorageException {
+    // The ID of your GCP project
+    // String projectId = "your-project-id";
+
+    // The ID of your GCS bucket that has object retention enabled
+    // String bucketName = "your-unique-bucket-name";
+
+    // The ID of your GCS object
+    // String objectName = "your-object-name";
+
+    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
+    BlobId blobId = BlobId.of(bucketName, objectName);
+    Blob blob = storage.get(blobId);
+    if (blob == null) {
+      System.out.println("The object " + objectName + " was not found in " + bucketName);
+      return;
+    }
+
+    Blob updated =
+        blob.toBuilder()
+            .setRetention(
+                Retention.newBuilder()
+                    .setMode(Retention.Mode.UNLOCKED)
+                    .setRetainUntilTime(now().plusDays(10))
+                    .build())
+            .build()
+            .update();
+
+    System.out.println("Retention policy for object " + objectName + " was set to:");
+    System.out.println(updated.getRetention().toString());
+
+    // To modify an existing policy on an Unlocked object, pass in the override parameter
+    blob.toBuilder()
+        .setRetention(
+            updated.getRetention().toBuilder().setRetainUntilTime(now().plusDays(9)).build())
+        .build()
+        .update(Storage.BlobTargetOption.overrideUnlockedRetention(true));
+
+    System.out.println("Retention policy for object " + objectName + " was updated to:");
+    System.out.println(storage.get(blobId).getRetention().toString());
+  }
+}
+
+// [END storage_set_object_retention_policy]
diff --git a/samples/snippets/src/test/java/com/example/storage/ITBucketSnippets.java b/samples/snippets/src/test/java/com/example/storage/ITBucketSnippets.java
@@ -30,6 +30,7 @@
 import com.example.storage.bucket.ChangeDefaultStorageClass;
 import com.example.storage.bucket.ConfigureBucketCors;
 import com.example.storage.bucket.CreateBucket;
+import com.example.storage.bucket.CreateBucketWithObjectRetention;
 import com.example.storage.bucket.CreateBucketWithStorageClassAndLocation;
 import com.example.storage.bucket.CreateBucketWithTurboReplication;
 import com.example.storage.bucket.DeleteBucket;
@@ -265,6 +266,7 @@ public void testGetBucketMetadata() {
     assertTrue(snippetOutput.contains("Labels:"));
     assertTrue(snippetOutput.contains("k=v"));
     assertTrue(snippetOutput.contains("Lifecycle Rules:"));
+    assertTrue(snippetOutput.contains("ObjectRetention: " + bucket.getObjectRetention()));
   }
 
   @Test
@@ -662,10 +664,14 @@ public void testLockRetentionPolicy() {
     String tempBucket = RemoteStorageHelper.generateBucketName();
     Bucket bucket = storage.create(BucketInfo.of(tempBucket));
     assertNotNull(bucket);
-    SetRetentionPolicy.setRetentionPolicy(PROJECT_ID, tempBucket, 5L);
-    assertEquals(5L, (long) storage.get(tempBucket).getRetentionPeriod());
-    LockRetentionPolicy.lockRetentionPolicy(PROJECT_ID, tempBucket);
-    assertTrue(storage.get(tempBucket).retentionPolicyIsLocked());
+    try {
+      SetRetentionPolicy.setRetentionPolicy(PROJECT_ID, tempBucket, 5L);
+      assertEquals(5L, (long) storage.get(tempBucket).getRetentionPeriod());
+      LockRetentionPolicy.lockRetentionPolicy(PROJECT_ID, tempBucket);
+      assertTrue(storage.get(tempBucket).retentionPolicyIsLocked());
+    } finally {
+      storage.delete(tempBucket);
+    }
   }
 
   @Test
@@ -682,4 +688,18 @@ public void testUniformBucketLevelAccess() {
     DisableUniformBucketLevelAccess.disableUniformBucketLevelAccess(PROJECT_ID, BUCKET);
     assertFalse(storage.get(BUCKET).getIamConfiguration().isUniformBucketLevelAccessEnabled());
   }
+
+  @Test
+  public void testCreateBucketWithObjectRetention() {
+    String tempBucket = RemoteStorageHelper.generateBucketName();
+
+    try {
+      CreateBucketWithObjectRetention.createBucketWithObjectRetention(PROJECT_ID, tempBucket);
+      assertNotNull(storage.get(tempBucket).getObjectRetention());
+      String snippetOutput = stdOutCaptureRule.getCapturedOutputAsUtf8String();
+      assertTrue(snippetOutput.contains("Enabled"));
+    } finally {
+      storage.delete(tempBucket);
+    }
+  }
 }
diff --git a/samples/snippets/src/test/java/com/example/storage/ITObjectSnippets.java b/samples/snippets/src/test/java/com/example/storage/ITObjectSnippets.java
@@ -47,6 +47,7 @@
 import com.example.storage.object.MoveObject;
 import com.example.storage.object.RotateObjectEncryptionKey;
 import com.example.storage.object.SetObjectMetadata;
+import com.example.storage.object.SetObjectRetentionPolicy;
 import com.example.storage.object.StreamObjectDownload;
 import com.example.storage.object.StreamObjectUpload;
 import com.example.storage.object.UploadEncryptedObject;
@@ -229,6 +230,7 @@ public void testGetObjectMetadata() {
     assertTrue(snippetOutput.contains("eventBasedHold: disabled"));
     assertTrue(snippetOutput.contains("User metadata:"));
     assertTrue(snippetOutput.contains("k=v"));
+    assertTrue(snippetOutput.contains("Object Retention Policy: " + remoteBlob.getRetention()));
   }
 
   @Test
@@ -434,4 +436,28 @@ public void testBatchSetObjectMetadata() {
     assertEquals("value", firstBlobMetadata.get("keyToAddOrUpdate"));
     assertEquals("value", secondBlobMetadata.get("keyToAddOrUpdate"));
   }
+
+  @Test
+  public void testSetObjectRetentionPolicy() {
+    String tempBucket = RemoteStorageHelper.generateBucketName();
+    storage.create(
+        BucketInfo.of(tempBucket), Storage.BucketTargetOption.enableObjectRetention(true));
+    String retentionBlob = "retentionblob";
+    storage.create(BlobInfo.newBuilder(tempBucket, retentionBlob).build());
+    assertNull(storage.get(tempBucket, retentionBlob).getRetention());
+    try {
+      SetObjectRetentionPolicy.setObjectRetentionPolicy(PROJECT_ID, tempBucket, retentionBlob);
+      assertNotNull(storage.get(tempBucket, retentionBlob).getRetention());
+    } finally {
+
+      storage
+          .get(tempBucket, retentionBlob)
+          .toBuilder()
+          .setRetention(null)
+          .build()
+          .update(Storage.BlobTargetOption.overrideUnlockedRetention(true));
+      storage.delete(tempBucket, retentionBlob);
+      storage.delete(tempBucket);
+    }
+  }
 }
