Help Center/ Object Storage Service/ SDK Reference/ Java/ Bucket APIs (SDK for Java)/ Write-Once-Read-Many (WORM) (SDK for Java)/ Configuring a Default WORM Policy for a Bucket (SDK for Java)
Updated on 2026-08-14 GMT+08:00
View PDF
Share

Configuring a Default WORM Policy for a Bucket (SDK for Java)

Function

This API is used to configure a default WORM policy and retention period for a bucket.

With a bucket's default WORM policy, if you do not specify a protection policy or retention period when you upload an object to the bucket, the default policy will be automatically applied to the newly uploaded object. An object-level WORM policy requires configuring a specific date, which indicates that an object will be protected until that date. For a default bucket-level WORM policy, a retention period is required, and the protection for an object starts when the object is uploaded to the bucket.

  • You can modify or even delete the default WORM policy of a bucket. The change applies only to the objects uploaded after the change, but not to those uploaded before.
  • During a multipart upload, the object parts uploaded are not protected before they are assembled. After object parts are assembled, the new object is protected by the default bucket-level WORM policy. You can also configure an object-level WORM policy for the new object.

Restrictions

  • The WORM mode can only be COMPLIANCE.
  • The retention period can be set to 1 to 36500 days or 1 to 100 years.
  • The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.

Method

obsClient.setObjectLockConfiguration(SetObjectLockConfigurationRequest request)

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

request

Table 2

Yes

Explanation:

Request parameters for configuring a default WORM policy for a bucket. For details, see Table 2.
Table 2 SetObjectLockConfigurationRequest

Parameter

Type

Mandatory (Yes/No)

Description

bucketName

String

Yes

Explanation:

Bucket name

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket properties comply with those set in the first creation request.

Default value:

None

objectLockConfiguration

Table 3

Yes

Explanation:

WORM policy configuration. For details, see Table 3.
Table 3 ObjectLockConfiguration

Parameter

Type

Mandatory (Yes/No)

Description

objectLockEnabled

String

Yes

Explanation:

Bucket-level WORM status

Restrictions:

N/A

Value range:

Enabled: Bucket-level WORM is enabled.

Default value:

N/A

rule

Table 4

Yes when objectLockEnabled is set to Enabled. If this parameter is not specified, the default bucket-level WORM policy will be cleared.

Explanation:

Rules of a bucket-level WORM policy

Restrictions:

If this parameter is not specified, the default bucket-level WORM policy will be cleared.

Value range:

For details, see Table 4.

Default value:

N/A
Table 4 ObjectLockRule

Parameter

Type

Mandatory (Yes/No)

Description

defaultRetention

Table 5

No

Explanation:

Default bucket-level WORM policy

Restrictions:

None

Value range:

For details, see Table 5.

Default value:

None
Table 5 DefaultRetention

Parameter

Type

Mandatory (Yes/No)

Description

mode

String

Yes

Explanation:

WORM retention policy of a bucket

Restrictions:

N/A

Value range:

COMPLIANCE: compliance mode

Default value:

COMPLIANCE

days

int

Either days or years must be specified, but they cannot be specified at the same time.

Explanation:

Retention period, in days

Restrictions:

Only one of days and years can be set to a value other than 0. The value must be within the allowed range.

Value range:

1 to 36500

Default value:

N/A

years

int

Either days or years must be specified, but they cannot be specified at the same time.

Explanation:

Default retention period, in years

Restrictions:

  • One year is considered as 365 days, regardless of the leap year.
  • Only one of days and years can be set to a value other than 0. The value must be within the allowed range.

Value range:

1 to 100

Default value:

N/A

Responses

Table 6 Common response headers

Parameter

Type

Description

statusCode

int

Explanation:

HTTP status code.

Value range:

A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response.

For more information, see Status Code.

Default value:

None

responseHeaders

Map<String, Object>

Explanation:

HTTP response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header.

Default value:

None

Sample Code

This example configures a default WORM policy for bucket exampleBucket. 
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.objectlock.DefaultRetention;
import com.obs.services.model.objectlock.ObjectLockConfiguration;
import com.obs.services.model.objectlock.ObjectLockRule;
import com.obs.services.model.objectlock.SetObjectLockConfigurationRequest;
public class SetObjectLockConfiguration {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are not advised to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. CN North-Beijing4 is used here as an example. Replace it with the one currently in use.
        // Obtain an endpoint using environment variables or import it in other ways.
        String endPoint = System.getenv("ENDPOINT");
        ObsConfiguration obsConfiguration = new ObsConfiguration();
        obsConfiguration.setEndPoint(endPoint);
        ObsClient obsClient = new ObsClient(ak, sk, securityToken, obsConfiguration);
        try {
            String exampleBucket = "exampleBucket";
            DefaultRetention retention = new DefaultRetention("COMPLIANCE", 30, null);
            ObjectLockRule rule = new ObjectLockRule(retention);
            ObjectLockConfiguration config = new ObjectLockConfiguration("Enabled", rule);
            SetObjectLockConfigurationRequest request = new SetObjectLockConfigurationRequest(exampleBucket, config);
            obsClient.setObjectLockConfiguration(request);
            System.out.println("SetObjectLockConfiguration successfully");
        } catch (ObsException e) {
            System.out.println("SetObjectLockConfiguration failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code:" + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message:" + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
            e.printStackTrace();
        } catch (Exception e) {
            System.out.println("SetObjectLockConfiguration failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}

Helpful Links