Object Storage Service:Get started with OSS SDK

Prerequisites

Before you begin, make sure you have:

• An Alibaba Cloud Account

• OSS activated

Configure environment variables

Credentials are passed to the SDK through environment variables to avoid hardcoding sensitive information in your code.

echo $SHELL

Install OSS SDK for Java

java -version

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.4</version>
</dependency>

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.1</version>
</dependency>
<dependency>
    <groupId>javax.activation</groupId>
    <artifactId>activation</artifactId>
    <version>1.1.1</version>
</dependency>
<!-- no more than 2.3.3-->
<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>2.3.3</version>
</dependency>

Run the complete example

The following example covers the full workflow in a single runnable program. It uses the Singapore region (ap-southeast-1) so you can run it immediately without any endpoint changes.

The program performs six operations in sequence: creates a bucket, uploads a string as an object, downloads and reads the object, lists the bucket contents, deletes the object, then deletes the bucket.

import java.io.*;
import java.util.Random;

import com.aliyun.oss.*;
import com.aliyun.oss.model.OSSObject;
import com.aliyun.oss.model.ObjectListing;
import com.aliyun.oss.model.OSSObjectSummary;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;

public class OssJavaSdkQuickStart {
    /** Generates a unique bucket name. */
    public static String generateUniqueBucketName(String prefix) {
        // Get the current timestamp.
        String timestamp = String.valueOf(System.currentTimeMillis());
        // Generate a random number between 0 and 9999.
        Random random = new Random();
        int randomNum = random.nextInt(10000); // Generate a random number between 0 and 9999.
        // Concatenate the parts to form a unique bucket name.
        return prefix + "-" + timestamp + "-" + randomNum;
    }

    public static void main(String[] args) throws com.aliyuncs.exceptions.ClientException {
        // This example uses the Singapore region to illustrate process. Set the endpoint to https://oss-ap-southeast-1.aliyuncs.com. Replace it with the actual endpoint.
        String endpoint = "https://oss-ap-southeast-1.aliyuncs.com";
        String bucketName = generateUniqueBucketName("demo");
        // Specify the region where the bucket is located. This example uses Singapore. Set the region to ap-southeast-1.
        String region = "ap-southeast-1";

        // Obtain access credentials from environment variables. Before you run the sample code, configure the environment variables.
        EnvironmentVariableCredentialsProvider credentialsProvider =
                CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer used, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // Explicitly declare the use of the V4 signature algorithm.
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .region(region)
                .build();
        try {
            // 1. Create a bucket.
            ossClient.createBucket(bucketName);
            System.out.println("1. Bucket " + bucketName + " created.");
            // 2. Upload a file.
            String objectName = "exampledir/exampleobject.txt";
            String content = "Hello OSS";
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()));
            System.out.println("2. File " + objectName + " uploaded.");
            // 3. Download the file.
            OSSObject ossObject = ossClient.getObject(bucketName, objectName);
            InputStream contentStream = ossObject.getObjectContent();
            BufferedReader reader = new BufferedReader(new InputStreamReader(contentStream));
            String line;
            System.out.println("3. Content of the downloaded file:");
            while ((line = reader.readLine()) != null) {
                System.out.println(line);
            }
            contentStream.close();
            // 4. List files.
            System.out.println("4. Files in the bucket:");
            ObjectListing objectListing = ossClient.listObjects(bucketName);
            for (OSSObjectSummary objectSummary : objectListing.getObjectSummaries()) {
                System.out.println(" - " + objectSummary.getKey() + " (size = " + objectSummary.getSize() + ")");
            }
            // 5. Delete the file.
            ossClient.deleteObject(bucketName, objectName);
            System.out.println("5. File " + objectName + " deleted.");
            // 6. Delete the bucket.
            ossClient.deleteBucket(bucketName);
            System.out.println("6. Bucket " + bucketName + " deleted.");
        } 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 | IOException 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();
            }
        }
    }
}

A successful run produces output similar to the following:

1. Bucket demo-1731651903982-4074 created.
2. File exampledir/exampleobject.txt uploaded.
3. Content of the downloaded file:
Hello OSS
4. Files in the bucket:
 - exampledir/exampleobject.txt (size = 9)
5. File exampledir/exampleobject.txt deleted.
6. Bucket demo-1731651903982-4074 deleted.

SDKs for other languages

SDKs for other languages support the same bucket management and object operations.

• OSS Python SDK V2

• OSS Go SDK V2

• OSS PHP SDK V2

• OSS Node.js SDK

• OSS C# SDK V2 (Preview)

• OSS C# SDK V1

• OSS Java SDK V2 (Preview)

• OSS Java SDK V1

• OSS Browser.js SDK

• OSS Android SDK

• OSS iOS SDK

• OSS Harmony SDK (Preview)

• OSS Swift SDK (Preview)

• OSS Ruby SDK

• OSS C++ SDK

• OSS C SDK

What's next

Now that you have a working SDK setup, explore common follow-up tasks:

• Manage access control — set bucket and object permissions using RAM policies or bucket policies

• Configure lifecycle rules — automatically transition or delete objects based on age or access patterns

• Enable versioning — protect objects from accidental deletion or overwrite

• OSS Java SDK V1 reference — full API reference for the SDK used in this guide