You can configure a time-based retention policy for a bucket. A retention policy has a protection period ranging from one day to 70 years. This topic describes how to create, query, and lock a retention policy.

Background information

OSS supports the Write Once Read Many (WORM) strategy that prevents an object from being deleted or overwritten for a specified period of time.

If a retention policy is not locked within 24 hours after it is created, the retention policy becomes invalid. After the retention policy configured for a bucket is locked, you can upload objects to or read objects from the bucket. However, you cannot delete objects in the bucket or the retention policy within the retention period of the policy. The retention period of the policy cannot be shortened but only be extended. For more information about retention policies, see Retention policy.

Create a retention policy

The following code provides an example on how to create a retention policy:

// The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Create an InitiateBucketWormRequest object.
InitiateBucketWormRequest initiateBucketWormRequest = new InitiateBucketWormRequest(bucketName);
// Set the retention period to one day.
initiateBucketWormRequest.setRetentionPeriodInDays(1);

// Create the retention policy.
InitiateBucketWormResult initiateBucketWormResult = ossClient.initiateBucketWorm(initiateBucketWormRequest);

// Query the ID of the retention policy.
String wormId = initiateBucketWormResult.getWormId();
System.out.println(wormId);

// Shut down the OSSClient instance.
ossClient.shutdown();

For more information about how to create a retention policy, see InitiateBucketWorm.

Cancel an unlocked retention policy

The following code provides an example on how to cancel an unlocked retention policy:

// The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Cancel the retention policy.
ossClient.abortBucketWorm(bucketName);

// Shut down the OSSClient instance.
ossClient.shutdown();

For more information about how to cancel an unlocked retention policy, see AbortBucketWorm.

Lock a retention policy

The following code provides an example on how to lock a retention policy:

// The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";
String wormId = "<yourWormId>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Lock the retention policy.
ossClient.completeBucketWorm(bucketName, wormId);

// Shut down the OSSClient instance.
ossClient.shutdown();

For more information about how to lock a retention policy, see CompleteBucketWorm.

Query a retention policy

The following code provides an example on how to query a retention policy:

// The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Query the retention policy.
GetBucketWormResult getBucketWormResult = ossClient.getBucketWorm(bucketName);

// Query the ID of the retention policy.
System.out.println(getBucketWormResult.getWormId());
// Query the state of the retention policy. InProgress indicates that the retention policy is not locked. Locked indicates that the retention policy is locked.
System.out.println(getBucketWormResult.getWormState());
// Query the retention period of the retention policy.
System.out.println(getBucketWormResult.getRetentionPeriodInDays());
// Query the created time of the retention policy.
System.out.println(getBucketWormResult.getCreationDate());

// Shut down the OSSClient instance.
ossClient.shutdown();

For more information about how to query a retention policy, see GetBucketWorm.

Extend the retention period of a retention policy

The following code provides an example on how to extend the retention period of a locked retention policy:

// The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";
String wormId = "<yourWormId>";

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Extend the retention period of the locked retention policy.
ossClient.extendBucketWorm(bucketName, wormId, 2);

// Shut down the OSSClient instance.
ossClient.shutdown();

For more information about how to extend the retention period of a locked retention policy, see ExtendBucketWorm.