runningInstances = new ArrayList<>();
try {
DescribeInstancesRequest request = new DescribeInstancesRequest()
.withInstanceIds(instanceIds);
DescribeInstancesResult result;
do {
// DescribeInstancesResponse is a paginated response, so use tokens with multiple re
result = ec2.describeInstances(request);
request.setNextToken(result.getNextToken()); // Prepare request for next page.
for (final Reservation r : result.getReservations()) {
for (final Instance instance : r.getInstances()) {
LOGGER.info("Examining instanceId: "+ instance.getInstanceId());
// if instance is in a running state, add it to runningInstances list.
if (RUNNING_STATES.contains(instance.getState().getName())) {
runningInstances.add(instance);
}
}
}
} while (result.getNextToken() != null);
} catch (final AmazonEC2Exception exception) {
// if instance isn't found, assume its terminated and continue.
if (exception.getErrorCode().equals(NOT_FOUND_ERROR_CODE)) {
LOGGER.info("Instance probably terminated; moving on.");
} else {
throw exception;
}
}
return runningInstances;
}
...
```
Our goal is to replace all v1 imports with v2 imports. We proceed one class at a time.
#### a. Replace import statement or class name
We see that the first parameter to the `describeRunningInstances` method is a v1 `AmazonEC2Client` instance. Do one of the following:
+ Replace the import for `com.amazonaws.services.ec2.AmazonEC2Client` with `software.amazon.awssdk.services.ec2.Ec2Client` and change `AmazonEC2Client` to `Ec2Client`.
+ Change the parameter type to `Ec2Client` and let the IDE prompt us for the correct import. Our IDE will prompt us to import the v2 class because the client names differ—`AmazonEC2Client` and `Ec2Client`. This approach does not work if the class name is the same in both versions.
#### b. Replace v1 model classes with v2 equivalents
After the change to the v2 `Ec2Client`, if we use an IDE, we see compilation errors in the following statement.
```
result = ec2.describeInstances(request);
```
The compilation error results from using an instance of v1's `DescribeInstancesRequest` as a parameter to the v2 `Ec2Client` `describeInstances` method. To fix, make the following replacement or import statements.
| replace | with |
| --- | --- |
| import com.amazonaws.services.ec2.model.DescribeInstancesRequest
| import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest
|
#### c. Change v1 constructors to v2 builders.
We still see compilation errors because there are [no constructors on v2 classes](migration-whats-different.md#immutable-classes). To fix, make the following change.
| change | to |
| --- | --- |
| final DescribeInstancesRequest request = new DescribeInstancesRequest()
.withInstanceIds(instanceIdsCopy);
| final DescribeInstancesRequest request = DescribeInstancesRequest.builder()
.instanceIds(instanceIdsCopy)
.build();
|
#### d. Replace v1 `*Result` response objects with v2 `*Response` equivalents
A consistent difference between v1 and v2 is that all [response objects in v2 end with `*Response` instead of `*Result`](migration-whats-different.md#model-classname-changes). Replace the v1 `DescribeInstancesResult` import to the v2 import, `DescribeInstancesResponse`.
#### d. Make API changes
The following statement needs a few changes.
```
request.setNextToken(result.getNextToken());
```
In v2, [setter methods](migration-whats-different.md#setter-getter-methods) do not use the `set` or with `prefix`. Getter methods prefixed with `get` are also gone in the SDK for Java 2.x
Model classes, such as the `request` instance, are immutable in v2, so we need to create a new `DescribeInstancesRequest` with a builder.
In v2, the statement becomes the following.
```
request = DescribeInstancesRequest.builder()
.nextToken(result.nextToken())
.build();
```
#### d. Repeat until method compiles with v2 classes
Continue with the rest of the code. Replace v1 imports with v2 imports and fix the compilation errors. Refer to the [v2 API Reference](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/package-summary.html) and [What's different reference](migration-whats-different.md) as needed.
After we migrate this single method, we have the following v2 code.
```
import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.RegionUtils;
import com.amazonaws.services.ec2.AmazonEC2Client;
import com.amazonaws.services.ec2.model.AmazonEC2Exception;
import com.amazonaws.services.ec2.model.CreateTagsRequest;
import com.amazonaws.services.ec2.model.InstanceStateName;
import com.amazonaws.services.ec2.model.Tag;
import com.amazonaws.services.ec2.model.TerminateInstancesRequest;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesResponse;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.Instance;
import software.amazon.awssdk.services.ec2.model.Reservation;
...
private static List getRunningInstances(Ec2Client ec2, List instanceIds) {
List runningInstances = new ArrayList<>();
try {
DescribeInstancesRequest request = DescribeInstancesRequest.builder()
.instanceIds(instanceIds)
.build();
DescribeInstancesResponse result;
do {
// DescribeInstancesResponse is a paginated response, so use tokens with multiple re
result = ec2.describeInstances(request);
request = DescribeInstancesRequest.builder() // Prepare request for next page.
.nextToken(result.nextToken())
.build();
for (final Reservation r : result.reservations()) {
for (final Instance instance : r.instances()) {
// if instance is in a running state, add it to runningInstances list.
if (RUNNING_STATES.contains(instance.state().nameAsString())) {
runningInstances.add(instance);
}
}
}
} while (result.nextToken() != null);
} catch (final Ec2Exception exception) {
// if instance isn't found, assume its terminated and continue.
if (exception.awsErrorDetails().errorCode().equals(NOT_FOUND_ERROR_CODE)) {
LOGGER.info("Instance probably terminated; moving on.");
} else {
throw exception;
}
}
return runningInstances;
}
...
```
Because we are migrating a single method in a Java file with eight methods, we have a mix of v1 and v2 imports as we work through the file. We added the last six import statements as we performed the steps.
After we migrate all the code, there will be no more v1 import statements.
### 6. Remove v1 Maven dependencies from the POM and v1 imports from files
After we migrate all v1 code in the file, we have the following v2 SDK import statements.
```
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.regions.ServiceMetadata;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.CreateTagsRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesResponse;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.Instance;
import software.amazon.awssdk.services.ec2.model.InstanceStateName;
import software.amazon.awssdk.services.ec2.model.Reservation;
import software.amazon.awssdk.services.ec2.model.Tag;
import software.amazon.awssdk.services.ec2.model.TerminateInstancesRequest;
```
After we migrate *all* files in our application, we no longer need the v1 dependencies in our POM file. Remove the v1 BOM from the `dependencyManagement` section, if using, and all v1 dependency blocks.
### 7. Refactor the code to use v2 API enhancements
For the snippet we have been migrating, we can optionally use a v2 paginator and let the SDK manage the token-based requests for more data.
We can replace the entire `do` clause with the following.
```
DescribeInstancesIterable responses = ec2.describeInstancesPaginator(request);
responses.reservations().stream()
.forEach(reservation -> reservation.instances()
.forEach(instance -> {
if (RUNNING_STATES.contains(instance.state().nameAsString())) {
runningInstances.put(instance.instanceId(), instance);
}
}));
```
## Package name to Maven artifactId mappings
When you migrate your Maven or Gradle project from v1 of the SDK for Java to v2, you need to figure out which dependencies to add to your build file. The approach described in the [Migration step-by-step instructions with example](#migration-steps) (step 3) uses the package names in import statements as a starting point to determine the dependencies (as artifactIds) to add to your build file.
You can use the information in this topic to map the v1 package names to v2 artifactIds.
### Common naming convention used in package names and Maven artifactIds
The following table shows the common naming convention that the SDKs use for a given SERVICE\$1ID. A SERVICE\$1ID is a unique identifier for an AWS service. For example, the SERVICE\$1ID for the Amazon S3 service is `s3` and `cognitoidentity` is the SERVICE\$1ID for Amazon Cognito Identity.
| v1 package name (import statement) | v1 artifactId | v2 artifactId | v2 package name (import statement) |
| --- | --- | --- | --- |
| com.amazonaws.services.SERVICE\$1ID | aws-java-sdk-SERVICE\$1ID | SERVICE\$1ID | software.amazon.awssdk.services.SERVICE\$1ID |
| |
| Example for Amazon Cognito Identity (SERVICE\$1ID: cognitoidentity) |
| com.amazonaws.services.cognitoidentity | aws-java-sdk-cognitoidentity | cognitoidentity | software.amazon.awssdk.services.cognitoidentity |
### SERVICE\$1ID differences
#### Within v1
In some cases the SERVICE\$1ID differs between the package name and in the artifactId for the same service. For example, the CloudWatch Metrics row of the following table shows that `metrics` is the SERVICE\$1ID in the package name but `cloudwatchmetrics` is the artifactId's SERVICE\$1ID.
#### Within v2
There are no differences in the SERVICE\$1ID used in package names and artifactIds.
#### Between v1 and v2
For the majority of services, the SERVICE\$1ID in v2 is the same as v1's SERVICE\$1ID in both package names and artifactIds. An example of this is the `cognitoedentity` SERVICE\$1ID as shown in the previous table. However, some SERVICE\$1IDs differ between the SDKs as shown in the following table.
A **boldface SERVICE\$1ID** in either of the v1 columns indicates that it's different from the SERVICE\$1ID used in v2.
| Service name | v1 package name | v1 artifactId | v2 artifactId | v2 package name |
| --- | --- | --- | --- | --- |
| | All package names begin with `com.amazonaws.services` as shown in the first row. | All artifactIds are enclosed in tags as shown in the first row. | All artifactIds are enclosed in tags as shown in the first row. | All package names begin with `software.amazon.awssdk` as shown in the first row. |
| |
| API Gateway | com.amazonaws.services.apigateway | aws-java-sdk-api-gateway | apigateway | software.amazon.awssdk.services.apigateway |
| App Registry | appregistry | appregistry | servicecatalogappregistry | servicecatalogappregistry |
| Application Discovery | applicationdiscovery | discovery | applicationdiscovery | applicationdiscovery |
| Augmented AI Runtime | augmentedairuntime | augmentedairuntime | sagemakera2iruntime | sagemakera2iruntime |
| Certificate Manager | certificatemanager | acm | acm | acm |
| CloudControl API | cloudcontrolapi | cloudcontrolapi | cloudcontrol | cloudcontrol |
| CloudSearch | cloudsearchv2 | cloudsearch | cloudsearch | cloudsearch |
| CloudSearch Domain | cloudsearchdomain | cloudsearch | cloudsearchdomain | cloudsearchdomain |
| CloudWatch Events | cloudwatchevents | events | cloudwatchevents | cloudwatchevents |
| CloudWatch Evidently | cloudwatchevidently | cloudwatchevidently | evidently | evidently |
| CloudWatch Logs | logs | logs | cloudwatchlogs | cloudwatchlogs |
| CloudWatch Metrics | metrics | cloudwatchmetrics | cloudwatch | cloudwatch |
| CloudWatch Rum | cloudwatchrum | cloudwatchrum | rum | rum |
| Cognito Identity Provider | cognitoidp | cognitoidp | cognitoidentityprovider | cognitoidentityprovider |
| Connect Campaign | connectcampaign | connectcampaign | connectcampaigns | connectcampaigns |
| Connect Wisdom | connectwisdom | connectwisdom | wisdom | wisdom |
| Database Migration Service | databasemigrationservice | dms | databasemigration | databasemigration |
| DataZone | datazone | datazoneexternal | datazone | datazone |
| DynamoDB | dynamodbv2 | dynamodb | dynamodb | dynamodb |
| Elastic File System | elasticfilesystem | efs | efs | efs |
| Elastic Map Reduce | elasticmapreduce | emr | emr | emr |
| Glue DataBrew | gluedatabrew | gluedatabrew | databrew | databrew |
| IAM Roles Anywhere | iamrolesanywhere | iamrolesanywhere | rolesanywhere | rolesanywhere |
| Identity Management | identitymanagement | iam | iam | iam |
| IoT Data | iotdata | iot | iotdataplane | iotdataplane |
| Kinesis Analytics | kinesisanalytics | kinesis | kinesisanalytics | kinesisanalytics |
| Kinesis Firehose | kinesisfirehose | kinesis | firehose | firehose |
| Kinesis Video Signaling Channels | kinesisvideosignalingchannels | kinesisvideosignalingchannels | kinesisvideosignaling | kinesisvideosignaling |
| Lex | lexruntime | lex | lexruntime | lexruntime |
| Lookout For Vision | lookoutforvision | lookoutforvision | lookoutvision | lookoutvision |
| Mainframe Modernization | mainframemodernization | mainframemodernization | m2 | m2 |
| Marketplace Metering | marketplacemetering | marketplacemeteringservice | marketplacemetering | marketplacemetering |
| Managed Grafana | managedgrafana | managedgrafana | grafana | grafana |
| Mechanical Turk | mturk | mechanicalturkrequester | mturk | mturk |
| Migration Hub Strategy Recommendations | migrationhubstrategyrecommendations | migrationhubstrategyrecommendations | migrationhubstrategy | migrationhubstrategy |
| Nimble Studio | nimblestudio | nimblestudio | nimble | nimble |
| Private 5G | private5g | private5g | privatenetworks | privatenetworks |
| Prometheus | prometheus | prometheus | amp | amp |
| Recycle Bin | recyclebin | recyclebin | rbin | rbin |
| Redshift Data API | redshiftdataapi | redshiftdataapi | redshiftdata | redshiftdata |
| Route 53 | route53domains | route53 | route53domains | route53domains |
| Sage Maker Edge Manager | sagemakeredgemanager | sagemakeredgemanager | sagemakeredge | sagemakeredge |
| Security Token | securitytoken | sts | sts | sts |
| Server Migration | servermigration | servermigration | sms | sms |
| Simple Email | simpleemail | ses | ses | ses |
| Simple Email V2 | simpleemailv2 | sesv2 | sesv2 | sesv2 |
| Simple Systems Management | simplesystemsmanagement | ssm | ssm | ssm |
| Simple Workflow | simpleworkflow | simpleworkflow | swf | swf |
| Step Functions | stepfunctions | stepfunctions | sfn | sfn |