| Direct resumable object | Not Supported |
### Result objects
| V1 class | V2 class | Migration status |
| --- | --- | --- |
| CopyResult | CompletedCopy | Supported |
| UploadResult | CompletedUpload | Supported |
### Configuration objects
| V1 class | V2 class | Migration status |
| --- | --- | --- |
| TransferManagerConfiguration | MultipartConfiguration (on Amazon S3 client) | Supported |
| TransferProgress | TransferProgress \$1 TransferProgressSnapshot | Supported |
| KeyFilter | DownloadFilter | Supported |
### Unsupported objects
| V1 class | V2 alternative | Migration status |
| --- | --- | --- |
| PauseStatus | Not supported | Not Supported |
| UploadContext | Not supported | Not Supported |
| ObjectCannedAclProvider | PutObjectRequest.builder().acl() | Not Supported |
| ObjectMetadataProvider | PutObjectRequest.builder().metadata() | Not Supported |
| ObjectTaggingProvider | PutObjectRequest.builder().tagging() | Not Supported |
| PresignedUrlDownload | Not supported | Not Supported |
## TransferManagerBuilder configuration migration
### Configuration changes
The configuration changes that you need to set for the v2 transfer manager depend on which S3 client that you use. You have the choice of the AWS CRT-based S3 client or the standard Java-based S3 async client. For information about the differences, see the [S3 clients in the AWS SDK for Java 2.x](examples-s3.md#s3-clients) topic.
------
#### [ Use the AWS CRT-based S3 client ]
****
| Setting | v1 | v2 - Transfer Manager using AWS CRT-based S3 client |
| --- | --- | --- |
| (get a builder) | TransferManagerBuilder tmBuilder =
TransferManagerBuilder.standard();
| S3TransferManager.Builder tmBuilder =
S3TransferManager.builder();
|
| S3 client | tmBuilder.withS3Client(...);
tmBuilder.setS3Client(...);
| tmBuilder.s3Client(...);
|
| Executor | tmBuilder.withExecutorFactory(...);
tmBuilder.setExecutorFactory(...);
| tmBuilder.executor(...);
|
| Shutdown thread pools | tmBuilder.withShutDownThreadPools(...);
tmBuilder.setShutdownThreadPools(...);
| Not supported. The provided executor will not be shut down when the S3TransferManager is closed |
| Minimum upload part size | tmBuilder.withMinimumUploadPartSize(...);
tmBuilder.setMinimumUploadPartSize(...);
| S3AsyncClient s3 = S3AsyncClient.crtBuilder().
minimumPartSizeInBytes(...).build();
tmBuilder.s3Client(s3);
|
| Multipart upload threshold | tmBuilder.withMultipartUploadThreshold(...);
tmBuilder.setMultipartUploadThreshold(...);
| S3AsyncClient s3 = S3AsyncClient.crtBuilder().
thresholdInBytes(...).build();
tmBuilder.s3Client(s3);
|
| Minimum copy part size | tmBuilder.withMultipartCopyPartSize(...);
tmBuilder.setMultipartCopyPartSize(...);
| S3AsyncClient s3 = S3AsyncClient.crtBuilder().
minimumPartSizeInBytes(...).build();
tmBuilder.s3Client(s3);
|
| Multipart copy threshold | tmBuilder.withMultipartCopyThreshold(...);
tmBuilder.setMultipartCopyThreshold(...);
| S3AsyncClient s3 = S3AsyncClient.crtBuilder().
thresholdInBytes(...).build();
tmBuilder.s3Client(s3);
|
| Disable parallel downloads | tmBuilder.withDisableParallelDownloads(...);
tmBuilder.setDisableParallelDownloads(...);
| Disable parallel downloads by passing a standard Java-based S3 client with multipart disabled (default) to the transfer manager.S3AsyncClient s3 =
S3AsyncClient.builder().build();
tmBuilder.s3Client(s3);
|
| Always calculate multipart md5 | tmBuilder.withAlwaysCalculateMultipartMd5(...);
tmBuilder.setAlwaysCalculateMultipartMd5(...);
| Not supported. |
------
#### [ Use Java-based S3 async client ]
****
| Setting | v1 | v2 - Transfer Manager using Java-based S3 async client |
| --- | --- | --- |
| (get a builder) | TransferManagerBuilder tmBuilder =
TransferManagerBuilder.standard();
| S3TransferManager.Builder tmBuilder =
S3TransferManager.builder();
|
| S3 client | tmBuilder.withS3Client(...);
tmBuilder.setS3Client(...);
| tmBuilder.s3Client(...);
|
| Executor | tmBuilder.withExecutorFactory(...);
tmBuilder.setExecutorFactory(...);
| tmBuilder.executor(...);
|
| Shutdown thread pools | tmBuilder.withShutDownThreadPools(...);
tmBuilder.setShutdownThreadPools(...);
| Not supported. The provided executor will not be shut down when the S3TransferManager is closed |
| Minimum upload part size | tmBuilder.withMinimumUploadPartSize(...);
tmBuilder.setMinimumUploadPartSize(...);
| S3AsyncClient s3 = S3AsyncClient.builder()
.multipartConfiguration(cfg ->
cfg.minimumPartSizeInBytes(...)).build();
tmBuilder.s3Client(s3);
|
| Multipart upload threshold | tmBuilder.withMultipartUploadThreshold(...);
tmBuilder.setMultipartUploadThreshold(...);
| S3AsyncClient s3 = S3AsyncClient.builder()
.multipartConfiguration(cfg ->
cfg.thresholdInBytes(...)).build();
tmBuilder.s3Client(s3);
|
| Minimum copy part size | tmBuilder.withMultipartCopyPartSize(...);
tmBuilder.setMultipartCopyPartSize(...);
| S3AsyncClient s3 = S3AsyncClient.builder()
.multipartConfiguration(cfg ->
cfg.minimumPartSizeInBytes(...)).build();
tmBuilder.s3Client(s3);
|
| Multipart copy threshold | tmBuilder.withMultipartCopyThreshold(...);
tmBuilder.setMultipartCopyThreshold(...);
| S3AsyncClient s3 = S3AsyncClient.builder()
.multipartConfiguration(cfg ->
cfg.thresholdInBytes(...)).build();
tmBuilder.s3Client(s3);
|
| Disable parallel downloads | tmBuilder.withDisableParallelDownloads(...);
tmBuilder.setDisableParallelDownloads(...);
| Disable parallel downloads by passing a standard Java-based S3 client with multipart disabled (default) to the transfer manager.S3AsyncClient s3 =
S3AsyncClient.builder().build();
tmBuilder.s3Client(s3);
|
| Always calculate multipart md5 | tmBuilder.withAlwaysCalculateMultipartMd5(...);
tmBuilder.setAlwaysCalculateMultipartMd5(...);
| Not supported. |
------
## Behavior changes
### Asynchronous operations
**V1 (blocking):**
```
Upload upload = transferManager.upload("amzn-s3-demo-bucket", "key", file);
upload.waitForCompletion(); // Blocks until complete
```
**V2 (asynchronous):**
```
FileUpload upload = transferManager.uploadFile(UploadFileRequest.builder()
.putObjectRequest(PutObjectRequest.builder()
.bucket("amzn-s3-demo-bucket")
.key("key")
.build())
.source(file)
.build());
CompletedFileUpload result = upload.completionFuture().join(); // Blocks until complete
// Or handle asynchronously:
upload.completionFuture().thenAccept(result -> {
System.out.println("Upload completed: " + result.response().eTag());
});
```
### Error handling
**V1:** Directory transfers fail completely if any sub-request fails.
**V2:** Directory transfers complete successfully even if some sub-requests fail. Check for errors explicitly:
```
DirectoryUpload directoryUpload = transferManager.uploadDirectory(request);
CompletedDirectoryUpload result = directoryUpload.completionFuture().join();
// Check for failed transfers
if (!result.failedTransfers().isEmpty()) {
System.out.println("Some uploads failed:");
result.failedTransfers().forEach(failed ->
System.out.println("Failed: " + failed.exception().getMessage()));
}
```
### Parallel download via byte-range fetches
When the automatic parallel transfer feature is enabled in the v2 SDK, the S3 Transfer Manager uses [byte-range fetches](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance-guidelines.html#optimizing-performance-guidelines-get-range) to retrieve specific portions of the object in parallel (multipart download). The way an object is downloaded with v2 does not depend on how the object was originally uploaded. All downloads can benefit from high throughput and concurrency.
In contrast, with v1's Transfer Manager, it does matter how the object was originally uploaded. The v1 Transfer Manager retrieves the parts of the object the same way that the parts were uploaded. If an object was originally uploaded as a single object, the v1 Transfer Manager is not able to accelerate the downloading process by using sub-requests.
# Changes in parsing Amazon S3 URIs from version 1 to version 2
This topic details the changes in parsing Amazon S3 URIs from version 1 (v1) to version 2 (v2.).
## High-level changes
To begin parsing an S3 URI in v1, you instantiate an `AmazonS3URI` by using a constructor. In v2 you call `parseUri()` on an instance of `S3Utilities`, to return an `S3URI`.
****
| Change | v1 | v2 |
| --- | --- | --- |
| Maven dependencies |
com.amazonaws
aws-java-sdk-bom
1.12.5871
pom
import
com.amazonaws
s3
|
software.amazon.awssdk
bom
2.27.212
pom
import
software.amazon.awssdk
s3
|
| Package name | com.amazonaws.services.s3 | software.amazon.awssdk.services.s3 |
| Class names | [AmazonS3URI](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3URI.html) | [S3URI](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Uri.html) |
1 [Latest version](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). 2 [Latest version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
## API changes
| Behavior | v1 | v2 |
| --- | --- | --- |
| Parse an S3 URI. | URI uri = URI.create( "https://s3.amazonaws.com");
AmazonS3Uri s3Uri =
new AmazonS3URI(uri, false);
| S3Client s3Client = S3Client.create();
S3Utilities s3Utilities =
s3Client.utilities();
S3Uri s3Uri =
s3Utilities.parseUri(uri);
|
| Retrieve the bucket name from an S3 URI. | String bucket = s3Uri.getBucket();
| Optional bucket = s3Uri.bucket();
|
| Retrieve the key. | String key = s3Uri.getKey();
| Optional key = s3Uri.key();
|
| Retrieve the region. | String region = s3Uri.getRegion();
| Optional region = s3Uri.region();
String region;
if (s3Uri.region().isPresent()) {
region = s3Uri.region().get().id();
}
|
| Retrieve whether the S3 URI is path style. | boolean isPathStyle = s3Uri.isPathStyle();
| boolean isPathStyle = s3Uri.isPathStyle();
|
| Retrieve the version ID. | String versionId = s3Uri.getVersionId();
| Optional versionId =
s3Uri.firstMatchingRawQueryParameter("versionId");
|
| Retrieve the query parameters. | N/A | Map> queryParams =
s3Uri.rawQueryParameters();
|
### Behavior changes
#### URL encoding
v1 provides the option to pass in a flag to specify whether the URI should be URL encoded. The default value is `true`.
In v2, URL encoding is not supported. If you work with object keys or query parameters that have reserved or unsafe characters, you must URL encode them. For example you need to replace a whitespace `" "` with `%20`.
# Changes in the S3 Event Notifications API from version 1 to version 2
This topic details the changes in the S3 Event Notifications API from version 1.x (v1) to version 2 .x (v2) of the AWS SDK for Java.
## High-level changes
### Structural changes
V1 uses static inner classes for `EventNotificationRecord` types and their attributes, whereas v2 uses separate public classes for `EventNotificationRecord` types.
### Naming convention changes
In v1, attribute class names include the suffix *Entity*, whereas v2 omits this suffix for simpler naming: for example, *eventData* instead of *eventDataEntity*.
## Changes in dependencies, packages and class names
In v1, S3 Event Notification API classes are transitively imported with along with the S3 module (artifactId `aws-java-sdk-s3`). However, in v2, you need to add a dependency on the `s3-event-notifications` artifact.
****
| Change | v1 | v2 |
| --- | --- | --- |
| Maven dependencies |
com.amazonaws
aws-java-sdk-bom
1.X.X
pom
import
com.amazonaws
aws-java-sdk-s3
|
software.amazon.awssdk
bom
2.X.X1
pom
import
software.amazon.awssdk
s3-event-notifications
|
| Package name | com.amazonaws.services.s3.event | software.amazon.awssdk.eventnotifications.s3.model |
| Class names | [S3EventNotification](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.html) [S3EventNotification.S3EventNotificationRecord](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3EventNotificationRecord.html) [ S3EventNotification.GlacierEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.GlacierEventDataEntity.html) [S3EventNotification.IntelligentTieringEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.IntelligentTieringEventDataEntity.html) [S3EventNotification.LifecycleEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.LifecycleEventDataEntity.html) [S3EventNotification.ReplicationEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.ReplicationEventDataEntity.html) [S3EventNotification.RequestParametersEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.RequestParametersEntity.html) [S3EventNotification.ResponseElementsEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.ResponseElementsEntity.html) [S3EventNotification.RestoreEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.RestoreEventDataEntity.html) [S3EventNotification.S3BucketEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3BucketEntity.html) [ S3EventNotification.S3Entity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3Entity.html) [S3EventNotification.S3ObjectEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.S3ObjectEntity.html) [S3EventNotification.TransitionEventDataEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.TransitionEventDataEntity.html) [S3EventNotification.UserIdentityEntity](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/event/S3EventNotification.UserIdentityEntity.html) | [S3EventNotification](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3EventNotification.html) [S3EventNotificationRecord](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3EventNotificationRecord.html) [GlacierEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/GlacierEventData.html) [IntelligentTieringEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/IntelligentTieringEventData.html) [LifecycleEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/LifecycleEventData.html) [ReplicationEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/ReplicationEventData.html) [RequestParameters](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/RequestParameters.html) [ResponseElements](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/ResponseElements.html) [RestoreEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/RestoreEventData.html) [S3Bucket](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3Bucket.html) [S3](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3.html) [S3Object](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/S3Object.html) [TransitionEventData](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/TransitionEventData.html) [UserIdentity](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/eventnotifications/s3/model/UserIdentity.html) |
1 [Latest version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
## API changes
### JSON to `S3EventNotification` and reverse
| Use case | v1 | v2 |
| --- | --- | --- |
| Create S3EventNotification from JSON String | S3EventNotification notification =
S3EventNotification.parseJson(message.body());
| S3EventNotification notification =
S3EventNotification.fromJson(message.body());
|
| Convert S3EventNotification to JSON String | String json = notification.toJson();
| String json = notification.toJson();
|
### Access attributes of `S3EventNotification`
| Use case | v1 | v2 |
| --- | --- | --- |
| Retrieve records from a notification | List records =
notifcation.getRecords();
| List records =
notification.getRecords();
|
| Retrieve a record from a list of records | S3EventNotification.S3EventNotificationRecord record =
records.stream().findAny().get();
| S3EventNotificationRecord record =
records.stream().findAny().get();
|
| Retrieve Glacier event data | S3EventNotification.GlacierEventDataEntity glacierEventData =
record.getGlacierEventData();
| GlacierEventData glacierEventData =
record.getGlacierEventData();
|
| Retrieve restore event data from a Glacier event | S3EventNotification.RestoreEventDataEntity restoreEventData =
glacierEventData.getRestoreEventDataEntity();
| RestoreEventData restoreEventData =
glacierEventData.getRestoreEventData();
|
| Retrieve request parameters | S3EventNotification.RequestParametersEntity requestParameters =
record.getRequestParameters();
| RequestParameters requestParameters =
record.getRequestParameters();
|
| Retrieve Intelligent Tiering event data | S3EventNotification.IntelligentTieringEventDataEntity tieringEventData =
record.getIntelligentTieringEventData();
| IntelligentTieringEventData intelligentTieringEventData =
record.getIntelligentTieringEventData();
|
| Retrieve lifecyle event data | S3EventNotification.LifecycleEventDataEntity lifecycleEventData =
record.getLifecycleEventData();
| LifecycleEventData lifecycleEventData =
record.getLifecycleEventData();
|
| Retrieve event name as enum | S3Event eventNameAsEnum = record.getEventNameAsEnum();
| //getEventNameAsEnum does not exist; use 'getEventName()'
String eventName = record.getEventName();
|
| Retrieve replication event data | S3EventNotification.ReplicationEventDataEntity replicationEntity =
record.getReplicationEventDataEntity();
| ReplicationEventData replicationEventData =
record.getReplicationEventData();
|
| Retrieve S3 bucket and object information | S3EventNotification.S3Entity s3 = record.getS3();
| S3 s3 = record.getS3();
|
| Retrieve user identity information | S3EventNotification.UserIdentityEntity userIdentity =
record.getUserIdentity();
| UserIdentity userIdentity =
record.getUserIdentity();
|
| Retrieve response elements | S3EventNotification.ResponseElementsEntity responseElements =
record.getResponseElements();
| ResponseElements responseElements =
record.getResponseElements();
|
## Migrate the `aws-lambda-java-events` library version
If you use [aws-lambda-java-events](https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-events) to work with S3 notification events within a Lambda function, we recommend that you upgrade to the latest 3.x.x version. Recent versions eliminate all dependencies on AWS SDK for Java 1.x from the S3 event notification API.
For more information about the differences in handling S3 event notifications between the `aws-lambda-java-events` library and the SDK for Java 2.x, see [Process S3 Events in Lambda with Java Libraries: AWS SDK for Java 2.x and `aws-lambda-java-events`](examples-s3-event-notifications.md#s3-event-notif-processing-options).
# Profile file changes
The AWS SDK for Java 2.x parses the profile definitions in `~/.aws/config` and `~/.aws/credentials` to more closely emulate the way the AWS CLI parses the files.
The SDK for Java 2.x:
+ Resolves a `~/` or `~` followed by the file system's default path separator at the start of the path by checking, in order, `$HOME`, `$USERPROFILE` (Windows only), `$HOMEDRIVE`, `$HOMEPATH` (Windows only), and then the `user.home` system property.
+ Looks for the `AWS_SHARED_CREDENTIALS_FILE` environment variable instead of `AWS_CREDENTIAL_PROFILES_FILE`.
+ Silently drops profile definitions in configuration files without the word `profile` at the beginning of the profile name.
+ Silently drops profile definitions that do not consist of alphanumeric, underscore or dash characters (after the leading `profile` word has been removed for configuration files).
+ Merges settings of profile definitions duplicated within the same file.
+ Merges settings of profile definitions duplicated in both the configuration and credentials files.
+ Does NOT merge settings if both `[profile foo]` and `[foo]` are found in the same file.
+ Uses settings in `[profile foo]` if both `[profile foo]` and `[foo]` are found in the configuration file.
+ Uses the value of the last duplicated setting in the same file and profile.
+ Recognizes both `;` and `#` for defining a comment.
+ Recognizes `;` and `#` in profile definitions to define a comment, even if the characters are adjacent to the closing bracket.
+ Recognizes `;` and `#` to define a comment only in setting values only if they are preceded by whitespace.
+ Recognizes `;` and `#` and all following content in setting values if they are not preceded by whitespace.
+ Considers role-based credentials the highest-priority credentials. The 2.x SDK always uses role-based credentials if the user specifies the `role_arn` property.
+ Considers session-based credentials the second-highest-priority credentials. The 2.x SDK always uses session-based credentials if role-based credentials were not used and the user specifies the `aws_access_key_id` and `aws_session_token` properties.
+ Uses basic credentials if role-based and session-based credentials are not used and the user specified the `aws_access_key_id` property.
# Environment variables and system properties changes
| 1.x Environment Variable | 1.x System Property | 2.x Environment Variable | 2.x System Property |
| --- | --- | --- | --- |
| AWS\$1ACCESS\$1KEY\$1IDAWS\$1ACCESS\$1KEY | aws.accessKeyId | AWS\$1ACCESS\$1KEY\$1ID | aws.accessKeyId |
| AWS\$1SECRET\$1KEYAWS\$1SECRET\$1ACCESS\$1KEY | aws.secretKey | AWS\$1SECRET\$1ACCESS\$1KEY | aws.secretAccessKey |
| AWS\$1SESSION\$1TOKEN | aws.sessionToken | AWS\$1SESSION\$1TOKEN | aws.sessionToken |
| AWS\$1REGION | aws.region | AWS\$1REGION | aws.region |
| AWS\$1CONFIG\$1FILE | | AWS\$1CONFIG\$1FILE | aws.configFile |
| AWS\$1CREDENTIAL\$1PROFILES\$1FILE | | AWS\$1SHARED\$1CREDENTIALS\$1FILE | aws.sharedCredentialsFile |
| AWS\$1PROFILE | aws.profile | AWS\$1PROFILE | aws.profile |
| AWS\$1EC2\$1METADATA\$1DISABLED | com.amazonaws.sdk.disableEc2Metadata | AWS\$1EC2\$1METADATA\$1DISABLED | aws.disableEc2Metadata |
| | com.amazonaws.sdk.ec2MetadataServiceEndpointOverride | AWS\$1EC2\$1METADATA\$1SERVICE\$1ENDPOINT | aws.ec2MetadataServiceEndpoint |
| AWS\$1CONTAINER\$1CREDENTIALS\$1RELATIVE\$1URI | | AWS\$1CONTAINER\$1CREDENTIALS\$1RELATIVE\$1URI | aws.containerCredentialsPath |
| AWS\$1CONTAINER\$1CREDENTIALS\$1FULL\$1URI | | AWS\$1CONTAINER\$1CREDENTIALS\$1FULL\$1URI | aws.containerCredentialsFullUri |
| AWS\$1CONTAINER\$1AUTHORIZATION\$1TOKEN | | AWS\$1CONTAINER\$1AUTHORIZATION\$1TOKEN | aws.containerAuthorizationToken |
| AWS\$1CBOR\$1DISABLED | com.amazonaws.sdk.disableCbor | CBOR\$1ENABLED | aws.cborEnabled |
| AWS\$1ION\$1BINARY\$1DISABLE | com.amazonaws.sdk.disableIonBinary | BINARY\$1ION\$1ENABLED | aws.binaryIonEnabled |
| AWS\$1EXECUTION\$1ENV | | AWS\$1EXECUTION\$1ENV | aws.executionEnvironment |
| | com.amazonaws.sdk.disableCertChecking | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) |
| | com.amazonaws.sdk.enableDefaultMetrics | [Not supported](https://github.com/aws/aws-sdk-java-v2/issues/23) | [Not supported](https://github.com/aws/aws-sdk-java-v2/issues/23) |
| | com.amazonaws.sdk.enableThrottledRetry | [Not supported](https://github.com/aws/aws-sdk-java-v2/issues/645) | [Not supported](https://github.com/aws/aws-sdk-java-v2/issues/645) |
| | com.amazonaws.regions.RegionUtils.fileOverride | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) |
| | com.amazonaws.regions.RegionUtils.disableRemote | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) |
| | com.amazonaws.services.s3.disableImplicitGlobalClients | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) |
| | com.amazonaws.sdk.enableInRegionOptimizedMode | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) | Not supported ([Request feature](https://github.com/aws/aws-sdk-java-v2/issues/new)) |
# Changes in Waiters from version 1 to version 2
This topic details the changes in the functionality of Waiters from version 1 (v1) to version 2 (v2).
The following tables demonstrate the difference for DynamoDB waiters specifically. Waiters for other services follow the same pattern.
## High-level changes
Waiters classes are in the same Maven artifact as the service.
| Change | v1 | v2 |
| --- | --- | --- |
| Maven dependencies |
com.amazonaws
aws-java-sdk-bom
1.12.6801
pom
import
com.amazonaws
dynamodb
|
software.amazon.awssdk
bom
2.27.102
pom
import
software.amazon.awssdk
dynamodb
|
| Package name | com.amazonaws.services.dynamodbv2.waiters | software.amazon.awssdk.services.dynamodb.waiters |
| Class names | `[AmazonDynamoDBWaiters](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/waiters/AmazonDynamoDBWaiters.html)` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-waiters.html) |
1 [Latest version](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). 2 [Latest version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
## API changes
| Change | v1 | v2 |
| --- | --- | --- |
| Create a waiter | AmazonDynamoDB client = AmazonDynamoDBClientBuilder
.standard().build();
AmazonDynamoDBWaiters waiter = client.waiters();
| Synchronous:DynamoDbClient client = DynamoDbClient.create();
DynamoDbWaiter waiter = client.waiter();
Asynchronous:DynamoDbAsyncClient asyncClient =
DynamoDbAsyncClient.create();
DynamoDbAsyncWaiter waiter = asyncClient.waiter();
|
| Wait until a table exists | Synchronous:waiter.tableExists()
.run(new WaiterParameters<>(
new DescribeTableRequest(tableName)));
Asynchronous:waiter.tableExists()
.runAsync(new WaiterParameters()
.withRequest(new DescribeTableRequest(tableName)),
new WaiterHandler() {
@Override
public void onWaitSuccess(
AmazonWebServiceRequest amazonWebServiceRequest) {
System.out.println("Table creation succeeded");
}
@Override
public void onWaitFailure(Exception e) {
e.printStackTrace();
}
}).get();
| Synchronous: WaiterResponse waiterResponse =
waiter.waitUntilTableExists(
r -> r.tableName("myTable"));
waiterResponse.matched().response()
.ifPresent(System.out::println);
Asynchronous: waiter.waitUntilTableExists(r -> r.tableName(tableName))
.whenComplete((r, t) -> {
if (t != null) {
t.printStackTrace();
} else {
System.out.println(
"Table creation succeeded");
}
}).join();
|
## Configuration changes
| Change | v1 | v2 |
| --- | --- | --- |
| Polling Strategy (max attempts and fixed delay) | MaxAttemptsRetryStrategy maxAttemptsRetryStrategy =
new MaxAttemptsRetryStrategy(10);
FixedDelayStrategy fixedDelayStrategy =
new FixedDelayStrategy(3);
PollingStrategy pollingStrategy =
new PollingStrategy(maxAttemptsRetryStrategy,
fixedDelayStrategy);
waiter.tableExists().run(
new WaiterParameters<>(
new DescribeTableRequest(tableName)),
pollingStrategy);
|
FixedDelayBackoffStrategy fixedDelayBackoffStrategy =
FixedDelayBackoffStrategy
.create(Duration.ofSeconds(3));
waiter.waitUntilTableExists(r -> r.tableName(tableName),
c -> c.maxAttempts(10)
.backoffStrategy(fixedDelayBackoffStrategy));
|
# Changes in the EC2 metadata utility from version 1 to version 2
This topic details the changes in the SDK for Java Amazon Elastic Compute Cloud (EC2) metadata utility from version 1 (v1) to version 2 (v2).
## High-level changes
****
| Change | v1 | v2 |
| --- | --- | --- |
| Maven dependencies |
com.amazonaws
aws-java-sdk-bom
1.12.5871
pom
import
com.amazonaws
aws-java-sdk-core
|
software.amazon.awssdk
bom
2.27.212
pom
import
software.amazon.awssdk
imds
software.amazon.awssdk
apache-client3
|
| Package name | com.amazonaws.util | software.amazon.awssdk.imds |
| Instantiation approach | Use static utility methods; no instantiation: String localHostName =
EC2MetadataUtils.getLocalHostName();
| Use a static factory method: Ec2MetadataClient client = Ec2MetadataClient.create();
Or use a builder approach: Ec2MetadataClient client = Ec2MetadataClient.builder()
.endpointMode(EndpointMode.IPV6)
.build();
|
| Types of clients | Synchronous only utility methods: EC2MetadataUtils | Synchronous: `Ec2MetadataClient` Asynchronous: `Ec2MetadataAsyncClient` |
1 [Latest version](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). 2 [Latest version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
3Notice the declaration of the `apache-client` module for v2. V2 of the EC2 metadata utility requires an implementation of the `SdkHttpClient` interface for the synchronous metadata client, or the `SdkAsyncHttpClient` interface for the asynchronous metadata client. The [Configure HTTP clients in the AWS SDK for Java 2.x](http-configuration.md) section shows the list of HTTP clients that you can use.
### Requesting metadata
In v1, you use static methods that accept no parameters to request metadata for an EC2 resource. In contrast, you need to specify the path to the EC2 resource as a parameter in v2. The following table shows the different approaches.
****
| v1 | v2 |
| --- | --- |
| String userMetaData = EC2MetadataUtils.getUserData();
| Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response =
client.get("/latest/user-data");
String userMetaData =
response.asString();
|
Refer to the [instance metadata categories](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instancedata-data-categories.html) to find the path you need to supply to request a piece of metadata.
**Note**
When you use an instance metadata client in v2, you should aim to use the same client for all request to retrieve metadata.
## Behavior changes
### JSON data
On EC2, the locally running Instance Metadata Service (IMDS) returns some metadata as JSON formatted strings. One such example is the dynamic metadata of an [instance identity document](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-identity-documents.html).
The v1 API contains separate methods for each piece of instance identity metadata, whereas the v2 API directly returns the JSON string. To work with the JSON string, you can use the [Document API ](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) to parse the response and navigate the JSON structure.
The following table compares how you retrieve metadata of an instance identity document in v1 and v2.
****
| Use case | v1 | v2 |
| --- | --- | --- |
| Retrieve the Region | InstanceInfo instanceInfo =
EC2MetadataUtils.getInstanceInfo();
String region = instanceInfo.getRegion();
| Ec2MetadataResponse response =
client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String region = instanceInfo.asMap().get("region").asString();
|
| Retrieve the instance id | InstanceInfo instanceInfo =
EC2MetadataUtils.getInstanceInfo();
String instanceId = instanceInfo.instanceId;
| Ec2MetadataResponse response =
client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceId = instanceInfo.asMap().get("instanceId").asString();
|
| Retrieve the instance type | InstanceInfo instanceInfo =
EC2MetadataUtils.getInstanceInfo();
String instanceType = instanceInfo.instanceType();
| Ec2MetadataResponse response =
client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceType = instanceInfo.asMap().get("instanceType").asString();
|
### Endpoint resolution differences
The following table shows the locations that the SDK checks to resolve the endpoint to IMDS. The locations are listed in descending priority.
****
| v1 | v2 |
| --- | --- |
| System property: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride | Client builder configuration method: endpoint(...) |
| Environment variable: AWS\$1EC2\$1METADATA\$1SERVICE\$1ENDPOINT | System property: aws.ec2MetadataServiceEndpoint |
| Default Value: http://169.254.169.254 | Config file: \$1.aws/config with the ec2\$1metadata\$1service\$1endpoint setting |
| | Value associated with resolved endpoint-mode |
| | Default value: http://169.254.169.254 |
### Endpoint resolution in v2
When you explicitly set an endpoint by using the builder, that endpoint value takes priority over all other settings. When the following code executes, the `aws.ec2MetadataServiceEndpoint` system property and config file `ec2_metadata_service_endpoint` setting are ignored if they exist.
```
Ec2MetadataClient client = Ec2MetadataClient
.builder()
.endpoint(URI.create("endpoint.to.use"))
.build();
```
#### Endpoint-mode
With v2, you can specify an endpoint-mode to configure the metadata client to use the default endpoint values for IPv4 or IPv6. Endpoint-mode is not available for v1. The default value used for IPv4 is `http://169.254.169.254` and `http://[fd00:ec2::254]` for IPv6.
The following table shows the different ways that you can set the endpoint mode in order of descending priority.
****
| | | Possible values |
| --- | --- | --- |
| Client builder configuration method: endpointMode(...) | Ec2MetadataClient client = Ec2MetadataClient
.builder()
.endpointMode(EndpointMode.IPV4)
.build();
| EndpointMode.IPV4, EndpointMode.IPV6 |
| System property | aws.ec2MetadataServiceEndpointMode | IPv4, IPv6 (case does not matter) |
| Config file: \$1.aws/config | ec2\$1metadata\$1service\$1endpoint setting | IPv4, IPv6 (case does not matter) |
| Not specified in the previous ways | IPv4 is used | |
#### How the SDK resolves `endpoint` or `endpoint-mode` in v2
1. The SDK uses the value that you set in code on the client builder and ignores any external settings. Because the SDK throws an exception if both `endpoint` and `endpointMode` are called on the client builder, the SDK uses the endpoint value from whichever method you use.
1. If you do not set a value in code, the SDK looks to external configuration—first for system properties and then for a setting in the config file.
1. The SDK first checks for an endpoint value. If a value is found, it is used.
1. If the SDK still hasn't found a value, the SDK looks for endpoint mode settings.
1. Finally, if the SDK finds no external settings and you have not configured the metadata client in code, the SDK uses the IPv4 value of `http://169.254.169.254`.
### IMDSv2
Amazon EC2 defines two approaches to access instance metadata:
+ Instance Metadata Service Version 1 (IMDSv1) – Request/response approach
+ Instance Metadata Service Version 2 (IMDSv2) – Session-oriented approach
The following table compares how the Java SDKs work with IMDS.
****
| v1 | v2 |
| --- | --- |
| IMDSv2 is used by default | Always uses IMDSv2 |
| Attempts to fetch a session token for each request and falls back to IMDSv1 if it fails to fetch a session token | Keeps a session token in an internal cache that is reused for multiple requests |
The SDK for Java 2.x supports only IMDSv2 and does not fall back to IMDSv1.
## Configuration differences
The following table lists the differing configuration options.
****
| Configuration | v1 | v2 |
| --- | --- | --- |
| Retries | Configuration not available | Configurable through builder method retryPolicy(...) |
| HTTP | Connection timeout configurable through the AWS\$1METADATA\$1SERVICE\$1TIMEOUT environment variable. The default is 1 second. | Configuration available by passing an HTTP client to the builder method httpClient(...). The default connection timeout for HTTP clients is 2 seconds. |
### Example v2 HTTP configuration
The following example shows how you can configure the metadata client. This example configures the connection timeout and uses the Apache HTTP client.
```
SdkHttpClient httpClient = ApacheHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(1))
.build();
Ec2MetadataClient imdsClient = Ec2MetadataClient.builder()
.httpClient(httpClient)
.build();
```
# Changes in Amazon CloudFront presigning from version 1 to version 2
This topic details the changes in the Amazon CloudFront from version 1 (v1) to version 2 (v2).
## High-level changes
****
| Change | v1 | v2 |
| --- | --- | --- |
| Maven dependencies |
com.amazonaws
aws-java-sdk-bom
1.12.5871
pom
import
com.amazonaws
cloudfront
|
software.amazon.awssdk
bom
2.27.212
pom
import
software.amazon.awssdk
cloudfront
|
| Package name | com.amazonaws.services.cloudfront | software.amazon.awssdk.services.cloudfront |
| Class names | [CloudFrontUrlSigner](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/cloudfront/CloudFrontUrlSigner.html) [CloudFrontCookieSigner](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/cloudfront/CloudFrontCookieSigner.html) | [CloudFrontUtilities](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudfront/CloudFrontUtilities.html) [SignedUrl](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudfront/url/SignedUrl.html) [CannedSignerRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudfront/model/CannedSignerRequest.html) [CustomSignerRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudfront/model/CustomSignerRequest.html) |
1 [Latest version](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). 2 [Latest version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
## API changes
| Behavior | v1 | v2 |
| --- | --- | --- |
| Build a canned request | Arguments are passed directly to the API. | CannedSignerRequest cannedRequest =
CannedSignerRequest.builder()
.resourceUrl(resourceUrl)
.privateKey(privateKey)
.keyPairId(keyPairId)
.expirationDate(expirationDate)
.build();
|
| Build a custom request | Arguments are passed directly to the API. | CustomSignerRequest customRequest =
CustomSignerRequest.builder()
.resourceUrl(resourceUrl)
.resourceUrlPattern(resourceUrlPattern)
.privateKey(keyFile)
.keyPairId(keyPairId)
.expirationDate(expirationDate)
.activeDate(activeDate)
.ipRange(ipRange)
.build();
|
| Generate a signed URL (canned) | String signedUrl =
CloudFrontUrlSigner.getSignedURLWithCannedPolicy(
resourceUrl, keyPairId, privateKey, expirationDate);
| CloudFrontUtilities cloudFrontUtilities =
CloudFrontUtilities.create();
SignedUrl signedUrl =
cloudFrontUtilities.getSignedUrlWithCannedPolicy(cannedRequest);
String url = signedUrl.url();
|
| Generate a signed cookie (custom) | CookiesForCustomPolicy cookies =
CloudFrontCookieSigner.getCookiesForCustomPolicy(
resourceUrl, privateKey, keyPairId, expirationDate,
activeDate, ipRange);
| CloudFrontUtilities cloudFrontUtilities =
CloudFrontUtilities.create();
CookiesForCustomPolicy cookies =
cloudFrontUtilities.getCookiesForCustomPolicy(customRequest);
|
### Refactored cookie headers in v2
In Java v1, the Java SDK delivers cookie headers as a `Map.Entry`.
```
Map.Entry signatureMap = cookies.getSignature();
String signatureKey = signatureMap.getKey(); // "CloudFront-Signature"
String signatureValue = signatureMap.getValue(); // "[SIGNATURE_VALUE]"
```
The Java v2 SDK delivers the entire header as a single `String`.
```
String signatureHeaderValue = cookies.signatureHeaderValue(); // "CloudFront-Signature=[SIGNATURE_VALUE]"
```
# Changes in the IAM Policy Builder API from version 1 to version 2
This topic details the changes in the IAM Policy Builder API from version 1 (v1) to version 2 (v2).
## High-level changes
****
| Change | v1 | v2 |
| --- | --- | --- |
| Maven dependencies |
com.amazonaws
aws-java-sdk-bom
1.12.5871
pom
import
com.amazonaws
aws-java-sdk-core
|
software.amazon.awssdk
bom
2.27.212
pom
import
software.amazon.awssdk
iam-policy-builder
|
| Package name | com.amazonaws.auth.policy | software.amazon.awssdk.policybuilder.iam |
| Class names | [Policy](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Policy.html) [Statement](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Statement.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-iam-policy-builder.html) | [IamPolicy](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamPolicy.html) [IamStatement](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamStatement.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-iam-policy-builder.html) |
1 [Latest version](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). 2 [Latest version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
## API changes
****
| Setting | v1 | v2 |
| --- | --- | --- |
| Instantiate a policy | Policy policy = new Policy();
| IamPolicy.Builder policyBuilder = IamPolicy.builder();
...
IamPolicy policy = policyBuilder.build();
|
| Set id | policy.withtId(...);
policy.setId(...);
| policyBuilder.id(...);
|
| Set version | N/A - uses default version of 2012-10-17 | policyBuilder.version(...);
|
| Create statement | Statement statement =
new Statement(Effect.Allow)
.withActions(...)
.withConditions(...)
.withId(...)
.withPrincipals(...)
.withResources(...);
| IamStatement statement =
IamStatement.builder()
.effect(IamEffect.ALLOW)
.actions(...)
.notActions(...)
.conditions(...)
.sid(...)
.principals(...)
.notPrincipals(...)
.resources(...)
.notResources(...)
.build()
|
| Set statement | policy.withStatements(statement);
policy.setStatements(statement);
| policyBuilder.addStatement(statement);
|
## Differences in building a statement
### Actions
#### v1
The v1 SDK has [`enum` types](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Action.html) for service actions that represent `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_action.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_action.html)` elements in a policy statement. The following `enum` types are some examples.
+ `[IdentityManagementActions](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/actions/IdentityManagementActions.html)`
+ `[DynamoDBv2Actions](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/actions/DynamoDBv2Actions.html)`
+ `[SQSActions](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/actions/SQSActions.html)`
The following example shows the `SendMessage` constant for `SQSActions`.
```
Action action = SQSActions.SendMessage;
```
You cannot specify a `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html)` element to a statement in v1.
#### v2
In v2, the [IamAction](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamAction.html) interface represents all actions. To specify a [service-specific action](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_action.html) element, pass a string to the `create` method as shown in the following code.
```
IamAction action = IamAction.create("sqs:SendMessage");
```
You can specify a `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html)` for a statement with v2 as shown in the following code.
```
IamAction action = IamAction.create("sqs:SendMessage");
IamStatement.builder().addNotAction(action);
```
### Conditions
#### v1
To represent statement conditions, the v1 SDK uses subclasses of [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Condition.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Condition.html).
+ [ArnCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/ArnCondition.html)
+ [BooleanCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/BooleanCondition.html)
+ [DateCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/DateCondition.html)
+ [IpAddressCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/IpAddressCondition.html)
+ [NumericCondition](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/NumericCondition.html)
+ [ StringCondition ](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/conditions/StringCondition.html)
Each `Condition` subclass defines a comparison `enum` type to help define the condition. For example, the following shows a *not like*[ string comparison](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String) for a condition.
```
Condition condition = new StringCondition(StringComparisonType.StringNotLike, "key", "value");
```
#### v2
In v2, you build a condition for a policy statement by using `[IamCondition](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamCondition.html)` and provide an `[IamConditionOperator](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamConditionOperator.html)`, which contains `enums` for all types.
```
IamCondition condition = IamCondition.create(IamConditionOperator.STRING_NOT_LIKE, "key", "value");
```
### Resources
#### v1
A policy statement's `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html)` element is represented by the SDK's `[Resource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Resource.html)` class. You supply the ARN as a string in the constructor. The following subclasses provide convenience constructors.
+ [S3BucketResource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/resources/S3BucketResource.html)
+ [S3ObjectResource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/resources/S3ObjectResource.html)
+ [SQSQueueResource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/resources/SQSQueueResource.html)
In v1, you can specify a `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html)` element for a `[Resource](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Resource.html)` by calling the `withIsNotType` method as shown in the following statement.
```
Resource resource = new Resource("arn:aws:s3:::amzn-s3-demo-bucket").withIsNotType(true);
```
#### v2
In v2, you create a `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html)` element by passing an ARN to the `IamResource.create` method.
```
IamResource resource = IamResource.create("arn:aws:s3:::amzn-s3-demo-bucket");
```
An `[IamResource](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamResource.html)` can be set as *[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notresource.html)* element as shown in the following snippet.
```
IamResource resource = IamResource.create("arn:aws:s3:::amzn-s3-demo-bucket");
IamStatement.builder().addNotResource(resource);
```
`IamResource.ALL` represents all resources.
### Principals
#### v1
The v1 SDK offers the following `[Principal](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/policy/Principal.html)` classes to represent types of principals that include all members:
+ `AllUsers`
+ `AllServices`
+ `AllWebProviders`
+ `All`
You cannot add a `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html)` element to a statement.
#### v2
In v2, `IamPrincipal.ALL` represents all principals:
To represent all members in other types of principals, use the `[IamPrincipalType](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/policybuilder/iam/IamPrincipalType.html)` classes when you create a `IamPrincipal`.
+ `IamPrincipal.create(IamPrincipalType.AWS,"*")` for all users.
+ `IamPrincipal.create(IamPrincipalType.SERVICE,"*")` for all services.
+ `IamPrincipal.create(IamPrincipalType.FEDERATED,"*")` for all web providers.
+ `IamPrincipal.create(IamPrincipalType.CANONICAL_USER,"*")` for all canonical users.
You can use the `addNotPrincipal` method to represent a `[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html)` element when you create a policy statement as shown in the following statement.
```
IamPrincipal principal = IamPrincipal.create(IamPrincipalType.AWS, "arn:aws:iam::444455556666:root");
IamStatement.builder().addNotPrincipal(principal);
```
# Changes in working with DynamoDB from version 1 to version 2 of the AWS SDK for Java
**Topics**
+ [DynamoDB mapping API differences between version 1 and version 2 of the AWS SDK for Java](ddb-mapping.md)
+ [Document API differences between version 1 and version 2 of the AWS SDK for Java](dynamodb-mapping-document-api.md)
+ [Encryption library migration](ddb-encryption-lib-migrate.md)
# DynamoDB mapping API differences between version 1 and version 2 of the AWS SDK for Java
The DynamoDB mapping APIs changed significantly between version 1 and version 2 of the AWS SDK for Java. In version 1, you use the `DynamoDBMapper` to work with Java POJOs. In version 2, you use the `DynamoDbEnhancedClient` with updated method names, enhanced schema definition options, and improved type safety.
Key differences include:
+ New method names (such as `getItem` instead of `load`)
+ Explicit table schema creation
+ Built-in support for both synchronous and asynchronous operations
+ Changes in how empty strings and configuration are handled
This section covers the mapping API changes, annotation differences, configuration updates, and migration guidance to help you transition from the v1 `DynamoDBMapper` to the v2 `DynamoDbEnhancedClient`.
**Contents**
+ [High-level changes in mapping libraries from version 1 to version 2 of the SDK for Java](dynamodb-mapping-high-level.md)
+ [Import dependency differences](dynamodb-mapping-high-level.md#dynamodb-mapping-deps)
+ [Changes in the DynamoDB mapping APIs between version 1 and version 2 of the SDK for Java](dynamodb-mapping-api-changes.md)
+ [Create a client](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-client)
+ [Establish mapping to DynamoDB table/index](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-mapping)
+ [Table operations](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-tobleops)
+ [Map classes and properties](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas)
+ [Bean annotations](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas-annos)
+ [V2 additional annotations](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas-annos-v2-addnl)
+ [Configuration](dynamodb-mapping-api-changes.md#dynamodb-mapping-configuration)
+ [Per-operation configuration](dynamodb-mapping-api-changes.md#dynamodb-mapping-configuration-per-op)
+ [Conditionals](dynamodb-mapping-api-changes.md#dynamodb-mapping-conditionals)
+ [Type conversion](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv)
+ [Default converters](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-defaults)
+ [Set a custom converter for an attribute](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-anno)
+ [Add a type converter factory or provider](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-factory)
+ [String handling differences between version 1 and version 2 of the SDK for Java](dynamodb-migration-string-handling.md)
+ [Optimistic locking differences between version 1 and version 2 of the SDK for Java](dynamodb-migrate-optimstic-locking.md)
+ [Fluent setters differences between version 1 and version 2 of the SDK for Java](dynamodb-migrate-fluent-setters.md)
# High-level changes in mapping libraries from version 1 to version 2 of the SDK for Java
The names of the mapping client in each library differ in V1 and V2:
+ V1 - DynamoDBMapper
+ V2 - DynamoDB Enhanced Client
You interact with the two libraries in much the same way: you instantiate a mapper/client and then supply a Java POJO to APIs that read and write these items to DynamoDB tables. Both libraries also offer annotations for the class of the POJO to direct how the client handles the POJO.
Notable differences when you move to V2 include:
+ V2 and V1 use different method names for the low-level DynamoDB operations. For example:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-mapping-high-level.html)
+ V2 offers multiple ways to define table schemas and map POJOs to tables. You can choose from the use of annotations or a schema generated from code using a builder. V2 also offers mutable and immutable versions of schemas.
+ With V2, you specifically create the table schema as one of the first steps, whereas in V1, the table schema is inferred from the annotated class as needed.
+ V2 includes the [Document API client ](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html) in the enhanced client API, whereas V1 uses a [separate API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html).
+ All APIs are available in synchronous and asynchronous versions in V2.
See the [DynamoDB mapping section](dynamodb-enhanced-client.md) in this guide for more detailed information on the V2 enhanced client.
## Import dependency differences
| V1 | V2 |
| --- | --- |
|
com.amazonaws
aws-java-sdk-bom
1.X.X
pom
import
com.amazonaws
aws-java-sdk-dynamodb
|
software.amazon.awssdk
bom
2.X.X*
pom
import
software.amazon.awssdk
dynamodb-enhanced
|
\$1 [Latest version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
In V1, a single dependency includes both the low-level DynamoDB API and the mapping/document API, whereas in V2, you use the `dynamodb-enhanced` artifact dependency to access the mapping/document API. The `dynamodb-enhanced` module contains a transitive dependency on the low-level `dynamodb` module.
# Changes in the DynamoDB mapping APIs between version 1 and version 2 of the SDK for Java
## Create a client
****
| Use case | V1 | V2 |
| --- | --- | --- |
| Normal instantiation | AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard()
.withCredentials(credentialsProvider)
.withRegion(Regions.US_EAST_1)
.build();
DynamoDBMapper mapper = new DynamoDBMapper(standardClient);
| DynamoDbClient standardClient = DynamoDbClient.builder()
.credentialsProvider(ProfileCredentialsProvider.create())
.region(Region.US_EAST_1)
.build();
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.build();
|
| Minimal instantiation | AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard();
DynamoDBMapper mapper = new DynamoDBMapper(standardClient);
| DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create();
|
| With attribute transformer\$1 | DynamoDBMapper mapper = new DynamoDBMapper(standardClient,
attributeTransformerInstance);
| DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.extensions(extensionAInstance, extensionBInstance)
.build();
|
\$1Extensions in V2 correspond roughly to attribute transformers in V1. The [Use extensions to customize DynamoDB Enhanced Client operations](ddb-en-client-extensions.md) section contains more information on extensions in V2.
## Establish mapping to DynamoDB table/index
In V1, you specify a DynamoDB table name through a bean annotation. In V2, a factory method, `table()`, produces an instance of `DynamoDbTable` that represents the remote DynamoDB table. The first parameter of the `table()` method is the DynamoDB table name.
****
| Use case | V1 | V2 |
| --- | --- | --- |
| Map the Java POJO class to the DynamoDB table | @DynamoDBTable(tableName ="Customer")
public class Customer {
...
}
| DynamoDbTable customerTable = enhancedClient.table("Customer",
TableSchema.fromBean(Customer.class));
|
| Map to a DynamoDB secondary index | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) The section in the DynamoDB Developer Guide that discusses[ the V1 `query` method](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html#DynamoDBMapper.Methods.query) shows a complete example. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) The [Use secondary indices](ddb-en-client-use-secindex.md) section in this guide provides more information. |
## Table operations
This section describes operation APIs that differ between V1 and V2 for most standard use cases.
In V2, all operations that involve a single table are called on the `DynamoDbTable` instance, not on the enhanced client. The enhanced client contains methods that can target multiple tables.
In the table named *Table operations* below, a POJO instance is referred to as `item` or as a specific type such as `customer1`. For the V2 examples the instances named, `table` is the result of previously calling `enhancedClient.table()` that returns a reference to the `DynamoDbTable` instance.
Note that most V2 operations can be called with a fluent consumer pattern even when not shown. For example,
```
Customer customer = table.getItem(r → r.key(key));
or
Customer customer = table.getItem(r → r.key(k -> k.partitionValue("id").sortValue("email")))
```
For V1 operations, *Table operations* (below) contains some of the commonly used forms and not all overloaded forms. For example, the `load()` method has the following overloads:
```
mapper.load(Customer.class, hashKey)
mapper.load(Customer.class, hashKey, rangeKey)
mapper.load(Customer.class, hashKey, config)
mapper.load(Customer.class, hashKey, rangeKey, config)
mapper.load(item)
mapper.load(item, config)
```
*Table operations* (below) shows the commonly used forms:
```
mapper.load(item)
mapper.load(item, config)
```
**Table operations**
| Use case | V1 | V2 |
| --- | --- | --- |
| Write a Java POJO to a DynamoDB table **DynamoDB operation:** `PutItem`, `UpdateItem` | mapper.save(item)
mapper.save(item, config)
mapper.save(item, saveExpression, config)
In V1, `DynamoDBMapperConfig.SaveBehavior` and annotations determines which low-level DynamoDB method will be called. In general, `UpdateItem` is called except when using `SaveBehavior.CLOBBER` and `SaveBehavior.PUT`. Auto-generated keys are a special use case, and occasionally both `PutItem` and `UpdateItem` are used. | table.putItem(putItemRequest)
table.putItem(item)
table.putItemWithResponse(item) //Returns metadata.
updateItem(updateItemRequest)
table.updateItem(item)
table.updateItemWithResponse(item) //Returns metadata.
|
| Read an item from a DynamoDB table to a Java POJO **DynamoDB operation:** `GetItem` | mapper.load(item)
mapper.load(item, config)
| table.getItem(getItemRequest)
table.getItem(item)
table.getItem(key)
table.getItemWithResponse(key) //Returns POJO with metadata.
|
| Delete an item from a DynamoDB table **DynamoDB operation:** `DeleteItem` | mapper.delete(item, deleteExpression, config)
| table.deleteItem(deleteItemRequest)
table.deleteItem(item)
table.deleteItem(key)
|
| Query a DynamoDB table or secondary index and return a paginated list **DynamoDB operation:** `Query` | mapper.query(Customer.class, queryExpression)
mapper.query(Customer.class, queryExpression,
mapperConfig)
| table.query(queryRequest)
table.query(queryConditional)
Use the returned `PageIterable.stream()` (lazy loading) for sync responses and `PagePublisher.subscribe()` for async responses |
| Query a DynamoDB table or secondary index and return a list **DynamoDB operation:** `Query` | mapper.queryPage(Customer.class, queryExpression)
mapper.queryPage(Customer.class, queryExpression,
mapperConfig)
| table.query(queryRequest)
table.query(queryConditional)
Use the returned `PageIterable.items()` (lazy loading) for sync responses and `PagePublisher.items.subscribe()` for async responses |
| Scan a DynamoDB table or secondary index and return a paginated list **DynamoDB operation:** `Scan` | mapper.scan(Customer.class, scanExpression)
mapper.scan(Customer.class, scanExpression,
mapperConfig)
| table.scan()
table.scan(scanRequest)
Use the returned `PageIterable.stream()` (lazy loading) for sync responses and `PagePublisher.subscribe()` for async responses |
| Scan a DynamoDB table or secondary index and return a list **DynamoDB operation:** `Scan` | mapper.scanPage(Customer.class, scanExpression)
mapper.scanPage(Customer.class, scanExpression,
mapperConfig)
| table.scan()
table.scan(scanRequest)
Use the returned `PageIterable.items()` (lazy loading) for sync responses and `PagePublisher.items.subscribe()` for async responses |
| Read multiple items from multiple tables in a batch **DynamoDB operation:** `BatchGetItem` | mapper.batchLoad(Arrays.asList(customer1,
customer2,
book1))
mapper.batchLoad(itemsToGet)
// itemsToGet: Map, List>
| enhancedClient.batchGetItem(batchGetItemRequest)
enhancedClient.batchGetItem(r -> r.readBatches(
ReadBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addGetItem(i -> i.key(k -> k.partitionValue(0)))
.build(),
ReadBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addGetItem(i -> i.key(k -> k.partitionValue(0)))
.build()))
// Iterate over pages with lazy loading or over all items
from the same table.
|
| Write multiple items to multiple tables in a batch **DynamoDB operation:** `BatchWriteItem` | mapper.batchSave(Arrays.asList(customer1,
customer2,
book1))
| enhancedClient.batchWriteItem(batchWriteItemRequest)
enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addPutItem(item1)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addPutItem(item2)
.build()))
|
| Delete multiple items from multiple tables in a batch **DynamoDB operation:** `BatchWriteItem` | mapper.batchDelete(Arrays.asList(customer1,
customer2,
book1))
| enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addDeleteItem(item1key)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addDeleteItem(item2key)
.build()))
|
| Write/delete multiple items in a batch **DynamoDB operation:** `BatchWriteItem` | mapper.batchWrite(Arrays.asList(customer1, book1),
Arrays.asList(customer2))
| enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addPutItem(item1)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addDeleteItem(item2key)
.build()))
|
| Carry out a transactional write **DynamoDB operation:** `TransactWriteItems` | mapper.transactionWrite(transactionWriteRequest)
| enhancedClient.transactWriteItems(transasctWriteItemsRequest)
|
| Carry out a transactional read **DynamoDB operation:** `TransactGetItems` | mapper.transactionLoad(transactionLoadRequest)
| enhancedClient.transactGetItems(transactGetItemsRequest)
|
| Get a count of matching items of a query **DynamoDB operation:** `Query` with `Select.COUNT` | mapper.count(Customer.class, queryExpression)
| // Get the count from query results.
PageIterable pageIterable =
customerTable.query(QueryEnhancedRequest.builder()
.queryConditional(queryConditional)
.select(Select.COUNT)
.build());
Iterator> iterator = pageIterable.iterator();
Page page = iterator.next();
int count = page.count();
// For a more concise approach, you can chain the method calls:
int count = customerTable.query(QueryEnhancedRequest.builder()
.queryConditional(queryConditional)
.select(Select.COUNT)
.build())
.iterator().next().count();
|
| Get a count of matching items of a scan **DynamoDB operation:**`Scan` with `Select.COUNT` | mapper.count(Customer.class, scanExpression)
| // Get the count from scan results.
PageIterable pageIterable =
customerTable.scan(ScanEnhancedRequest.builder()
.filterExpression(filterExpression)
.select(Select.COUNT)
.build());
Iterator> iterator = pageIterable.iterator();
Page page = iterator.next();
int count = page.count();
// For a more concise approach, you can chain the method calls:
int count = customerTable.scan(ScanEnhancedRequest.builder()
.filterExpression(filterExpression)
.select(Select.COUNT)
.build())
.iterator().next().count();
|
| Create a table in DynamoDB corresponding to the POJO class **DynamoDB operation:** `CreateTable` | mapper.generateCreateTableRequest(Customer.class)
The previous statement generates a low-level create table request; users must call `createTable` on the DynamoDB client. | table.createTable(createTableRequest)
table.createTable(r -> r.provisionedThroughput(defaultThroughput())
.globalSecondaryIndices(
EnhancedGlobalSecondaryIndex.builder()
.indexName("gsi_1")
.projection(p -> p.projectionType(ProjectionType.ALL))
.provisionedThroughput(defaultThroughput())
.build()));
|
| Perform a parallel scan in DynamoDB **DynamoDB operation:** `Scan` with `Segment` and `TotalSegments` parameters | mapper.parallelScan(Customer.class,
scanExpression,
numTotalSegments)
| Users are required to handle the worker threads and call `scan` for each segment: table.scan(r -> r.segment(0).totalSegments(5))
|
| Integrate Amazon S3 with DynamoDB to store intelligent S3 links | mapper.createS3Link(bucket, key)
mapper.getS3ClientCache()
| Not supported because it couples Amazon S3 and DynamoDB. |
## Map classes and properties
In both V1 and V2, you map classes to tables using bean-style annotations. V2 also offers [other ways to define schemas](ddb-en-client-adv-features.md#ddb-en-client-adv-features-schm-overview) for specific use cases, such as working with immutable classes.
### Bean annotations
The following table shows the equivalent bean annotations for a specific use case that are used in V1 and V2. A `Customer` class scenario is used to illustrate parameters.
Annotations—as well as classes and enumerations—in V2 follow camel case convention and use 'DynamoDb', not 'DynamoDB'.
| Use case | V1 | V2 |
| --- | --- | --- |
| Map class to table | @DynamoDBTable (tableName ="CustomerTable")
| @DynamoDbBean
@DynamoDbBean(converterProviders = {...})
The table name is defined when calling the DynamoDbEnhancedClient\$1table() method. |
| Designate a class member as a table attribute | @DynamoDBAttribute(attributeName = "customerName")
| @DynamoDbAttribute("customerName") |
| Designate a class member is a hash/partition key | @DynamoDBHashKey
| @DynamoDbPartitionKey
|
| Designate a class member is a range/sort key | @DynamoDBRangeKey
| @DynamoDbSortKey
|
| Designate a class member is a secondary index hash/partition key | @DynamoDBIndexHashKey
| @DynamoDbSecondaryPartitionKey
|
| Designate a class member is a secondary index range/sort key | @DynamoDBIndexRangeKey
| @DynamoDbSecondarySortKey
|
| Ignore this class member when mapping to a table | @DynamoDBIgnore
| @DynamoDbIgnore
|
| Designate a class member as an auto-generated UUID key attribute | @DynamoDBAutoGeneratedKey
| @DynamoDbAutoGeneratedUuid
The extension that provides this is not loaded by default; you must add the extension to client builder. |
| Designate a class member as an auto-generated timestamp attribute | @DynamoDBAutoGeneratedTimestamp
| @DynamoDbAutoGeneratedTimestampAttribute
The extension that provides this is not loaded by default; you must add the extension to client builder. |
| Designate a class member as an auto-incremented version attribute | @DynamoDBVersionAttribute
| @DynamoDbVersionAttribute
The extension that provides this is auto-loaded. |
| Designate a class member as requiring a custom conversion | @DynamoDBTypeConverted
| @DynamoDbConvertedBy
|
| Designate a class member to be stored as a different attribute type | @DynamoDBTyped()
| Use an `AttributeConverter` implementation. V2 provides many built-in converters for common Java types. You can also implement your own custom `AttributeConverter` or `AttributeConverterProvider`. See [Control attribute conversion](ddb-en-client-adv-features-conversion.md) in this guide. |
| Designate a class that can be serialized to a DynamoDB document (JSON-style document) or sub-document | @DynamoDBDocument
| Use the Enhanced Document API. See the following resources:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
### V2 additional annotations
| Use case | V1 | V2 |
| --- | --- | --- |
| Designate a class member not to be stored as a NULL attribute if the Java value is null | N/A | @DynamoDbIgnoreNulls
|
| Designate a class member to be an empty object if all attributes are null | N/A | @DynamoDbPreserveEmptyObject
|
| Designate special update action for a class member | N/A | @DynamoDbUpdateBehavior
|
| Designate an immutable class | N/A | @DynamoDbImmutable
|
| Designate a class member as an auto-incremented counter attribute | N/A | @DynamoDbAtomicCounter
The extension that provides this functionality is auto-loaded. |
## Configuration
In V1, you generally control specific behaviors by using an instance of `DynamoDBMapperConfig`. You can supply the configuration object either when you create the mapper or when you make a request. In V2, configuration is specific to the request object for the operation.
| Use case | V1 | Default in V1 | V2 |
| --- | --- | --- | --- |
| | DynamoDBMapperConfig.builder()
| | |
| Batch load/write retry strategy | .withBatchLoadRetryStrategy(loadRetryStrategy)
.withBatchWriteRetryStrategy(writeRetryStrategy)
| retry failed items | Configure the retry strategy on the underlying DynamoDBClient. See [Configure retry behavior in the AWS SDK for Java 2.x](retry-strategy.md) in this guide. |
| Consistent reads | .withConsistentReads(CONSISTENT)
| EVENTUAL | By default, consistent reads is false for read operations. Override with .consistentRead(true) on the request object. |
| Conversion schema with sets of marshallers/unmarshallers | .withConversionSchema(conversionSchema)
Static implementations provide backwards compatibility with older versions. | V2\$1COMPATIBLE | Not applicable. This is a legacy feature that refers to how the earliest versions of DynamoDB (V1) stored data types, and this behavior will not be preserved in the enhanced client. An example of behavior in DynamoDB V1 is storing booleans as Number instead of as Boolean. |
| Table names | .withObjectTableNameResolver()
.withTableNameOverride()
.withTableNameResolver()
Static implementations provide backwards compatibility with older versions | use annotation or guess from class | The table name is defined when calling the `DynamoDbEnhancedClient#table()` method. |
| Pagination load strategy | .withPaginationLoadingStrategy(strategy)
Options are: LAZY\$1`LOADING`, `EAGER_LOADING`, or `ITERATION_ONLY` | LAZY\$1LOADING | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
| Request metric collection | .withRequestMetricCollector(collector)
| null | Use metricPublisher() in ClientOverrideConfiguration when building the standard DynamoDB client. |
| Save behavior | .withSaveBehavior(SaveBehavior.CLOBBER)
Options are `UPDATE`, `CLOBBER`, `PUT`, `APPEND_SET`, or `UPDATE_SKIP_NULL_ATTRIBUTES`. | UPDATE | In V2, you call `putItem()` or `updateItem()` explicitly. `CLOBBER or PUT`: Corresponding action in v 2 is calling `putItem()`. There is no specific `CLOBBER` configuration. `UPDATE`: Corresponds to `updateItem()` `UPDATE_SKIP_NULL_ATTRIBUTES`: Corresponds to `updateItem()`. Control update behavior with the request setting `ignoreNulls` and the annotation/tag `DynamoDbUpdateBehavior`. `APPEND_SET`: Not supported |
| Type converter factory | .withTypeConverterFactory(typeConverterFactory)
| standard type converters | Set on the bean by using @DynamoDbBean(converterProviders = {ConverterProvider.class,
DefaultAttributeConverterProvider.class}) |
### Per-operation configuration
In V1, some operations, such as `query()`, are highly configurable through an “expression” object submitted to the operation. For example:
```
DynamoDBQueryExpression emailBwQueryExpr = new DynamoDBQueryExpression()
.withRangeKeyCondition("Email",
new Condition()
.withComparisonOperator(ComparisonOperator.BEGINS_WITH)
.withAttributeValueList(
new AttributeValue().withS("my")));
mapper.query(Customer.class, emailBwQueryExpr);
```
In V2, instead of using a configuration object, you set parameters on the request object by using a builder. For example:
```
QueryEnhancedRequest emailBw = QueryEnhancedRequest.builder()
.queryConditional(QueryConditional
.sortBeginsWith(kb -> kb
.sortValue("my"))).build();
customerTable.query(emailBw);
```
## Conditionals
In V2, conditional and filtering expressions are expressed using an `Expression` object, which encapsulates the condition and the mapping of names and filters.
| Use case | Operations | V1 | V2 |
| --- | --- | --- | --- |
| Expected attribute conditions | save(), delete(), query(), scan() | new DynamoDBSaveExpression()
.withExpected(Collections.singletonMap(
"otherAttribute", new ExpectedAttributeValue(false)))
.withConditionalOperator(ConditionalOperator.AND);
| Deprecated; use ConditionExpression instead. |
| Condition expression | delete() | deleteExpression.setConditionExpression("zipcode = :zipcode")
deleteExpression.setExpressionAttributeValues(...)
| Expression conditionExpression =
Expression.builder()
.expression("#key = :value OR #key1 = :value1")
.putExpressionName("#key", "attribute")
.putExpressionName("#key1", "attribute3")
.putExpressionValue(":value", AttributeValues.stringValue("wrong"))
.putExpressionValue(":value1", AttributeValues.stringValue("three"))
.build();
DeleteItemEnhancedRequest request = DeleteItemEnhancedRequest.builder()
.conditionExpression(conditionExpression).build();
|
| Filter expression | query(), scan() | scanExpression
.withFilterExpression("#statename = :state")
.withExpressionAttributeValues(attributeValueMapBuilder.build())
.withExpressionAttributeNames(attributeNameMapBuilder.build())
| Map values = singletonMap(":key", stringValue("value"));
Expression filterExpression =
Expression.builder()
.expression("name = :key")
.expressionValues(values)
.build();
QueryEnhancedRequest request = QueryEnhancedRequest.builder()
.filterExpression(filterExpression).build();
|
| Condition expression for query | query() | queryExpression.withKeyConditionExpression()
| QueryConditional keyEqual = QueryConditional.keyEqualTo(b -> b
.partitionValue("movie01"));
QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder()
.queryConditional(keyEqual)
.build();
|
## Type conversion
### Default converters
In V2, the SDK provides a set of default converters for all common types. You can change type converters both at the overall provider level as well as for a single attribute. You can find a list of the available converters in the [AttributeConverter](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/AttributeConverter.html) API reference.
### Set a custom converter for an attribute
In V1, you can annotate a getter method with `@DynamoDBTypeConverted` to specify the class that converts between the Java attribute type and a DynamoDB attribute type. For instance, a `CurrencyFormatConverter` that converts between a Java `Currency` type and DynamoDB String can be applied as shown in the following snippet.
```
@DynamoDBTypeConverted(converter = CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }
```
The V2 equivalent of the previous snippet is shown below.
```
@DynamoDbConvertedBy(CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }
```
**Note**
In V1, you can apply the annotation to the attribute itself , a type or a user-defined annotation, V2 supports applying the annotation it only to the getter.
### Add a type converter factory or provider
In V1, you can provide your own set of type converters, or override the types you care about by adding a type converter factory to the configuration. The type converter factory extends `DynamoDBTypeConverterFactory`, and overrides are done by getting a reference to the default set and extending it. The following snippet demonstrates how to do this.
```
DynamoDBTypeConverterFactory typeConverterFactory =
DynamoDBTypeConverterFactory.standard().override()
.with(String.class, CustomBoolean.class, new DynamoDBTypeConverter() {
@Override
public String convert(CustomBoolean bool) {
return String.valueOf(bool.getValue());
}
@Override
public CustomBoolean unconvert(String string) {
return new CustomBoolean(Boolean.valueOf(string));
}}).build();
DynamoDBMapperConfig config =
DynamoDBMapperConfig.builder()
.withTypeConverterFactory(typeConverterFactory)
.build();
DynamoDBMapper mapperWithTypeConverterFactory = new DynamoDBMapper(dynamo, config);
```
V2 provides similar functionality through the `@DynamoDbBean` annotation. You can provide a single `AttributeConverterProvider` or a chain of ordered `AttributeConverterProvider`s. Note that if you supply your own chain of attribute converter providers, you will override the default converter provider and must include it in the chain to use its attribute converters.
```
@DynamoDbBean(converterProviders = {
ConverterProvider1.class,
ConverterProvider2.class,
DefaultAttributeConverterProvider.class})
public class Customer {
...
}
```
The section on [attribute conversion](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-example) in this guide contains a complete example for V2.
# String handling differences between version 1 and version 2 of the SDK for Java
V1 and V2 handle empty strings differently when sending data to DynamoDB:
+ **V1**: Converts empty strings to null values before sending to DynamoDB (resulting in no attribute)
+ **V2**: Sends empty strings as actual empty string values to DynamoDB
**Important**
After migrating to V2, if you don't want empty strings stored in DynamoDB, you must implement custom converters. Without custom converters, V2 stores empty strings as actual empty string attributes in your DynamoDB items, which differs from V1's behavior of omitting these attributes entirely.
**Example custom converter for V2 that converts an empty string attribute to null**
```
/**
* Custom converter that maintains V1 behavior by converting empty strings to null values
* when writing to DynamoDB, ensuring compatibility with existing data. No attribute will be saved to DynamoDB.
*/
public class NullifyEmptyStringConverter implements AttributeConverter {
@Override
public AttributeValue transformFrom(String value) {
if (value == null || value.isEmpty()) {
return AttributeValue.builder().nul(true).build();
}
return AttributeValue.builder().s(value).build();
}
@Override
public String transformTo(AttributeValue attributeValue) {
if (attributeValue.nul()) {
return null;
}
return attributeValue.s();
}
@Override
public EnhancedType type() {
return EnhancedType.of(String.class);
}
@Override
public AttributeValueType attributeValueType() {
return AttributeValueType.S;
}
}
// V2 usage:
@DynamoDbBean
public class Customer {
private String name;
@DynamoDbConvertedBy(NullifyEmptyStringConverter.class)
public String getName() {
return name;
}
}
```
# Optimistic locking differences between version 1 and version 2 of the SDK for Java
Both V1 and V2 implement optimistic locking with an attribute annotation that marks one property on your bean class to store the version number.
**Differences in optimistic locking behavior**
| | V1 | V2 |
| --- | --- | --- |
| Bean class annotation | @DynamoDBVersionAttribute | @DynamoDbVersionAttribute (note that V2 uses a lowercase "b") |
| Initial save | Version number attribute set to 1. | The starting value for the version attribute set with `@DynamoDbVersionAttribute(startAt = X)`. Default value is 0. |
| Update | The version number attribute is incremented by 1 if the conditional check verifies that the version number of the object being updated matches the number in the database. | The version number attribute is incremented if the conditional check verifies that the version number of the object being updated matches the number in the database. The version number attribute incremented by the `incrementBy` option set with `@DynamoDbVersionAttribute(incrementBy = X)`. Default value is 1. |
| Delete | DynamoDBMapper adds a conditional check that the version number of the object being deleted matches the version number in the database. | V2 does not does not automatically add conditions for the delete operations. You must add condition expressions manually if you want to control the delete behavior. In the following example `recordVersion` is the bean's version attribute. // 1. Read the item and get its current version.
Customer item = customerTable.getItem(Key.builder().partitionValue("someId").build());
AttributeValue currentVersion = item.getRecordVersion();
// 2. Create conditional delete with the `currentVersion` value.
DeleteItemEnhancedRequest deleteItemRequest =
DeleteItemEnhancedRequest.builder()
.key(KEY)
.conditionExpression(Expression.builder()
.expression("recordVersion = :current_version_value")
.putExpressionValue(":current_version_value", currentVersion)
.build()).build();
customerTable.deleteItem(deleteItemRequest);
|
| Transactional Write with a Condition Check | You cannot use a bean class that is annotated with @DynamoDBVersionAttribute in an addConditionCheck method. | You can use a bean class with the @DynamoDbVersionAttribute annotation in an addConditionCheck builder method for a transactWriteItems request. |
| Disable | Disable optimistic locking by changing the DynamoDBMapperConfig.SaveBehavior enumeration value from UPDATE to CLOBBER. | Do not use the `@DynamoDbVersionAttribute` annotation. |
# Fluent setters differences between version 1 and version 2 of the SDK for Java
You can use POJOs with fluent setters in the DynamoDB mapping API for V1 and with V2 since version 2.30.29.
For example, the following POJO returns a `Customer` instance from the `setName` method:
```
// V1
@DynamoDBTable(tableName ="Customer")
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this;
}
}
```
However, if you use a version of V2 prior to 2.30.29, `setName` returns a `Customer` instance with a `name` value of `null`.
```
// V2 prior to version 2.30.29.
@DynamoDbBean
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this; // Bug: returns this instance with a `name` value of `null`.
}
}
```
```
// Available in V2 since version 2.30.29.
@DynamoDbBean
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this; // Returns this instance for method chaining with the `name` value set.
}
}
```
# Document API differences between version 1 and version 2 of the AWS SDK for Java
The Document API supports working with JSON-style documents as single items in a DynamoDB table. The V1 Document API has a corresponding API in V2, but instead of using a separate client for the document API as in V1, V2 incorporates document API features in the DynamoDB enhanced client.
In V1, the [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Item.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Item.html) class represents an unstructured record from a DynamoDB table. In V2, an unstructured record is represented by an instance of the [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html) class. Note that primary keys are defined in the table schema for V2, and on the item itself in V1.
The table below compares the differences between the Document APIs in V1 and V2.
| Use case | V1 | V2 |
| --- |--- |--- |
| Create a document client | AmazonDynamoDB client = ... //Create a client.
DynamoDB documentClient = new DynamoDB(client);
| // The V2 Document API uses the same DynamoDbEnhancedClient
// that is used for mapping POJOs.
DynamoDbClient standardClient = ... //Create a standard client.
DynamoDbEnhancedClient enhancedClient = ... // Create an enhanced client.
|
| Reference a table | Table documentTable = docClient.documentClient("Person"); | DynamoDbTable documentTable = enhancedClient.table("Person",
TableSchema.documentSchemaBuilder()
.addIndexPartitionKey(TableMetadata.primaryIndexName(),"id", AttributeValueType.S)
.attributeConverterProviders(AttributeConverterProvider.defaultProvider())
.build());
|
| **Work with semi-structured data** |
| --- |
| Put item | Item item = new Item()
.withPrimaryKey("id", 50)
.withString("firstName", "Shirley");
PutItemOutcome outcome = documentTable.putItem(item);
| EnhancedDocument personDocument = EnhancedDocument.builder()
.putNumber("id", 50)
.putString("firstName", "Shirley")
.build();
documentTable.putItem(personDocument);
|
| Get item | GetItemOutcome outcome = documentTable.getItemOutcome( "id", 50);
Item personDocFromDb = outcome.getItem();
String firstName = personDocFromDb.getString("firstName");
| EnhancedDocument personDocFromDb = documentTable
.getItem(Key.builder()
.partitionValue(50)
.build());
String firstName = personDocFromDb.getString("firstName");
|
| **Work with JSON items** |
| --- |
| Convert a JSON structure to use it with the Document API | // The 'jsonPerson' identifier is a JSON string.
Item item = new Item().fromJSON(jsonPerson);
| // The 'jsonPerson' identifier is a JSON string.
EnhancedDocument document = EnhancedDocument.builder()
.json(jsonPerson).build());
|
| Put JSON | documentTable.putItem(item)
| documentTable.putItem(document);
|
| Read JSON | GetItemOutcome outcome = //Get item.
String jsonPerson = outcome.getItem().toJSON();
| String jsonPerson = documentTable.getItem(Key.builder()
.partitionValue(50).build())
.fromJson();
|
## API reference and guides for document APIs
| | V1 | V2 |
| --- | --- | --- |
| API reference | [API reference](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/package-summary.html) | [API reference](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) |
| Documentation guide | [Amazon DynamoDB Developer Guide](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/JavaDocumentAPIItemCRUD.html) | [Enhanced Document API](ddb-en-client-doc-api.md) (this guide) |
# V1 Xpec API to V2 Expressions API
The Expression Specification (Xspec) API available in V1 that helps create expressions to work with document-oriented data is not available in V2. V2 uses the Expression API, which works with both document-oriented data and object-to-item mapped data.
****
| | V1 | V2 |
| --- | --- | --- |
| API name | Expression Specification (Xspec) API | Expression API |
| Works with | Methods of the Document API [Table](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Table.html) class such as [updateItem](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Table.html#updateItem-java.lang.String-java.lang.Object-com.amazonaws.services.dynamodbv2.xspec.UpdateItemExpressionSpec-) and [scan](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/Table.html#scan-com.amazonaws.services.dynamodbv2.xspec.ScanExpressionSpec-) | Both APIs of DynamoDB Enhanced Client: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) For both types of APIs, after you have acquired a [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html) instance: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) you use expressions in `DynamoDbTable` methods when you create request objects. For example in the `filterExpression` method of the [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryEnhancedRequest.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryEnhancedRequest.Builder.html) |
| Resources | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-v1-xspec-migrate.html) | [Expressions information](ddb-en-client-expressions.md) in this Java Developer Guide |
# Encryption library migration
For information about migrating the encryption library for DynamoDB to work with V2 of the Java SDK, see the [Amazon DynamoDB Encryption Client Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/ddb-java-migrate.html).
# Changes in automatic Amazon SQS request batching from version 1 to version 2
This topic details the changes in automatic request batching for Amazon SQS between version 1 and version 2 of the AWS SDK for Java.
## High-level changes
The AWS SDK for Java 1.x performs client-side buffering using a separate `[AmazonSQSBufferedAsyncClient](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/sqs/buffered/AmazonSQSBufferedAsyncClient.html)` class that requires explicit initialization for request batching.
The AWS SDK for Java 2.x simplifies and enhances buffering functionality with the `[SqsAsyncBatchManager](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html)`. The implementation of this interface provides automatic request batching capabilities directly integrated with the standard `[SqsAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/SqsAsyncClient.html)`. To learn about v2's `SqsAsyncBatchManager`, see the [Use automatic request batching for Amazon SQS with the AWS SDK for Java 2.x](sqs-auto-batch.md) topic in this guide.
| Change | v1 | v2 |
| --- | --- | --- |
| Maven dependencies |
com.amazonaws
aws-java-sdk-bom
1.12.7821
pom
import
com.amazonaws
aws-java-sdk-sqs
|
software.amazon.awssdk
bom
2.31.152
pom
import
software.amazon.awssdk
sqs
|
| Package names | com.amazonaws.services.sqs.buffered | software.amazon.awssdk.services.sqs.batchmanager |
| Class names | `[AmazonSQSBufferedAsyncClient](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/sqs/buffered/AmazonSQSBufferedAsyncClient.html)` | [SqsAsyncBatchManager](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html) |
1 [Latest version](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). 2 [Latest version](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
## Using automatic SQS request batching
| Change | v1 | v2 |
| --- | --- | --- |
| Create a batch manager | AmazonSQSAsync sqsAsync = new AmazonSQSAsyncClient();
AmazonSQSAsync bufferedSqs = new
AmazonSQSBufferedAsyncClient(sqsAsync);
| SqsAsyncClient asyncClient = SqsAsyncClient.create();
SqsAsyncBatchManager sqsAsyncBatchManager =
asyncClient.batchManager();
|
| Create a batch manager with custom configuration | AmazonSQSAsync sqsAsync = new AmazonSQSAsyncClient();
QueueBufferConfig queueBufferConfig = new QueueBufferConfig()
.withMaxBatchOpenMs(200)
.withMaxBatchSize(10)
.withMinReceiveWaitTimeMs(1000)
.withVisibilityTimeoutSeconds(20)
.withReceiveMessageAttributeNames(messageAttributeValues);
AmazonSQSAsync bufferedSqs =
new AmazonSQSBufferedAsyncClient(sqsAsync, queueBufferConfig);
| BatchOverrideConfiguration batchOverrideConfiguration =
BatchOverrideConfiguration.builder()
.sendRequestFrequency(Duration.ofMillis(200))
.maxBatchSize(10)
.receiveMessageMinWaitDuration(Duration.ofMillis(1000))
.receiveMessageVisibilityTimeout(Duration.ofSeconds(20))
.receiveMessageSystemAttributeNames(messageSystemAttributeNames)
.receiveMessageAttributeNames(messageAttributeValues)
.build();
SqsAsyncBatchManager sqsAsyncBatchManager = SqsAsyncBatchManager.builder()
.overrideConfiguration(batchOverrideConfiguration)
.client(SqsAsyncClient.create())
.scheduledExecutor(Executors.newScheduledThreadPool(8))
.build();
|
| Send messages | Future sendResultFuture =
bufferedSqs.sendMessageAsync(new SendMessageRequest()
.withQueueUrl(queueUrl)
.withMessageBody(body));
| CompletableFuture sendCompletableFuture =
sqsAsyncBatchManager.sendMessage(
SendMessageRequest.builder()
.queueUrl(queueUrl)
.messageBody(body)
.build());
|
| Delete messages | Future deletResultFuture =
bufferedSqs.deleteMessageAsync(new DeleteMessageRequest()
.withQueueUrl(queueUrl));
| CompletableFuture deleteResultCompletableFuture
= sqsAsyncBatchManager.deleteMessage(
DeleteMessageRequest.builder()
.queueUrl(queueUrl)
.build());
|
| Change visibility of messages | Future changeVisibilityResultFuture =
bufferedSqs.changeMessageVisibilityAsync
(new ChangeMessageVisibilityRequest()
.withQueueUrl(queueUrl)
.withVisibilityTimeout(20));
| CompletableFuture changeResponseCompletableFuture
= sqsAsyncBatchManager.changeMessageVisibility(
ChangeMessageVisibilityRequest.builder()
.queueUrl(queueUrl)
.visibilityTimeout(20)
.build());
|
| Receive messages | ReceiveMessageResult receiveResult =
bufferedSqs.receiveMessage(
new ReceiveMessageRequest()
.withQueueUrl(queueUrl));
| CompletableFuture
responseCompletableFuture = sqsAsyncBatchManager.receiveMessage(
ReceiveMessageRequest.builder()
.queueUrl(queueUrl)
.build());
|
## Asynchronous return type differences
| Change | v1 | v2 |
| --- | --- | --- |
| Return type | Future | CompletableFuture |
| Callback mechanism | Requires an AsyncHandler with separate onSuccess and onError methods | Uses CompletableFuture APIs provided by the JDK, such as whenComplete(), thenCompose(), thenApply() |
| Exception handling | Uses AsyncHandler\$1onError() method | Uses CompletableFuture APIs provided by the JDK, such as exceptionally(), handle(), or whenComplete() |
| Cancellation | Basic support through Future.cancel() | Cancelling a parent CompletableFuture automatically cancels all dependent futures in the chain |
## Asynchronous completion handling differences
| Change | v1 | v2 |
| --- | --- | --- |
| Response handler implementation | Future future = bufferedSqs.receiveMessageAsync(
receiveRequest,
new AsyncHandler() {
@Override
public void onSuccess(ReceiveMessageRequest request,
ReceiveMessageResult result) {
List messages = result.getMessages();
System.out.println("Received " + messages.size() + " messages");
for (Message message : messages) {
System.out.println("Message ID: " + message.getMessageId());
System.out.println("Body: " + message.getBody());
}
}
@Override
public void onError(Exception e) {
System.err.println("Error receiving messages: " + e.getMessage());
e.printStackTrace();
}
}
);
| CompletableFuture completableFuture = sqsAsyncBatchManager
.receiveMessage(ReceiveMessageRequest.builder()
.queueUrl(queueUrl).build())
.whenComplete((receiveMessageResponse, throwable) -> {
if (throwable != null) {
System.err.println("Error receiving messages: " + throwable.getMessage());
throwable.printStackTrace();
} else {
List messages = receiveMessageResponse.messages();
System.out.println("Received " + messages.size() + " messages");
for (Message message : messages) {
System.out.println("Message ID: " + message.messageId());
System.out.println("Body: " + message.body());
}
}
});
|
## Key configuration parameters
****
| Parameter | v1 | v2 |
| --- | --- | --- |
| Maximum batch size | maxBatchSize (default 10 requests per batch) | maxBatchSize (default 10 requests per batch) |
| Batch wait time | maxBatchOpenMs (default 200 ms) | sendRequestFrequency (default 200 ms) |
| Visibility timeout | visibilityTimeoutSeconds (-1 for queue default) | receiveMessageVisibilityTimeout (queue default) |
| Minimum wait time | longPollWaitTimeoutSeconds (20s when longPoll is true) | receiveMessageMinWaitDuration (default 50 ms) |
| Message attributes | Set using ReceiveMessageRequest | receiveMessageAttributeNames (none by default) |
| System attributes | Set using ReceiveMessageRequest | receiveMessageSystemAttributeNames (none by default) |
| Long polling | longPoll (default is true) | Not supported to avoid open connections waiting until the server sends the messages |
| Maximum wait time for long polling | longPollWaitTimeoutSeconds (default 20s) | Not supported to avoid open connections waiting until the server sends the messages |
| Maximum number of prefetched receive batches stored client-side | maxDoneReceiveBatches (10 batches) | Not supported because it is handled internally |
| Maximum number of active outbound batches processed simultaneously | maxInflightOutboundBatches (default 5 batches) | Not supported because it is handled internally |
| Maximum number of active receive batches processed simultaneously | maxInflightReceiveBatches (default 10 batches) | Not supported because it is handled internally |