Bucket Operations

Overview

This document provides an overview of APIs related to basic bucket operations and access control list (ACL) and corresponding SDK sample code.

Basic operations

ACL

Basic Operations

Querying Bucket List

Feature Description

This API is used to query the list of all buckets under the specified account.

Method Prototype

public List<Bucket> listBuckets() throws CosClientException, CosServiceException;

Parameter Descriptions

None

Return Result Descriptions

• Success: A list of all bucket classes is returned. A bucket class contains information such as bucket member and location.
• Failure: An error (e.g., the bucket does not exist) occurred and a CosClientException or CosServiceException exception was thrown. For more information, see Troubleshooting.

Sample Request

List<Bucket> buckets = cosClient.listBuckets();
for (Bucket bucketElement : buckets) {
    String bucketName = bucketElement.getName();
    String bucketLocation = bucketElement.getLocation();
}

Creating a Bucket

Feature Description

This API is used to create a bucket under the specified account. You can create up to 200 buckets in total in all regions under one account. There is no limit on the number of objects in a bucket. Creating a bucket is a low-frequency operation. It is generally recommended to create buckets in the console and create objects in the SDK.

Method Prototype

public Bucket createBucket(String  bucketName) throws CosClientException, CosServiceException;

Parameter Descriptions

Return Result Descriptions

• Success: A bucket class containing bucket description (bucket name, owner, and creation date).
• Failure: An error (e.g., authentication failed) occurred and a CosClientException or CosServiceException exception was thrown. For more information, see Troubleshooting.

Sample Request

// Bucket name is in the format of BucketName-APPID. The bucket name entered here must be in this format
String bucketName = "examplebucket-1250000000";
Bucket bucket = cosClient.createBucket(bucketName);

Checking a Bucket and Its Permission

Feature Description

This API is used to check whether a bucket exists and you have permission to access it.

Method Prototype

public boolean doesBucketExist(String bucketName) 
  throws CosClientException, CosServiceException;

Parameter Descriptions

Return Result Descriptions

• Success: If it exists, true is returned; otherwise, false is returned.
• Failure: An error (e.g., authentication failed) occurred and a CosClientException or CosServiceException exception was thrown. For more information, see Troubleshooting.

Sample Request

// Bucket name is in the format of BucketName-APPID. The bucket name entered here must be in this format
String bucketName = "examplebucket-1250000000";
boolean bucketExistFlag = cosClient.doesBucketExist(bucketName);

Deleting a Bucket

Feature Description

This API is used to delete an empty bucket under the specified account.

Method Prototype

public void deleteBucket(String bucketName) throws CosClientException, CosServiceException;

Parameter Descriptions

Return Result Descriptions

• Success: No return value.
• Failure: An error (e.g., authentication failed) occurred and a CosClientException or CosServiceException exception was thrown. For more information, see Troubleshooting.

Sample Request

// Bucket name is in the format of BucketName-APPID. The bucket name entered here must be in this format
String bucketName = "examplebucket-1250000000";
cosClient.deleteBucket(bucketName);

ACL

Setting Bucket ACL

Feature Description

This API is used to set the access control list (ACL) for the specified bucket. The Set Bucket ACL is an overriding operation that overrides existing permission settings. The ACL can be divided into predefined ACL (CannedAccessControlList) and custom ACL (AccessControlList). When both types of ACLs are set at the same time, the predefined ACL will be ignored and the custom one will prevail.

Method Prototype

// Method 1 (setting a custom ACL)
public void setBucketAcl(String bucketName, AccessControlList acl)
  throws CosClientException, CosServiceException;
// Method 2 (setting a predefined ACL)
public void setBucketAcl(String bucketName, CannedAccessControlList acl) throws CosClientException, CosServiceException;
// Method 3 (encapsulating both methods above, i.e., containing two types of ACLs; if set simultaneously, the custom ACL will prevail)
public void setBucketAcl(SetBucketAclRequest setBucketAclRequest) 
  throws CosClientException, CosServiceException;

Parameter Descriptions

Method 3 covers the parameters of methods 1 and 2 and thus is used here as an example.

Request member description:

Grant class member description:

Owner class member description:

CannedAccessControlList represents a predefined ACL for everyone and is an enumeration class with the following enumerated values:

Return Result Descriptions

• Success: No return value.
• Failure: An error (e.g., authentication failed) occurred and a CosClientException or CosServiceException exception was thrown. For more information, see Troubleshooting.

Sample Request

// Bucket name is in the format of BucketName-APPID. The bucket name entered here must be in this format
String bucketName = "examplebucket-1250000000";
// Set a custom ACL
AccessControlList acl = new AccessControlList();
Owner owner = new Owner();
owner.setId("qcs::cam::uin/2779643970:uin/2779643970");
acl.setOwner(owner);
String id = "qcs::cam::uin/2779643970:uin/734505014";
UinGrantee uinGrantee = new UinGrantee("qcs::cam::uin/2779643970:uin/734505014");
uinGrantee.setIdentifier(id);
acl.grantPermission(uinGrantee, Permission.FullControl);
cosClient.setBucketAcl(bucketName, acl);

// Set a predefined ACL
// Set private read/write (all newly created buckets are private read/write by default)
cosClient.setBucketAcl(bucketName, CannedAccessControlList.Private);
// Set public read and private write
cosClient.setBucketAcl(bucketName, CannedAccessControlList.PublicRead);
// Set public read/write
cosClient.setBucketAcl(bucketName, CannedAccessControlList.PublicReadWrite);

Querying Bucket ACL

Feature Description

This API is used to query the access control list (ACL) for the specified bucket.

Method Prototype

public AccessControlList getBucketAcl(String bucketName)
       throws CosClientException, CosServiceException

Parameter Descriptions

Return Result Descriptions

• Success: The ACL of a bucket is returned.
• Failure: An error (e.g., authentication failed) occurred and a CosClientException or CosServiceException exception was thrown. For more information, see Troubleshooting.

Sample Request

// Bucket name is in the format of BucketName-APPID. The bucket name entered here must be in this format
String bucketName = "examplebucket-1250000000";
AccessControlList acl = cosClient.getBucketAcl(bucketName);