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

Prerequisites

Java 8 or later.

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

Install the SDK

You can use Maven to install the OSS SDK for Java 2.0.

<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

You can configure access credentials by setting environment variables with the AccessKey pair of a RAM user.

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

• OSSClient implements AutoCloseable. If you create an instance using a try-with-resources statement, resources are automatically released. You do not need to call close() manually.

• Creating and destroying an OSSClient instance is a time-consuming operation. We recommend that you use the singleton pattern to reuse an OSSClient instance. If you use this pattern, you must call close() manually before the application terminates to prevent resource leaks.

  Singleton pattern

  Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

  public class OssClientSingleton {
      private OssClientSingleton() {}
  
      private static class Holder {
          private static final OSSClient INSTANCE = OSSClient.newBuilder()
              .credentialsProvider(new EnvironmentVariableCredentialsProvider())
              .region("<region-id>")
              .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 = "<region-id>";

        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 = "<region-id>";
        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

If you use the default OSS domain name for access, you may encounter issues such as files being inaccessible or failing to be previewed. If you use a custom domain name to access OSS, you can preview files directly in a browser and use a CDN for accelerated content delivery.

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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.
        String region = "<region-id>";

        // 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

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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.
        String region = "<region-id>";

        // 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

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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.
        String region = "<region-id>";

        // 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

You can use disableSsl(true) to disable HTTPS.

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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.
        String region = "<region-id>";

        // 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

You can use an internal endpoint to access OSS resources in the same region. This reduces traffic costs and improves access speed.

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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.
        String region = "<region-id>";

        // // Method 2: Directly specify the region and endpoint.
        // // Specify the region where the bucket is located.
        // String region = "<region-id>";
        // // Specify the internal endpoint for the bucket's region.
        // String endpoint = "<endpoint>";

        // 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

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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.
        String region = "<region-id>";

        // // Method 2: Directly specify the region and transfer acceleration endpoint.
        // // Specify the region where the bucket is located.
        // String region = "<region-id>";
        // // 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

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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.
        String region = "<region-id>";

        // 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 custom HTTPClient

If the standard configuration parameters do not meet your needs, you can use a custom HTTP client.

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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.
        String region = "<region-id>";

        // 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 preceding credential configuration methods do not meet your needs, you can implement a custom method for obtaining credentials. The Java SDK provides multiple ways to do this.

Implement through the Supplier interface

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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("<region-id>") // 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

If you only need to access public-read OSS resources, you can use anonymous access without providing credentials.

Before you run the sample code, replace <region-id> with the actual region and endpoint, such as ap-southeast-1.

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("<region-id>") // 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());
        }
    }
}