How to use Java SDK for range download - Object Storage Service

If you only need a portion of a file, you can use range download to retrieve data from a specified range.

Notes

In this topic, the public endpoint of the China (Hangzhou) region is used. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For details about supported regions and endpoints, see Regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Configuration examples for common scenarios.
To perform a range download, you must have the oss:GetObject permission. For more information, see Attach a custom policy to a RAM user.

Specify a valid range to download data

The following sample code provides an example of how to specify a valid range to download a file.

import com.aliyun.oss.*; import com.aliyun.oss.common.auth.*; import com.aliyun.oss.common.comm.SignVersion; import com.aliyun.oss.model.GetObjectRequest; import com.aliyun.oss.model.OSSObject; import java.io.InputStream; public class Demo { public static void main(String[] args) throws Exception { // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. String endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider(); // Specify the bucket name. 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"; // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. String region = "cn-hangzhou"; // Create an OSSClient instance. // Call the shutdown method to release resources when the OSSClient is no longer in use. ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration(); clientBuilderConfiguration.setSignatureVersion(SignVersion.V4); OSS ossClient = OSSClientBuilder.create() .endpoint(endpoint) .credentialsProvider(credentialsProvider) .clientConfiguration(clientBuilderConfiguration) .region(region) .build(); InputStream in = null; try { GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, objectName); // For a file of 1,000 bytes, the valid byte range is 0 to 999. // Obtain data within the range of 0 to 999 bytes. This range includes byte 0 and byte 999, which means a total of 1,000 bytes of data are obtained. If the specified range is invalid (for example, the start or end position is a negative value, or the specified value is greater than the file size), the entire file is downloaded. getObjectRequest.setRange(0, 999); // Perform a range download. OSSObject ossObject = ossClient.getObject(getObjectRequest); // Read data. byte[] buf = new byte[1024]; in = ossObject.getObjectContent(); for (int n = 0; n != -1; ) { n = in.read(buf, 0, buf.length); } ossObject.close(); } 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 (ClientException 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) { ossClient.shutdown(); } // After the data is read, you must close the stream. Otherwise, a connection leak occurs, no connections are available for requests, and the program does not work as expected. if (in != null) { in.close(); } } } }

A single stream read may not retrieve all the data. If you want to read 64 KB of data in streaming mode, you can use the following method to read the data multiple times until 64 KB of data is read or the end of the file is reached. For more information, see InputStream.read.

byte[] buf = new byte[1024]; InputStream in = ossObject.getObjectContent(); for (int n = 0; n != -1; ) { n = in.read(buf, 0, buf.length); } in.close();

Specify an invalid download range

Assume that you have an object that is 1,000 bytes in size. The valid download range is from 0 to 999. If the specified range is invalid, the Range header does not take effect. The response returns the HTTP status code 200 and the content of the entire object. The following table describes invalid requests and their responses.

If you set Range: bytes to 500-2000, the value at the end of the range is invalid. The content of the entire file is returned, and the HTTP status code is 200.
If you set Range: bytes to 1000-2000, the value at the start of the range is invalid. The content of the entire file is returned, and the HTTP status code is 200.

Perform a range download based on standard behavior

You can add the x-oss-range-behavior:standard request header to change the download behavior of OSS when the specified range is invalid. Assume that you have an object that is 1,000 bytes in size.

If you set Range: bytes to 500-2000, the value at the end of the range is invalid. The content within the range of 500 to 999 bytes is returned, and the HTTP status code is 206.
If you set Range: bytes to 1000-2000, the value at the start of the range is invalid. The HTTP status code 416 and the InvalidRange error code are returned.

The following code provides an example of how to perform a range download based on standard behavior.

import com.aliyun.oss.*; import com.aliyun.oss.common.auth.*; import com.aliyun.oss.common.comm.SignVersion; import com.aliyun.oss.model.GetObjectRequest; import com.aliyun.oss.model.OSSObject; public class Demo { public static void main(String[] args) throws Exception { // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. String endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider(); // Specify the bucket name. 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"; // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. String region = "cn-hangzhou"; // Create an OSSClient instance. // Call the shutdown method to release resources when the OSSClient is no longer in use. ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration(); // Explicitly declare that the V4 signature algorithm is used. clientBuilderConfiguration.setSignatureVersion(SignVersion.V4); OSS ossClient = OSSClientBuilder.create() .endpoint(endpoint) .credentialsProvider(credentialsProvider) .region(region) .build(); try { // The value at the end of the range is invalid. The content within the range of 500 to 999 bytes is returned, and the HTTP status code is 206. GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, objectName); getObjectRequest.setRange(500, 2000); getObjectRequest.addHeader("x-oss-range-behavior", "standard"); OSSObject ossObject = ossClient.getObject(getObjectRequest); ossObject.close(); System.out.println("standard get " + "500~2000 "+ "statusCode:" + ossObject.getResponse().getStatusCode()); System.out.println("standard get " + "500~2000 " + "contentLength:" + ossObject.getResponse().getContentLength()); // The value at the start of the range is invalid. The following code throws an exception. The HTTP status code 416 and the InvalidRange error code are returned. getObjectRequest = new GetObjectRequest(bucketName, objectName); getObjectRequest.setRange(1000, 2000); getObjectRequest.addHeader("x-oss-range-behavior", "standard"); OSSObject ossObject2 = ossClient.getObject(getObjectRequest); ossObject2.close(); } 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 (ClientException 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) { ossClient.shutdown(); } } } }

References

For more information about the API operation for range download, see GetObject.