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

GetServiceResult getService(GetServiceRequest request)throws CosXmlClientException, CosXmlServiceException;

void getServiceAsync(GetServiceRequest request, CosXmlResultListener cosXmlResultListen);

Sample Request

GetServiceRequest getServiceRequest = new GetServiceRequest();
// Use the sync method
try {
    GetServiceResult result = cosXmlService.getService(getServiceRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// Use the async callback to request
cosXmlService.getServiceAsync(getServiceRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Put Bucket Lifecycle success
        GetServiceResult getServiceResult = (GetServiceResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Put Bucket Lifecycle failed because of CosXmlClientException or CosXmlServiceException...
    }
});

When initiating a request, if you want to directly set an already calculated signature string, you can do so by calling the getServiceRequest.setSign("already calculated signature string") method. The signature string is calculated by the SDK by default.

Parameter Descriptions

Return Result Descriptions

The result of the request is returned through GetServiceResult.

If the operation failed, the system throws a CosXmlClientException or CosXmlServiceException exception.

Creating a Bucket

Feature Description

This API (PUT Bucket) is used to created a bucket.

Method Prototype

PutBucketResult putBucket(PutBucketRequest request) throws CosXmlClientException, CosXmlServiceException;

void putBucketAsync(PutBucketRequest request, CosXmlResultListener cosXmlResultListener);

Sample Request

String bucket = "examplebucket-1250000000";
PutBucketRequest putBucketRequest = new PutBucketRequest(bucket);

// Define the ACL attribute of the bucket. Value range: private, public-read-write, and public-read; default value: private
putBucketRequest.setXCOSACL("private");

// Grant the grantee read permission
ACLAccount readACLS = new ACLAccount();
readACLS.addAccount("OwnerUin", "SubUin");
putBucketRequest.setXCOSGrantRead(readACLS);

// Grant the grantee write permission
ACLAccount writeACLS = new ACLAccount();
writeACLS.addAccount("OwnerUin", "SubUin");
putBucketRequest.setXCOSGrantRead(writeACLS);

// Grant the grantee read-write permission
ACLAccount writeandReadACLS = new ACLAccount();
writeandReadACLS.addAccount("OwnerUin", "SubUin");
putBucketRequest.setXCOSGrantRead(writeandReadACLS);

// Use the sync method
try {
    PutBucketResult putBucketResult = cosXmlService.putBucket(putBucketRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// Use the async callback to request
cosXmlService.putBucketAsync(putBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Put Bucket success
        PutBucketResult putBucketResult = (putBucketResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Put Bucket failed because of CosXmlClientException or CosXmlServiceException...
    }
});

When initiating a request, if you want to directly set an already calculated signature string, you can do so by calling the putBucketRequest.setSign("already calculated signature string") method. The signature string is calculated by the SDK by default.

Parameter Descriptions

Return Result Descriptions

The result of the request is returned through PutBucketResult.

If the operation failed, the system throws a CosXmlClientException or CosXmlServiceException exception.

Checking a Bucket and Its Permission

Feature Description

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

HeadBucketResult headBucket(HeadBucketRequest request) throws CosXmlClientException, CosXmlServiceException;

void headBucketAsync(HeadBucketRequest request, CosXmlResultListener cosXmlResultListener);

Sample Request

String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
HeadBucketRequest headBucketRequest = new HeadBucketRequest(bucket);

// Use the sync method
try {
    HeadBucketResult headBucketResult = cosXmlService.headBucket(headBucketRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// Use the async callback to request
cosXmlService.headBucketAsync(headBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Head Bucket success
        HeadBucketResult headBucketResult = (HeadBucketResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Head Bucket failed because of CosXmlClientException or CosXmlServiceException...
    }
});

When initiating a request, if you want to directly set an already calculated signature string, you can do so by calling the headBucketRequest.setSign("already calculated signature string") method. The signature string is calculated by the SDK by default.

Parameter Descriptions

Return Result Descriptions

The result of the request is returned through HeadBucketResult.

If the operation failed, the system throws a CosXmlClientException or CosXmlServiceException exception.

Deleting a Bucket

Feature Description

This API (DELETE Bucket) is used to delete the specified bucket.

Method Prototype

DeleteBucketResult deleteBucket(DeleteBucketRequest request) throws CosXmlClientException, CosXmlServiceException;

void deleteBucketAsync(DeleteBucketRequest request, CosXmlResultListener cosXmlResultListener);

Sample Request

String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
DeleteBucketRequest deleteBucketRequest = new DeleteBucketRequest(bucket);

// Use the sync method
try {
    DeleteBucketResult deleteBucketResult = cosXmlService.deleteBucket(deleteBucketRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// Use the async callback to request
cosXmlService.deleteBucketAsync(deleteBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Delete Bucket success
        DeleteBucketResult deleteBucketResult = (DeleteBucketResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Delete Bucket failed because of CosXmlClientException or CosXmlServiceException...
    }
});

When initiating a request, if you want to directly set an already calculated signature string, you can do so by calling the deleteBucketRequest.setSign("already calculated signature string") method. The signature string is calculated by the SDK by default.

Parameter Descriptions

Return Result Descriptions

The result of the request is returned through DeleteBucketResult.

If the operation failed, the system throws a CosXmlClientException or CosXmlServiceException exception.

ACL

Setting Bucket ACL

Feature Description

This API (PUT Bucket acl) is used to set the access control list (ACL) for the specified bucket.

Method Prototype

PutBucketACLResult putBucketACL(PutBucketACLRequest request) throws CosXmlClientException, CosXmlServiceException;

void putBucketACLAsync(PutBucketACLRequest request, CosXmlResultListener cosXmlResultListener);

Sample Request

String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
PutBucketACLRequest putBucketACLRequest = new PutBucketACLRequest(bucket);

// Set bucket access permission
putBucketACLRequest.setXCOSACL("public-read");

// Grant the grantee read permission
ACLAccount readACLS = new ACLAccount();
readACLS.addAccount("OwnerUin", "SubUin");
putBucketACLRequest.setXCOSGrantRead(readACLS);

// Grant the grantee write permission
ACLAccount writeACLS = new ACLAccount();
writeACLS.addAccount("OwnerUin", "SubUin");
putBucketACLRequest.setXCOSGrantRead(writeACLS);

// Grant the grantee read-write permission
ACLAccount writeandReadACLS = new ACLAccount();
writeandReadACLS.addAccount("OwnerUin", "SubUin");
putBucketACLRequest.setXCOSGrantRead(writeandReadACLS);

// Use the sync method
try {
    PutBucketACLResult putBucketACLResult = cosXmlService.putBucketACL(putBucketACLRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// Use the async callback to request
cosXmlService.putBucketACLAsync(putBucketACLRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Put Bucket ACL success
        PutBucketACLResult putBucketACLResult = (PutBucketACLResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Put Bucket ACL failed because of CosXmlClientException or CosXmlServiceException...
    }
});

When initiating a request, if you want to directly set an already calculated signature string, you can do so by calling the putBucketACLRequest.setSign("already calculated signature string") method. The signature string is calculated by the SDK by default.

Parameter Descriptions

Return Result Descriptions

The result of the request is returned through PutBucketACLResult.

If the operation failed, the system throws a CosXmlClientException or CosXmlServiceException exception.

Querying Bucket ACL

Feature Description

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

Method Prototype

GetBucketACLResult getBucketACL(GetBucketACLRequest request) throws CosXmlClientException, CosXmlServiceException;

void getBucketACLAsync(GetBucketACLRequest request, CosXmlResultListener cosXmlResultListener);

Sample Request

String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
GetBucketACLRequest getBucketACLRequest = new GetBucketACLRequest(bucket);

// Use the sync method
try {
    GetBucketACLResult getBucketACLResult = cosXmlService.getBucketACL(getBucketACLRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// Use the async callback to request
cosXmlService.getBucketACLAsync(getBucketACLRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Get Bucket ACL success
        GetBucketACLResult getBucketACLResult = (GetBucketACLResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Get Bucket ACL failed because of CosXmlClientException or CosXmlServiceException...
    }
});

When initiating a request, if you want to directly set an already calculated signature string, you can do so by calling the getBucketACLRequest.setSign("already calculated signature string") method. The signature string is calculated by the SDK by default.

Parameter Descriptions

Return Result Descriptions

The result of the request is returned through GetBucketACLResult.

If the operation failed, the system throws a CosXmlClientException or CosXmlServiceException exception.