Actions on Buckets

Introduction

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

Basic Operations

ACL

Basic Operations

Querying Bucket List

Feature Description

This API (GET Service) is used to query the list of all buckets under a specified account.

Method Prototype

GetServiceResult getService(GetServiceRequest request)throws CosXmlClientException, CosXmlServiceException;

void getServiceAsync(GetServiceRequest request, CosXmlResultListener cosXmlResultListen);

Sample Request

GetServiceRequest getServiceRequest = new GetServiceRequest();
// Set signature verification Host, verify all Headers by default
Set<String> headerKeys = new HashSet<>();
headerKeys.add("Host");
getServiceRequest.setSignParamsAndHeaders(null, headerKeys);
// 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 make requests
cosXmlService.getServiceAsync(getServiceRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        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 use a calculated signature string, you can do so by calling getServiceRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

Parameter Description

Returned Result

The result of the request is returned through GetServiceResult.

If the operation fails, the SDK will throw a CosXmlClientException or CosXmlServiceException exception.

Creating a Bucket

Feature Description

This API (PUT Bucket) is used to create 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. Valid values: private, public-read-write, public-read; Default: private
putBucketRequest.setXCOSACL("private");

// Grant read permission to the authorized user
ACLAccount readACLS = new ACLAccount();
readACLS.addAccount("100000000001", "100000000001");
putBucketRequest.setXCOSGrantRead(readACLS);

// Grant write permission to the authorized user
ACLAccount writeACLS = new ACLAccount();
writeACLS.addAccount("100000000001", "100000000001");
putBucketRequest.setXCOSGrantWrite(writeACLS);

// Grant read and write permissions to the authorized user
ACLAccount writeandReadACLS = new ACLAccount();
writeandReadACLS.addAccount("100000000001", "100000000001");
putBucketRequest.setXCOSReadWrite(writeandReadACLS);
// Set signature verification Host, verify all Headers by default
Set<String> headerKeys = new HashSet<>();
headerKeys.add("Host");
putBucketRequest.setSignParamsAndHeaders(null, headerKeys);
// 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 make requests
cosXmlService.putBucketAsync(putBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        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 use a calculated signature string, you can do so by calling putBucketRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

Parameter Description

Returned Result

The result of the request is returned through PutBucketResult.

If the operation fails, the SDK will throw a CosXmlClientException or CosXmlServiceException exception.

Retrieving Information on a Bucket and Its Permission

Feature Description

This API (HEAD Bucket) is used to verify whether a bucket exists and if you have the 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);
// Set signature verification Host, verify all Headers by default
Set<String> headerKeys = new HashSet<>();
headerKeys.add("Host");
headBucketRequest.setSignParamsAndHeaders(null, headerKeys);
// 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 make requests
cosXmlService.headBucketAsync(headBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        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 use a calculated signature string, you can do so by calling headBucketRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

Parameter Description

Returned Result

The result of the request is returned through HeadBucketResult.

If the operation fails, the SDK will throw 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);
// Set signature verification Host, verify all Headers by default
Set<String> headerKeys = new HashSet<>();
headerKeys.add("Host");
deleteBucketRequest.setSignParamsAndHeaders(null, headerKeys);
// 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 make requests
cosXmlService.deleteBucketAsync(deleteBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        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 use a calculated signature string, you can do so by calling deleteBucketRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

Parameter Description

Returned Result

The result of the request is returned through DeleteBucketResult.

If the operation fails, the SDK will throw 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's access permission
putBucketACLRequest.setXCOSACL("public-read");

// Grant read permission to the authorized user
ACLAccount readACLS = new ACLAccount();
readACLS.addAccount("100000000001", "100000000001");
putBucketACLRequest.setXCOSGrantRead(readACLS);

// Grant write permission to the authorized user
ACLAccount writeACLS = new ACLAccount();
writeACLS.addAccount("100000000001", "100000000001");
putBucketACLRequest.setXCOSGrantWrite(writeACLS);

// Grant read and write permissions to the authorized user
ACLAccount writeandReadACLS = new ACLAccount();
writeandReadACLS.addAccount("100000000001", "100000000001");
putBucketACLRequest.setXCOSReadWrite(writeandReadACLS);
// Set signature verification Host, verify all Headers by default
Set<String> headerKeys = new HashSet<>();
headerKeys.add("Host");
putBucketACLRequest.setSignParamsAndHeaders(null, headerKeys);
// 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 make requests
cosXmlService.putBucketACLAsync(putBucketACLRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        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 use a calculated signature string, you can do so by calling putBucketACLRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

Parameter Description

Returned Result

The result of the request is returned through PutBucketACLResult.

If the operation fails, the SDK will throw a CosXmlClientException or CosXmlServiceException exception.

Querying Bucket ACL

Feature Description

This API (GET Bucket ACL) is used to get the ACL of 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);
// Set signature verification Host, verify all Headers by default
Set<String> headerKeys = new HashSet<>();
headerKeys.add("Host");
getBucketACLRequest.setSignParamsAndHeaders(null, headerKeys);
// 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 make requests
cosXmlService.getBucketACLAsync(getBucketACLRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        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 use a calculated signature string, you can do so by calling getBucketACLRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

Parameter Description

Returned Result

The result of the request is returned through GetBucketACLResult.

If the operation fails, the SDK will throw a CosXmlClientException or CosXmlServiceException exception.