Skip to content

Commit 45837d3

Browse files
JesseLovelacegcf-owl-bot[bot]
JesseLovelace
and
gcf-owl-bot[bot]
authored
docs: add samples for object retention (#2417)
* 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>
1 parent f32aba5 commit 45837d3

File tree

7 files changed

+177
-4
lines changed

7 files changed

+177
-4
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-storage/tree/
237237
| 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) |
238238
| 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) |
239239
| 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) |
240+
| 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) |
240241
| 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) |
241242
| 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) |
242243
| 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/
322323
| 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) |
323324
| 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) |
324325
| 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) |
326+
| 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) |
325327
| 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) |
326328
| 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) |
327329
| 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) |

‎samples/snippets/src/main/java/com/example/storage/bucket/CreateBucketWithObjectRetention.java‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/*
2+
* Copyright 2024 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.example.storage.bucket;
18+
19+
// [START storage_create_bucket_with_object_retention]
20+
21+
import com.google.cloud.storage.Bucket;
22+
import com.google.cloud.storage.BucketInfo;
23+
import com.google.cloud.storage.Storage;
24+
import com.google.cloud.storage.StorageOptions;
25+
26+
public class CreateBucketWithObjectRetention {
27+
public static void createBucketWithObjectRetention(String projectId, String bucketName) {
28+
// The ID of your GCP project
29+
// String projectId = "your-project-id";
30+
31+
// The ID to give your GCS bucket
32+
// String bucketName = "your-unique-bucket-name";
33+
34+
Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
35+
36+
Bucket bucket =
37+
storage.create(
38+
BucketInfo.of(bucketName), Storage.BucketTargetOption.enableObjectRetention(true));
39+
40+
System.out.println(
41+
"Created bucket "
42+
+ bucket.getName()
43+
+ " with object retention enabled setting: "
44+
+ bucket.getObjectRetention().getMode().toString());
45+
}
46+
}
47+
48+
// [END storage_create_bucket_with_object_retention]

‎samples/snippets/src/main/java/com/example/storage/bucket/GetBucketMetadata.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ public static void getBucketMetadata(String projectId, String bucketName) {
5656
System.out.println("StorageClass: " + bucket.getStorageClass().name());
5757
System.out.println("TimeCreated: " + bucket.getCreateTime());
5858
System.out.println("VersioningEnabled: " + bucket.versioningEnabled());
59+
System.out.println("ObjectRetention: " + bucket.getObjectRetention());
5960
if (bucket.getLabels() != null) {
6061
System.out.println("\n\n\nLabels:");
6162
for (Map.Entry<String, String> label : bucket.getLabels().entrySet()) {

‎samples/snippets/src/main/java/com/example/storage/object/GetObjectMetadata.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ public static void getObjectMetadata(String projectId, String bucketName, String
6868
System.out.println("StorageClass: " + blob.getStorageClass());
6969
System.out.println("TimeCreated: " + new Date(blob.getCreateTime()));
7070
System.out.println("Last Metadata Update: " + new Date(blob.getUpdateTime()));
71+
System.out.println("Object Retention Policy: " + blob.getRetention());
7172
Boolean temporaryHoldIsEnabled = (blob.getTemporaryHold() != null && blob.getTemporaryHold());
7273
System.out.println("temporaryHold: " + (temporaryHoldIsEnabled ? "enabled" : "disabled"));
7374
Boolean eventBasedHoldIsEnabled =

‎samples/snippets/src/main/java/com/example/storage/object/SetObjectRetentionPolicy.java‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
/*
2+
* Copyright 2022 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.example.storage.object;
18+
19+
// [START storage_set_object_retention_policy]
20+
21+
import static java.time.OffsetDateTime.now;
22+
23+
import com.google.cloud.storage.Blob;
24+
import com.google.cloud.storage.BlobId;
25+
import com.google.cloud.storage.BlobInfo.Retention;
26+
import com.google.cloud.storage.Storage;
27+
import com.google.cloud.storage.StorageException;
28+
import com.google.cloud.storage.StorageOptions;
29+
30+
public class SetObjectRetentionPolicy {
31+
public static void setObjectRetentionPolicy(
32+
String projectId, String bucketName, String objectName) throws StorageException {
33+
// The ID of your GCP project
34+
// String projectId = "your-project-id";
35+
36+
// The ID of your GCS bucket that has object retention enabled
37+
// String bucketName = "your-unique-bucket-name";
38+
39+
// The ID of your GCS object
40+
// String objectName = "your-object-name";
41+
42+
Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
43+
BlobId blobId = BlobId.of(bucketName, objectName);
44+
Blob blob = storage.get(blobId);
45+
if (blob == null) {
46+
System.out.println("The object " + objectName + " was not found in " + bucketName);
47+
return;
48+
}
49+
50+
Blob updated =
51+
blob.toBuilder()
52+
.setRetention(
53+
Retention.newBuilder()
54+
.setMode(Retention.Mode.UNLOCKED)
55+
.setRetainUntilTime(now().plusDays(10))
56+
.build())
57+
.build()
58+
.update();
59+
60+
System.out.println("Retention policy for object " + objectName + " was set to:");
61+
System.out.println(updated.getRetention().toString());
62+
63+
// To modify an existing policy on an Unlocked object, pass in the override parameter
64+
blob.toBuilder()
65+
.setRetention(
66+
updated.getRetention().toBuilder().setRetainUntilTime(now().plusDays(9)).build())
67+
.build()
68+
.update(Storage.BlobTargetOption.overrideUnlockedRetention(true));
69+
70+
System.out.println("Retention policy for object " + objectName + " was updated to:");
71+
System.out.println(storage.get(blobId).getRetention().toString());
72+
}
73+
}
74+
75+
// [END storage_set_object_retention_policy]

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

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
import com.example.storage.bucket.ChangeDefaultStorageClass;
3131
import com.example.storage.bucket.ConfigureBucketCors;
3232
import com.example.storage.bucket.CreateBucket;
33+
import com.example.storage.bucket.CreateBucketWithObjectRetention;
3334
import com.example.storage.bucket.CreateBucketWithStorageClassAndLocation;
3435
import com.example.storage.bucket.CreateBucketWithTurboReplication;
3536
import com.example.storage.bucket.DeleteBucket;
@@ -265,6 +266,7 @@ public void testGetBucketMetadata() {
265266
assertTrue(snippetOutput.contains("Labels:"));
266267
assertTrue(snippetOutput.contains("k=v"));
267268
assertTrue(snippetOutput.contains("Lifecycle Rules:"));
269+
assertTrue(snippetOutput.contains("ObjectRetention: " + bucket.getObjectRetention()));
268270
}
269271

270272
@Test
@@ -662,10 +664,14 @@ public void testLockRetentionPolicy() {
662664
String tempBucket = RemoteStorageHelper.generateBucketName();
663665
Bucket bucket = storage.create(BucketInfo.of(tempBucket));
664666
assertNotNull(bucket);
665-
SetRetentionPolicy.setRetentionPolicy(PROJECT_ID, tempBucket, 5L);
666-
assertEquals(5L, (long) storage.get(tempBucket).getRetentionPeriod());
667-
LockRetentionPolicy.lockRetentionPolicy(PROJECT_ID, tempBucket);
668-
assertTrue(storage.get(tempBucket).retentionPolicyIsLocked());
667+
try {
668+
SetRetentionPolicy.setRetentionPolicy(PROJECT_ID, tempBucket, 5L);
669+
assertEquals(5L, (long) storage.get(tempBucket).getRetentionPeriod());
670+
LockRetentionPolicy.lockRetentionPolicy(PROJECT_ID, tempBucket);
671+
assertTrue(storage.get(tempBucket).retentionPolicyIsLocked());
672+
} finally {
673+
storage.delete(tempBucket);
674+
}
669675
}
670676

671677
@Test
@@ -682,4 +688,18 @@ public void testUniformBucketLevelAccess() {
682688
DisableUniformBucketLevelAccess.disableUniformBucketLevelAccess(PROJECT_ID, BUCKET);
683689
assertFalse(storage.get(BUCKET).getIamConfiguration().isUniformBucketLevelAccessEnabled());
684690
}
691+
692+
@Test
693+
public void testCreateBucketWithObjectRetention() {
694+
String tempBucket = RemoteStorageHelper.generateBucketName();
695+
696+
try {
697+
CreateBucketWithObjectRetention.createBucketWithObjectRetention(PROJECT_ID, tempBucket);
698+
assertNotNull(storage.get(tempBucket).getObjectRetention());
699+
String snippetOutput = stdOutCaptureRule.getCapturedOutputAsUtf8String();
700+
assertTrue(snippetOutput.contains("Enabled"));
701+
} finally {
702+
storage.delete(tempBucket);
703+
}
704+
}
685705
}

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@
4747
import com.example.storage.object.MoveObject;
4848
import com.example.storage.object.RotateObjectEncryptionKey;
4949
import com.example.storage.object.SetObjectMetadata;
50+
import com.example.storage.object.SetObjectRetentionPolicy;
5051
import com.example.storage.object.StreamObjectDownload;
5152
import com.example.storage.object.StreamObjectUpload;
5253
import com.example.storage.object.UploadEncryptedObject;
@@ -229,6 +230,7 @@ public void testGetObjectMetadata() {
229230
assertTrue(snippetOutput.contains("eventBasedHold: disabled"));
230231
assertTrue(snippetOutput.contains("User metadata:"));
231232
assertTrue(snippetOutput.contains("k=v"));
233+
assertTrue(snippetOutput.contains("Object Retention Policy: " + remoteBlob.getRetention()));
232234
}
233235

234236
@Test
@@ -434,4 +436,28 @@ public void testBatchSetObjectMetadata() {
434436
assertEquals("value", firstBlobMetadata.get("keyToAddOrUpdate"));
435437
assertEquals("value", secondBlobMetadata.get("keyToAddOrUpdate"));
436438
}
439+
440+
@Test
441+
public void testSetObjectRetentionPolicy() {
442+
String tempBucket = RemoteStorageHelper.generateBucketName();
443+
storage.create(
444+
BucketInfo.of(tempBucket), Storage.BucketTargetOption.enableObjectRetention(true));
445+
String retentionBlob = "retentionblob";
446+
storage.create(BlobInfo.newBuilder(tempBucket, retentionBlob).build());
447+
assertNull(storage.get(tempBucket, retentionBlob).getRetention());
448+
try {
449+
SetObjectRetentionPolicy.setObjectRetentionPolicy(PROJECT_ID, tempBucket, retentionBlob);
450+
assertNotNull(storage.get(tempBucket, retentionBlob).getRetention());
451+
} finally {
452+
453+
storage
454+
.get(tempBucket, retentionBlob)
455+
.toBuilder()
456+
.setRetention(null)
457+
.build()
458+
.update(Storage.BlobTargetOption.overrideUnlockedRetention(true));
459+
storage.delete(tempBucket, retentionBlob);
460+
storage.delete(tempBucket);
461+
}
462+
}
437463
}

0 commit comments

Comments
 (0)