Quick start

Last Updated: Dec 21, 2017

It is necessary to understand OSS Basic Concepts, such as bucket, object, endpoint, AccessKeyId, and AccessKeySecret.

This document describes how to use the OSS Java SDK to perform common operations, such as bucket creation, object upload, and object download.

Initialize OSSClient

Before you send an HTTP request to OSS, you must create an OSSClient instance first:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // The Alibaba Cloud account AccessKey gives you permission to access all APIs, so we suggest you follow Alibaba Cloud Best Practices and create and use an RAM sub-account for API access or daily O&M. To create an RAM sub-account, log on to https://ram.console.aliyun.com
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // Access the OSS
  9. // Disable the OSSClient
  10. ossClient.shutdown();

Note: For more OSSClient initialization content, see Initialization.

Create a bucket

A bucket is a global namespace on OSS used to store objects. It is equivalent to a data container.

The following code creates a bucket:

  1. ossClient.createBucket("<bucketName>");


Upload an object

The following code uploads an object to OSS:

  1. String content = "Hello OSS";
  2. ossClient.putObject("<bucketName>", "<key>", new ByteArrayInputStream(content.getBytes()));


  • The Java SDK uploads the object to OSS through InputStream.

  • For more information on object uploading, see Object Uploading.

Download an object

The following code retrieves the textual content of an object:

  1. OSSObject ossObject = ossClient.getObject("<bucketName>", "<key>"));
  2. InputStream content = ossObject.getObjectContent();
  3. if (content != null) {
  4. BufferedReader reader = new BufferedReader(new InputStreamReader(content));
  5. while (true) {
  6. String line = reader.readLine();
  7. if (line == null) break;
  8. System.out.println("\n" + line);
  9. }
  10. content.close();
  11. }


  • OSSClient.GetObject can be called to return an OSSObject instance which contains the object content and its metadata.

  • OSSObject.GetObjectContent can be called to retrieve the input stream of an object. You can read the input stream to retrieve the object content. Close the stream after you use it.

  • For more information on object downloading, see Object Downloading.

List an object

Once you upload objects to a bucket, you may need to check the objects in a bucket. The following code lists the objects in a specified bucket:

  1. ObjectListing objectListing = ossClient.listObjects("<bucketName>");
  2. for (OSSObjectSummary objectSummary : objectListing.getObjectSummaries()) {
  3. System.out.println(" - " + objectSummary.getKey() + " " +
  4. "(size = " + objectSummary.getSize() + ")");
  5. }

You can call OSSClient#listObjects to return the ObjectListing instance which contains the returned result for the listObject request. You can use ObjetListing#getObjectSummaries to retrieve the descriptive information of all the objects.


  • The preceding code lists 100 objects by default.

  • For richer listing features, see List objects in a bucket in Object Management.

Delete an object

The following code deletes an object:

  1. ossClient.deleteObject("<bucketName>", "<key>")


  • If no exception is thrown when the OSS Java SDK operation is completed successfully, the returned value is valid. If an exception is thrown, it indicates the operation is failed and the returned data is invalid.

  • Complete code can be found at GitHub.

Thank you! We've received your feedback.