Note:
- For more information on the meanings of parameters such as
SecretId
,SecretKey
, andBucket
contained herein and how to get them, please see COS Glossary.- The common classes in the COS SDK for Java are contained in the following packages:
You can install the Java SDK using Maven or source code:
Using Maven
Add required dependencies to the pom.xml file of your Maven project as follows:
<dependency>
<groupId>com.qcloud</groupId>
<artifactId>cos_api</artifactId>
<version>5.6.35</version>
</dependency>
Using source code
Download the source code here or from the SDK, and import it using Maven. For example, to import it into Eclipse, select File > Import > Maven > Existing Maven Projects.
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 on the class name in your IDE to view more details on all of 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 there is only one instance in the program lifecycle, and call the shutdown method to turn off the instance when 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 abbreviations of COS regions, please visit https://intl.cloud.tencent.com/document/product/436/6224?from_cn_redirect=1.
// `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);
You can also use a temporary key to initialize the COSClient. For more information on how to generate and use a temporary key, please see Generating and Using Temporary Keys. An example is shown below:
// 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 abbreviations of COS regions, please visit https://intl.cloud.tencent.com/document/product/436/6224?from_cn_redirect=1.
// `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 | Setting Method | Description | Type |
---|---|---|---|
region | Constructor or set method | Bucket region. For the abbreviations of COS regions, please see Regions and Access Endpoints | Region |
httpProtocol | set method | The protocol used by a request. By default, HTTP is used to interact with COS | HttpProtocol |
signExpired | set method | Validity period in seconds of the request signature. Default value: 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 |
After determining the region and bucket name, create a bucket by referring to the sample below:
String bucket = "examplebucket-1250000000"; // Bucket name in the format of BucketName-APPID
CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucket);
// Set the bucket permission to Private (private read/write). Other options include public read/private write and public read/write
createBucketRequest.setCannedAcl(CannedAccessControlList.Private);
try{
Bucket bucketResult = cosClient.createBucket(createBucketRequest);
} catch (CosServiceException serverException) {
serverException.printStackTrace();
} catch (CosClientException clientException) {
clientException.printStackTrace();
}
Query the bucket list by referring to the sample below:
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 the advanced upload API.
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/images/picture.jpg
, the object key is images/picture.jpg
. For more information, please see Object Key.Below is an example of uploading a file below 5 GB:
// Specify the file to be uploaded.
File localFile = new File(localFilePath);
// Specify the destination bucket.
String bucketName = "examplebucket-1250000000";
// Specify the key of the object to be uploaded to COS.
String key = "exampleobject";
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
Query the list of objects in a bucket by referring to the sample below:
// Enter the bucket name in the format of 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; and leave it empty to list all objects.
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 use the GET method to download) to share to another device for the download. If your file is set to private read, note that the pre-signed URL may be valid only for a limited period.
Download a file to a specified local path by referring to the sample below:
// Enter the bucket name in the format of BucketName-APPID.
String bucketName = "examplebucket-1250000000";
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 locally.
String outputFilePath = "exampleobject";
File downFile = new File(outputFilePath);
getObjectRequest = new GetObjectRequest(bucketName, key);
ObjectMetadata downObjectMeta = cosClient.getObject(getObjectRequest, downFile);
Delete an object in a specified path of COS with the following code:
// Enter the bucket name in the format of BucketName-APPID.
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
cosClient.deleteObject(bucketName, key);
Close 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?