Quick start

Last Updated: Apr 18, 2018

It is useful to understand the OSS basic concepts. To learn more about bucket, object, endpoint, AccessKeyID, and AccessKeySecret, see OSS Basic Concepts.

This article 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 as an example. Other regions can be entered 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 recommend that 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 OSS
  9. // Disable the OSSClient
  10. ossClient.shutdown();

Note: For more information about OSSClient initialization, 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, 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, see Object Downloading.

List an object

After you upload objects to a bucket, you can view the objects in the 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. Use ObjectListing#getObjectSummaries to retrieve the descriptive information of all the objects.


  • The preceding code lists 100 objects by default.

  • For more information, 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 once the OSS Java SDK operation is successfully completed, the returned value is valid. If an exception is thrown, it indicates the operation is failed and the returned value is invalid.

  • Complete code can be found at GitHub.

Thank you! We've received your feedback.