Note：
- For the definitions of terms such as SecretId, SecretKey, and Bucket, see COS Glossary.
- You can find common classes for the COS Java SDK in the following packages:
You can install the Java SDK using Maven or source code:
<dependency>
<groupId>com.qcloud</groupId>
<artifactId>cos_api</artifactId>
<version>5.6.38</version>
</dependency>
Uninstall the SDK by removing the POM dependencies or source code.
The following describes how to use the COS Java SDK to complete basic operations, such as initializing the client, creating a bucket, querying a bucket list, uploading an object, querying an object list, downloading an object, and deleting an object. For the classes in the examples, you can click the class name in your IDE to view more details about all its fields and functions.
The COS Java SDK package is named com.qcloud.cos.*. You can import the classes required for running your program through your IDE such as Eclipse and IntelliJ.
Before making any request for COS services, you need to generate a COSClient class object for calling the COS APIs.
Note：
COSClient is a thread-safe class that allows multi-thread access to the same instance. Because an instance maintains a connection pool internally, creating multiple instances may lead to resource exhaustion. Please ensure that there is only one instance in the program lifecycle, and call the shutdown method to turn off the instance when it is no longer needed. If you need to create a new instance, shut down the previous instance first.
If you use a permanent key to initialize a COSClient, you need to get your SecretId and SecretKey on the API Key Management page in the CAM console. A permanent key is suitable for most application scenarios. Below is an example:
// 1. Initialize the user credentials (secretId, secretKey).
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// 2. Set the bucket region. For the abbreviations for COS regions, please see https://intl.cloud.tencent.com/document/product/436/6224.
// `clientConfig` contains the set methods to set region, HTTPS (HTTP by default), timeout, and proxy. For detailed usage, please see the source code or the FAQs about the SDK for Java.
Region region = new Region("COS_REGION");
ClientConfig clientConfig = new ClientConfig(region);
// The HTTPS protocol is recommended.
clientConfig.setHttpProtocol(HttpProtocol.https);
// 3. Generate a COS client.
COSClient cosClient = new COSClient(cred, clientConfig);
You can also use a temporary key to initialize COSClient. For more information on how to generate and use a temporary key, see Generating and Using Temporary Keys. Below is a sample:
// 1. Pass in the obtained temporary key (tmpSecretId, tmpSecretKey, sessionToken).
String tmpSecretId = "COS_SECRETID";
String tmpSecretKey = "COS_SECRETKEY";
String sessionToken = "COS_TOKEN";
BasicSessionCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
// 2. Set the bucket region. For the abbreviations for COS regions, please see https://intl.cloud.tencent.com/document/product/436/6224.
// `clientConfig` contains the set methods to set region, HTTPS (HTTP by default), timeout, and proxy. For detailed usage, please see the source code or the FAQs about the SDK for Java.
Region region = new Region("COS_REGION");
ClientConfig clientConfig = new ClientConfig(region);
// 3. Generate a COS client.
COSClient cosClient = new COSClient(cred, clientConfig);
The ClientConfig class is a configuration class containing the following main members:
| Member Name | Set Method | Description | Type |
|---|---|---|---|
| region | Constructor or set method | Bucket region. For the abbreviations for COS regions, please see Regions and Access Endpoints. | Region |
| httpProtocol | Set method | The protocol used by the request. By default, HTTP is used to interact with COS. | HttpProtocol |
| signExpired | Set method | Validity period (in seconds) of the request signature. Default: 3600s | int |
| connectionTimeout | Set method | Timeout duration in milliseconds for connection with COS. Default value: 30000 ms | int |
| socketTimeout | Set method | Timeout duration in milliseconds for the client to read data. Default value: 30000 ms | int |
| httpProxyIp | Set method | Proxy server IP | String |
| httpProxyPort | Set method | Proxy server port | int |
The following example creates a bucket for the selected region and bucket:
String bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucket);
// Set the bucket permission to "Private" (private read and write). Other valid values are "PublicRead" (public read/private write) and "PublicReadWrite" (public read and write).
createBucketRequest.setCannedAcl(CannedAccessControlList.Private);
try{
Bucket bucketResult = cosClient.createBucket(createBucketRequest);
} catch (CosServiceException serverException) {
serverException.printStackTrace();
} catch (CosClientException clientException) {
clientException.printStackTrace();
}
The following example queries a bucket list:
List<Bucket> buckets = cosClient.listBuckets();
for (Bucket bucketElement : buckets) {
String bucketName = bucketElement.getName();
String bucketLocation = bucketElement.getLocation();
}
Upload a local file or input stream with a known length to COS. It is most suitable for uploading small image files below 20 MB. The maximum file size allowed is 5 GB. For larger files, you need to use multipart upload or an advanced upload API.
Note：
The classes related to advanced APIs are in the com.qcloud.cos.transfer.* sub-package.
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/images/picture.jpg, the object key is images/picture.jpg. For more information, please see Object Key.The following example uploads a file up to 5 GB:
// Specify the file to be uploaded.
File localFile = new File(localFilePath);
// Specify a bucket to store the file.
String bucketName = "examplebucket-1250000000";
// Specify the COS path (i.e. the object key) to upload the file. For example, if the object key is "folder/picture.jpg", the file "picture.jpg" will be uploaded to the "folder" directory.
String key = "exampleobject";
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
The following example queries the list of objects in a bucket:
// Enter the bucket name in the format: BucketName-APPID.
String bucketName = "examplebucket-1250000000";
ListObjectsRequest listObjectsRequest = new ListObjectsRequest();
// Set the bucket name.
listObjectsRequest.setBucketName(bucketName);
// The prefix indicates that the key of the object to be listed must start with this value
listObjectsRequest.setPrefix("images/");
// Set the delimiter to "/" to list objects in the current directory. To list all objects, leave it empty.
listObjectsRequest.setDelimiter("/");
// Set the maximum number of traversed objects (up to 1,000 per listobject request).
listObjectsRequest.setMaxKeys(1000);
ObjectListing objectListing = null;
do {
try {
objectListing = cosClient.listObjects(listObjectsRequest);
} catch (CosServiceException e) {
e.printStackTrace();
return;
} catch (CosClientException e) {
e.printStackTrace();
return;
}
// A common prefix indicates paths that end with the delimiter. If the delimiter is set to "/", the common prefix indicates the paths of all subdirectories.
List<String> commonPrefixs = objectListing.getCommonPrefixes();
// The object summary shows all listed objects.
List<COSObjectSummary> cosObjectSummaries = objectListing.getObjectSummaries();
for (COSObjectSummary cosObjectSummary : cosObjectSummaries) {
// File path key
String key = cosObjectSummary.getKey();
// File ETag
String etag = cosObjectSummary.getETag();
// File size
long fileSize = cosObjectSummary.getSize();
// File storage class
String storageClasses = cosObjectSummary.getStorageClass();
}
String nextMarker = objectListing.getNextMarker();
listObjectsRequest.setMarker(nextMarker);
} while (objectListing.isTruncated());
Once an object is uploaded, you can download it by calling the GET Object API with the same key, or by generating a pre-signed URL (Please specify GET as the download method) to share to another device for download. Note that the pre-signed URL may be valid only for a limited period if your file is set to private-read.
The following example downloads a file to a specified local path:
// Enter the bucket name in the format: BucketName-APPID.
String bucketName = "examplebucket-1250000000";
// Specify the COS path (i.e. the object key) of the file to download. For example, if the object key is "folder/picture.jpg", the file "picture.jpg" in the "folder" directory will be downloaded.
String key = "exampleobject";
// Method 1. Get the input stream of the downloaded file.
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
COSObject cosObject = cosClient.getObject(getObjectRequest);
COSObjectInputStream cosObjectInput = cosObject.getObjectContent();
// Download the CRC64 value of the object.
String crc64Ecma = cosObject.getObjectMetadata().getCrc64Ecma();
// Close the input stream.
cosObjectInput.close();
// Method 2: Download the file to a local directory, e.g. a directory in D drive.
String outputFilePath = "exampleobject";
File downFile = new File(outputFilePath);
getObjectRequest = new GetObjectRequest(bucketName, key);
ObjectMetadata downObjectMeta = cosClient.getObject(getObjectRequest, downFile);
You can delete an object in a specified path in COS with the following code:
// Enter the bucket name in the format: BucketName-APPID.
String bucketName = "examplebucket-1250000000";
// Specify the COS path (i.e. the object key) of the file to delete. For example, if the object key is "folder/picture.jpg", the "picture.jpg" file in the "folder" directory will be deleted.
String key = "exampleobject";
cosClient.deleteObject(bucketName, key);
By default, if requests initiated by COSClient via the SDK return error responses, they will be retried. The retry policy is as follows:
3. You can set it using clientConfig.setMaxErrorRetry.0, no retry will be performed on all types of request errors.You can also configure a retry policy as needed by referring to the following code:
Setting the number of retries:
Region region = new Region("COS_REGION");
ClientConfig clientConfig = new ClientConfig(region);
// Set the maximum number of retries to 4.
clientConfig.setMaxErrorRetry = 4;
Setting the retry policy:
// Customize a retry policy.
public class OnlyIOExceptionRetryPolicy extends RetryPolicy {
@Override
public <X extends CosServiceRequest> boolean shouldRetry(CosHttpRequest<X> request,
HttpResponse response,
Exception exception,
int retryIndex) {
// Retry only for client-side IOException.
if (exception.getCause() instanceof IOException) {
return true;
}
return false;
}
}
Region region = new Region("COS_REGION");
ClientConfig clientConfig = new ClientConfig(region);
RetryPolicy myRetryPolicy = new OnlyIOExceptionRetryPolicy();
// Configure the custom retry policy.
clientConfig.setRetryPolicy(myRetryPolicy);
Shut down the COSClient and release the server threads connected over HTTP with the following code:
// Close the client (release server threads).
cosClient.shutdown();
Was this page helpful?