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 even after multiple attempts. To resolve this issue, Object Storage Service (OSS) SDK for Java provides the resumable download feature. In resumable download, the object that you want to download is split into multiple parts and each part is separately downloaded. After all parts are downloaded, these parts are combined into a complete object.


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

import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {
    public static void main(String[] args) {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
        String endpoint = "";
        // 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 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 the bucket name. 
        String objectName = "exampledir/exampleobject.txt";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
        try {
            // Perform resumable download in which 10 parts can be concurrently downloaded. 
            DownloadFileRequest downloadFileRequest = new DownloadFileRequest(bucketName, objectName);
            // Specify the full path of the local file. Example: D:\\localpath\\examplefile.txt. 
            // Specify the size of each part. Unit: bytes. Valid values: 100 KB to 5 GB. Default value: 100 KB. 
            downloadFileRequest.setPartSize(1 * 1024 * 1024);
            // Specify the number of threads for the resumable download task. Default value: 1. 
            // Specify whether to enable resumable download. By default, resumable upload is disabled. 
            // Specify the full path of the checkpoint file. Example: D:\\localpath\\examplefile.txt.dcp. 
            // 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. After the object is downloaded, the checkpoint file is deleted. 

            // Download the object. 
            DownloadFileResult downloadRes = ossClient.downloadFile(downloadFileRequest);
            // After the object is downloaded, the object metadata is returned. 
            ObjectMetadata objectMetadata = downloadRes.getObjectMetadata();
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (Throwable ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {


  • For more information about the complete sample code for resumable download, visit GitHub.
  • For more information about the API operation that you can call to perform resumable download, see GetObject.