Alibaba Cloud Java SDK V1.0: ECS integration and V2 migration

Why the Alibaba Cloud Java SDK V1.0 exists

The V1.0 SDK targets Java applications that call Alibaba Cloud OpenAPI services, including Elastic Compute Service, Server Load Balancer, and CloudMonitor. Its stated purpose is to keep application code away from repetitive API work such as constructing requests and signing them. That is useful for teams that want service-specific Java request and response classes rather than assembling HTTP requests by hand.

The audience is narrower than the repository name may suggest. A developer needs an Alibaba Cloud account, an `AccessKey ID`, and an `AccessKey Secret`, as well as activation of the relevant cloud product when required. The SDK also requires JDK 1.8 or later. These prerequisites mean that it is intended for server-side Java integration or other trusted application environments, not as an anonymous client for public APIs.

The decisive adoption issue is lifecycle status. The repository description and README both say that V1.0 has entered the basic security maintenance phase and is no longer recommended. They specifically direct new users to `alibabacloud-java-sdk` and also advise users with existing V1.0 integrations to migrate. The README attributes the recommended move to V2.0's improved architecture, modern security practices, credential management, feature set, and continued updates. Those are the project's stated migration reasons, not independently verified measurements.

DefaultAcsClient request flow for ECS calls

The documented ECS path follows four concrete steps. Application code creates a `DefaultProfile` from a region ID and RAM account credentials. It then constructs `DefaultAcsClient`, creates a service-specific request object, sets parameters, and submits the request through `getAcsResponse`. The SDK handles the API-related request construction and signing described by the README.

The request object carries typed parameters. In the ECS example, `DescribeInstancesRequest` receives `setPageSize(10)`. The response exposes `DescribeInstancesResponse` and an `Instances` collection, from which the example reads each instance's public IP address. This shape keeps API-specific fields inside generated-looking Java model classes rather than requiring the application to parse an unstructured response itself.

The documented control flow distinguishes two failure categories. `ServerException` is caught separately from `ClientException`, allowing application code to treat service-side and client-side failures differently if needed. The sample prints stack traces, which is sufficient to demonstrate the call but not a production logging policy. The README does not document retry behavior, timeout configuration, pagination beyond setting page size, idempotency rules, or rollback for this request flow. Those omissions matter when assessing whether the sample matches a production integration.

Maven setup for a JDK 1.8 ECS client

For an existing Maven project that temporarily requires V1.0, the README identifies two Maven modules for the ECS example: the common core and the ECS product SDK. The dependency versions are expressed as upper-bounded ranges rather than fixed releases.

The following is the README's ECS dependency configuration. Maven should resolve both modules before the example application is compiled:

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>[4.6.3,5.0.0)</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-ecs</artifactId>
    <version>[4.16.0,5.0.0)</version>
</dependency>

A first real use starts with `DescribeInstancesRequest`. Substitute a region and credentials owned by an appropriate RAM identity, then call `getAcsResponse`. The README indicates that the account must have access to the activated service, and the credentials must belong to a RAM account according to the comments in the example.

The README also says that manually added repositories can cause unresolved JAR dependencies and a `NoClassDefFoundError`. Its explicit additions are shown below. Add these only when the project's effective Maven configuration requires them, rather than assuming every build needs duplicate declarations:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>
<dependency>
    <groupId>io.opentracing</groupId>
    <artifactId>opentracing-api</artifactId>
    <version>0.33.0</version>
</dependency>
<dependency>
    <groupId>io.opentracing</groupId>
    <artifactId>opentracing-util</artifactId>
    <version>0.33.0</version>
</dependency>

The README does not supply a `mvn` invocation for a newly generated application, so this is dependency setup rather than a complete project-generation tutorial.

DescribeInstances Java call and exception boundaries

The README's Java example is short enough to expose the complete first call without introducing another API. It uses `DefaultProfile.getProfile`, creates `DefaultAcsClient`, and casts the returned `IAcsClient` call back to a typed ECS response.

The following block comes from the README. Replace each bracketed credential or region placeholder before attempting the call, and expect printed public IP addresses only if the RAM identity can perform the request and the response contains instances:

DefaultProfile profile = DefaultProfile.getProfile(
    "<your-region-id>",
    "<your-access-key-id>",
    "<your-access-key-secret>");
IAcsClient client = new DefaultAcsClient(profile);
DescribeInstancesRequest request = new DescribeInstancesRequest();
request.setPageSize(10);
DescribeInstancesResponse response;
try {
    response = client.getAcsResponse(request);
    for (DescribeInstancesResponse.Instance instance:response.getInstances()) {
        System.out.println(instance.getPublicIpAddress());
    }
} catch (ServerException e) {
    e.printStackTrace();
} catch (ClientException e) {
    e.printStackTrace();
}

This example is useful for confirming dependency resolution, region configuration, credentials, and service permission, but it is not a production credential-management design. The README mentions modern credential management as a reason to migrate to V2.0, yet the V1.0 sample directly accepts an AccessKey ID and secret. It does not show an environment variable, profile provider, RAM role, or secret store. No such mechanism should be inferred from the example.

The repository also links an OpenAPI diagnosis service for locating errors through a `RequestID` or error message. That can help diagnose an API failure, but it does not replace local exception handling in the client.

V1.0 maintenance, module sprawl, and migration cost

The repository is not archived, and its last push was on 2026-10-15. That date shows recent repository activity, but it must be read alongside the explicit lifecycle notice: V1.0 has entered basic security maintenance and is no longer recommended. A recent push does not convert the maintenance notice into an endorsement for new adoption.

The repository layout exposes the cost of the generation. Its top level contains separate modules for `aliyun-java-sdk-core`, `aliyun-java-sdk-ecs`, `aliyun-java-sdk-slb`, `aliyun-java-sdk-ram`, and many other product packages. The documented build target also packages several service modules independently, including ECS, CCC, Dysmsapi, SLB, CDN, CloudAPI, ROS, RAM, STS, VPC, and RDS. Applications can therefore need coordinated dependency decisions across several service-specific artifacts.

For an existing V1.0 application, the upgrade work is a migration rather than a fixed release bump. The repository does not provide a V1.0-to-V2.0 compatibility mapping, automatic migration tool, or list of unchanged classes in its README. Engineers must map their imported request, response, client, profile, and exception types, then verify service behavior. The README's linked differences page and V2.0 documentation are the documented starting points for that work.

The GitHub repository has no GitHub releases, so there is no repository release history to use as an upgrade cadence. The top-level `License` file is present, while the repository metadata classifies the licence as a custom licence that GitHub cannot classify. The README does not summarize its terms, so no redistribution or compliance conclusion can be drawn from the repository information.

Why V2.0 changes the adoption decision

The direct alternative is Alibaba Cloud Java SDK V2.0 in the `aliyun/alibabacloud-java-sdk` repository. This is not an unrelated client library or a lower-level HTTP alternative. It is Alibaba Cloud's replacement generation for Java OpenAPI access and is the destination named by the V1.0 project.

The documented difference is architectural and operational. V1.0 uses `DefaultProfile`, `DefaultAcsClient`, generated service-specific model classes, and exceptions such as `ClientException` and `ServerException`. The V2.0 repository and documentation do not show the replacement classes in this README, so replacement code must be taken from the V2.0 documentation rather than mechanically renaming V1.0 imports. The README states that V2.0 has an improved architecture, optimized performance, modern security practices, credential management, a richer feature set, and an improved API design. It does not provide benchmark data supporting those statements.

V2.0 is the wrong choice for an application that must remain on an already pinned V1.0 dependency graph without compatibility work. A large service integration may also be expensive to move because it can span many modules and exception paths. Conversely, V1.0 is the wrong default for a new Java service because its own documentation rejects that use. The practical distinction is migration exposure: V2.0 requires new code to follow the current API, while V1.0 can serve a legacy application temporarily while its dependencies and calls are mapped.

Editorial conclusion

Existing Java applications may use V1.0 while planning a controlled move to V2.0, but new projects and applications without a legacy dependency should choose V2.0. Before migrating, verify the selected service modules, V1 and V2 configuration differences, credential handling, and expected response behavior in the Alibaba Cloud V1/V2 migration guidance. For a new ECS integration, V2.0 is the concrete choice because the V1.0 repository explicitly says V1.0 is no longer recommended.

Frequently asked questions

Official sources

1. aliyun/aliyun-openapi-java-sdk on GitHub
2. Issues
3. README