Object Storage Service:OSS SDK for Java 2.0 (preview)

Prerequisites

Java 8 or later.

Run the java -version command to check your Java version. If Java is not installed, or if the version is earlier than Java 8, download and install Java.

Install the SDK

Add the SDK dependency via Maven or build from source.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>alibabacloud-oss-v2</artifactId>
    <version><!-- Specify the latest version number--></version>
</dependency>

mvn clean install -DskipTests -Dgpg.skip=true

Configure access credentials

Set environment variables with a RAM user's AccessKey pair.

In the RAM console, create a RAM user with Permanent AccessKey Pair access. Save the AccessKey pair, and grant the AliyunOSSFullAccess permission to the user.

Initialize the client

Initialize the OSSClient by specifying a region.

• OSSClient implements AutoCloseable. With try-with-resources, resources are released automatically without calling close().

• Creating and destroying OSSClient is expensive. Use the singleton pattern to reuse a single instance, and call close() explicitly before the application exits.

  Singleton pattern

  public class OssClientSingleton {
      private OssClientSingleton() {}
  
      private static class Holder {
          private static final OSSClient INSTANCE = OSSClient.newBuilder()
              .credentialsProvider(new EnvironmentVariableCredentialsProvider())
              .region("cn-hangzhou")
              .build();
      }
  
      public static OSSClient getInstance() {
          return Holder.INSTANCE;
      }
  
      // Close the OSSClient instance. This must be explicitly called.
      public static void shutdown() {
          try {
              getInstance().close();
          } catch (Exception e) {
              // Handle the close exception.
          }
      }
  }
  

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.exceptions.ServiceException;
import com.aliyun.sdk.service.oss2.models.*;
import com.aliyun.sdk.service.oss2.paginator.ListBucketsIterable;

public class Example {
    public static void main(String[] args) {
        String region = "cn-hangzhou";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        OSSClientBuilder clientBuilder = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region);

        try (OSSClient client = clientBuilder.build()) {

            ListBucketsIterable paginator = client.listBucketsPaginator(
                    ListBucketsRequest.newBuilder()
                            .build());

            for (ListBucketsResult result : paginator) {
                for (BucketSummary info : result.buckets()) {
                    System.out.printf("bucket: name:%s, region:%s, storageClass:%s\n", info.name(), info.region(), info.storageClass());
                }
            }

        } catch (Exception e) {
//            ServiceException se = ServiceException.asCause(e);
//            if (se != null) {
//                System.out.printf("ServiceException: requestId:%s, errorCode:%s\n", se.requestId(), se.errorCode());
//            }
            System.out.printf("error:\n%s", e);
        }
    }
}

import com.aliyun.sdk.service.oss2.OSSAsyncClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.exceptions.ServiceException;
import com.aliyun.sdk.service.oss2.models.*;

import java.util.concurrent.CompletableFuture;

public class ExampleAsync {
    public static void main(String[] args) {
        String region = "cn-hangzhou";
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSAsyncClient client = OSSAsyncClient.newBuilder()
                .region(region)
                .credentialsProvider(provider)
                .build()) {

            CompletableFuture<ListBucketsResult> future = client.listBucketsAsync(
                    ListBucketsRequest.newBuilder().build()
            );

            future.thenAccept(result -> {
                        for (BucketSummary info : result.buckets()) {
                            System.out.printf("bucket: name:%s, region:%s, storageClass:%s\n",
                                    info.name(), info.region(), info.storageClass());
                        }
                    })
                    .exceptionally(e -> {
//                ServiceException se = ServiceException.asCause(e);
//                if (se != null) {
//                    System.out.printf("Async ServiceException: requestId:%s, errorCode:%s\n",
//                            se.requestId(), se.errorCode());
//                }
                        System.out.printf("async error:\n%s\n", e);
                        return null;
                    });

            future.join();

        } catch (Exception e) {
            System.out.printf("main error:\n%s\n", e);
        }
    }
}

Use a custom domain name

Using the default OSS domain name may cause files to be inaccessible or fail to preview. Bind a custom domain name to enable browser preview and CDN acceleration.

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Specify your custom domain name. For example, www.example-***.com.
        String endpoint = "https://www.example-***.com";

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                // Note: Set useCName to true to enable the CNAME option. Otherwise, you cannot use a custom domain name.
                .useCName(true)
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Timeout control

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // Set the timeout for establishing a connection. The default value is 5 seconds.
                .connectTimeout(Duration.ofSeconds(30))
                // Set the timeout for reading and writing data. The default value is 20 seconds.
                .readWriteTimeout(Duration.ofSeconds(30))
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Retry policy

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import com.aliyun.sdk.service.oss2.retry.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        /*
         * SDK retry policy configuration description:
         *
         * Default retry policy:
         * When no retry policy is configured, the SDK uses StandardRetryer as the default client implementation.
         * Its default configuration is as follows:
         * - maxAttempts: Sets the maximum number of attempts. The default is 3.
         * - maxBackoff: Sets the maximum backoff time in seconds. The default is 20 seconds.
         * - baseDelay: Sets the base delay time in seconds. The default is 0.2 seconds.
         * - backoffDelayer: Sets the backoff algorithm. The default is the FullJitter backoff algorithm.
         *   Formula: [0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
         * - errorRetryables: Retryable error types, including HTTP status codes, service error codes, and client errors.
         *
         * When a retryable error occurs, the provided configuration is used to delay and then retry the request.
         * The overall latency of the request increases with the number of retries. If the default configuration
         * does not meet your scenario requirements, you can configure retry parameters or modify the retry implementation.
         */

        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Retry policy configuration example:

        // 1. Customize the maximum number of retries (default is 3, here set to 5).
        Retryer customRetryer = StandardRetryer.newBuilder()
                .maxAttempts(5)
                .build();

        // 2. Customize the backoff delay time.
        // Adjust the baseDelay to 0.5 seconds (default 0.2 seconds) and maxBackoff to 25 seconds (default 20 seconds).
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FullJitterBackoff(Duration.ofMillis(500), Duration.ofSeconds(25)))
        //         .build();

        // 3. Customize the backoff algorithm.
        // Use a fixed-delay backoff algorithm instead of the default FullJitter algorithm, with a 2-second delay each time.
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FixedDelayBackoff(Duration.ofSeconds(2)))
        //         .build();

        // 4. Disable the retry policy.
        // To disable all retry attempts, use the NopRetryer implementation.
        // Retryer customRetryer = new NopRetryer();

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .retryer(customRetryer)
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

HTTP/HTTPS protocol

Use disableSsl(true) to disable the HTTPS protocol.

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // Set to not use HTTPS requests.
                .disableSsl(true)
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Use an internal endpoint

Use an internal endpoint to access OSS within the same region, reducing traffic costs and improving speed.

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Method 1: Specify the region and set useInternalEndpoint to true.
        // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // // Method 2: Directly specify the region and endpoint.
        // // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        // String region = "cn-hangzhou";
        // // Specify the internal endpoint for the bucket's region. For China (Hangzhou), the endpoint is 'oss-cn-hangzhou-internal.aliyuncs.com'.
        // String endpoint = "oss-cn-hangzhou-internal.aliyuncs.com";

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .useInternalEndpoint(true)
                // .endpoint(endpoint) // If using Method 2, uncomment this line and comment out the previous one.
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Use a transfer acceleration endpoint

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Method 1: Specify the region and set useAccelerateEndpoint to true.
        // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // // Method 2: Directly specify the region and transfer acceleration endpoint.
        // // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        // String region = "cn-hangzhou";
        // // Specify the transfer acceleration endpoint for the bucket's region, for example, 'https://oss-accelerate.aliyuncs.com'.
        // String endpoint = "https://oss-accelerate.aliyuncs.com";

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .useAccelerateEndpoint(true)
                // .endpoint(endpoint) // If using Method 2, uncomment this line and comment out the previous one.
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Use a private domain

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Specify your private domain. For example: https://service.corp.example.com
        String endpoint = "https://service.corp.example.com";

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Use a Gov Cloud domain name

Configure an OSSClient using an Alibaba Gov Cloud domain name.

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Specify the region and endpoint.
        // Specify the region where the bucket is located. For China (Beijing) Gov Cloud 1, set the region to cn-north-2-gov-1.
        String region = "cn-north-2-gov-1";
        // Specify the internal endpoint for the bucket's region. For China (Beijing) Gov Cloud 1, the endpoint is 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com'.
        // To specify the HTTP protocol, set the domain to 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'.
        String endpoint = "https://oss-cn-north-2-gov-1-internal.aliyuncs.com";

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Use a custom HTTPClient

Use a custom HTTP client when the standard configuration parameters are insufficient.

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import com.aliyun.sdk.service.oss2.transport.HttpClient;
import com.aliyun.sdk.service.oss2.transport.HttpClientOptions;
import com.aliyun.sdk.service.oss2.transport.apache5client.Apache5HttpClientBuilder;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        // Load credential information from environment variables for identity verification.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Specify the region where the bucket is located. For example, for China (Hangzhou), set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Set the parameters for the HTTP client.
        HttpClientOptions httpClientOptions = HttpClientOptions.custom()
                // Connection timeout. The default value is 5 seconds.
                .connectTimeout(Duration.ofSeconds(30))
                // Timeout for reading and writing data. The default value is 20 seconds.
                .readWriteTimeout(Duration.ofSeconds(30))
                // Maximum number of connections. The default value is 1024.
                .maxConnections(2048)
                // Specifies whether to skip certificate verification. By default, this is false.
                .insecureSkipVerify(false)
                // Specifies whether to enable HTTP redirection. By default, this is disabled.
                .redirectsEnabled(false)
                // Set the proxy server.
                // .proxyHost("http://user:passswd@proxy.example-***.com")
                .build();

        // Create an HTTP client and pass in the HTTP client parameters.
        HttpClient httpClient = Apache5HttpClientBuilder.create()
                .options(httpClientOptions)
                .build();

        // Create an OSS client with the configured information.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .httpClient(httpClient)
                .build()) {

            // Use the created client for subsequent operations...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Use custom access credentials

If the built-in credential methods are insufficient, implement a custom credential provider.

Implement through the Supplier interface

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.Credentials;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProviderSupplier;

public class OSSExample {
    public static void main(String[] args) {
        // Create a custom credential provider.
        CredentialsProvider credentialsProvider = new CredentialsProviderSupplier(() -> {
            // TODO: Implement your custom credential retrieval logic.
            
            // Return long-term credentials.
            return new Credentials("access_key_id", "access_key_secret");
            
            // Return an STS token (if needed).
            // return new Credentials("sts_access_key_id", "sts_access_key_secret", "security_token");
        });
        
        // Create an OSS client.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("cn-hangzhou") // Specify the region where the bucket is located.
                .build()) {
            
            // Use the created client for subsequent operations...
            
        } catch (Exception e) {
            System.err.println("Operation failed: " + e.getMessage());
        }
    }
}

Anonymous access

Access public-read OSS resources without providing credentials.

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.AnonymousCredentialsProvider;

public class OSSExample {
    public static void main(String[] args) {
        // Create an anonymous credential provider.
        CredentialsProvider credentialsProvider = new AnonymousCredentialsProvider();
        
        // Create an OSS client.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("cn-hangzhou") // Specify the region where the bucket is located.
                .build()) {
            
            // Use the created client for subsequent operations...
            // Note: Anonymous access can only be used for resources with public-read permissions.
            
        } catch (Exception e) {
            System.err.println("Operation failed: " + e.getMessage());
        }
    }
}