Upgrade Java SDK V1 to V2

Compile-time blocking items

These changes directly cause compilation failures. The compiler can locate them one by one, so the scope of changes is relatively certain.

The output type change is the only item that requires additional manual verification: a type mismatch causes a compile-time error, but whether fields are read correctly cannot be fully exposed at compile time. You must verify this item by item in Step 6 based on core paths.

Runtime behavior changes

These changes do not block compilation, but they change how requests are authenticated and which domain names they target. The consequences of missing a change appear only at runtime.

Optional new capabilities

The following two capabilities are non-breaking additions. You can adopt them as needed; migration is complete without them.

Step 1: Update the Maven dependency

Replace the dependency coordinates in pom.xml. The V1 dependency is as follows:

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

For the V2 dependency, replace <version> with the latest version number that you find on Maven Repository:

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

V1 additionally declares JAXB-related dependencies for Java 9 or later (javax.xml.bind:jaxb-api, javax.activation:activation, and org.glassfish.jaxb:jaxb-runtime). V2 no longer needs them, so you can remove them as well.

Step 2: Change package names and imports

Replace imports of com.aliyun.oss and its subpackages with the corresponding types under com.aliyun.sdk.service.oss2. The following table lists the mappings for commonly used packages:

V2 groups its model classes in the models package. When you replace imports in bulk, import com.aliyun.sdk.service.oss2.models.* first, and then add the missing types one by one based on the compilation errors.

Step 3: Change the client creation code

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;

String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
String region = "<region-id>";
String endpoint = "<endpoint>";

DefaultCredentialProvider provider = new DefaultCredentialProvider(accessKeyId, accessKeySecret);

ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
// V1 requires V4 signatures to be declared explicitly
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);

OSS ossClient = OSSClientBuilder.create()
        .credentialsProvider(provider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)
        .endpoint(endpoint)
        .build();

// Perform OSS operations...

ossClient.shutdown();

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

CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

try (OSSClient client = OSSClient.newBuilder()
        .credentialsProvider(provider)
        .region("<region-id>")
        .build()) {

    // Perform OSS operations...

}

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

import java.util.concurrent.CompletableFuture;

try (OSSAsyncClient client = OSSAsyncClient.newBuilder()
        .credentialsProvider(new EnvironmentVariableCredentialsProvider())
        .region("<region-id>")
        .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%n", info.name(), info.region());
        }
    });

    future.join();
}

Step 4: Change the API input and output forms

V2 consolidates the input of every operation into a request object and the output into a result object. This section uses listing buckets to demonstrate the general migration pattern. Migrate other operations in the same way.

V1:

List<Bucket> buckets = ossClient.listBuckets();
for (Bucket bucket : buckets) {
    System.out.println(bucket.getName());
}

V2:

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

ListBucketsResult result = client.listBuckets(
        ListBucketsRequest.newBuilder().build());

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

Note the following three differences when you rewrite the code. First, input: even if an operation takes no parameters, you must construct a request object by using XxxRequest.newBuilder().build(). Second, output: read result fields by using accessor methods that are named after the fields (result.buckets(), info.name()) instead of the V1 getXxx() getters. Third, pagination: V1 requires you to maintain a marker loop to pull pages manually, whereas V2 provides paginator interfaces. For example, client.listBucketsPaginator(...) returns ListBucketsIterable, which you can iterate over directly to get all pages:

import com.aliyun.sdk.service.oss2.paginator.ListBucketsIterable;

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

for (ListBucketsResult page : paginator) {
    for (BucketSummary info : page.buckets()) {
        System.out.println(info.name());
    }
}

Step 5: Change the exception handling logic

V1 requires you to catch server-side and client-side exceptions separately. Both extend RuntimeException:

try {
    ossClient.putObject(...);
} catch (OSSException oe) {
    // The request reached the server but was rejected: insufficient permissions, invalid parameters, resource not found, and so on
    System.out.println("Error Code: " + oe.getErrorCode());
    System.out.println("Request ID: " + oe.getRequestId());
} catch (ClientException ce) {
    // Client-side issues: network unavailable, request timeout, certificate validation failure, and so on
    System.out.println("Error Message: " + ce.getMessage());
} finally {
    ossClient.shutdown();
}

In V2, catch the error uniformly with catch (Exception e), use ServiceException.asCause(e) to determine whether it is a server-side error, and if so read information such as requestId() and errorCode(); otherwise handle it as a client-side error:

import com.aliyun.sdk.service.oss2.exceptions.ServiceException;

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

Existing error code branches based on OSSException.getErrorCode() (such as SignatureDoesNotMatch, AccessDenied, and NoSuchKey) can be moved directly to ServiceException.errorCode(). The error code values remain the same. When you use the asynchronous client, exceptions are obtained through the CompletableFuture.exceptionally() callback, and server-side information is also extracted through ServiceException.asCause(e).

Step 6: Test and verify

Verify the migration results in the order shown in the following table. Proceed to the next item only after the current item meets its pass criteria.