You may fail to download a large object if the network is unstable or other exceptions occur. In some cases, you may still fail to download the object after multiple attempts. To resolve this issue, Object Storage Service (OSS) SDK for Java provides the resumable download feature.

In resumable download, objects that you want to download are split into multiple parts that are downloaded separately. After all parts are downloaded, OSS combines these parts together.

You can use ossClient.downloadFile to implement resumable download. The following table describes the parameters you can configure for DownloadFileRequest.

Parameter Required Example Description Configuration method
bucketName Yes examplebucket The name of the bucket. Constructor
key Yes exampledir/exampleobject.txt The full path of the object to download. The full path of the object cannot contain bucket names. Constructor
downloadFile No D:\\localpath\\examplefile.txt The full path of the local file. The OSS object is downloaded to this path. Constructor or setDownloadFile
partSize No 1 * 1024 * 1024 The size of each part. Valid values: 1 byte to 5 GB. setPartSize
taskNum No 10 The number of parts that can be concurrently downloaded. Default value: 1. setTaskNum
enableCheckpoint No true Specifies whether to enable resumable upload and download. Default value: false. Valid values:
  • false: specifies that the resumable upload and download feature is disabled.
  • true: specifies that the resumable upload and download feature is enabled.
checkpointFile No D:\\localpath\\examplefile.txt.dcp The file that records the results of multipart download. This parameter must be specified if you want to enable resumable upload and download. This file stores information about download progress. If you fail to download a part, the next download operation continues based on the recorded progress. After the object is downloaded, the checkpoint file is deleted.

By default, the name of the file is downloadFile.dcp, and the file is stored in the same path as that of the downloadFile.


The following code provides an example on how to implement resumable download:

// Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to 
String endpoint = "yourEndpoint";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a Resource Access Management (RAM) user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Specify the name of the bucket. Example: examplebucket. 
String bucketName = "examplebucket";
// Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
String objectName = "exampledir/exampleobject.txt";

// Create an OSSClient instance. 
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// Send a request to perform resumable download in which 10 parts can be concurrently downloaded. 
DownloadFileRequest downloadFileRequest = new DownloadFileRequest(bucketName, objectName);
downloadFileRequest.setPartSize(1 * 1024 * 1024);
// Set the full path of the checkpoint file. After the checkpoint file is generated because the object download is interrupted, you must set the full path of the checkpoint file only when you want to continue the download of the object. 

// Download the object. 
DownloadFileResult downloadRes = ossClient.downloadFile(downloadFileRequest);
// After the object is downloaded, the object metadata is returned. 
ObjectMetadata objectMetadata = downloadRes.getObjectMetadata();

// Shut down the OSSClient instance.