AWS SDK for Java 2.x - Developer Guide for version 2.x

AWS SDK for Java 2.x

Developer Guide for version 2.x

AWS SDK for Java 2.x Developer Guide for version 2.x

AWS SDK for Java 2.x: Developer Guide for version 2.x

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not

Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or

discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may

or may not be aﬃliated with, connected to, or sponsored by Amazon.

AWS SDK for Java 2.x Developer Guide for version 2.x

Table of Contents

Developer Guide - AWS SDK for Java 2.x .............................................................................................. 1

Get started with the SDK ............................................................................................................ 1

Develop mobile applications ........................................................................................................ 1

Maintenance and support for SDK major versions .......................................................................... 1

Additional resources ................................................................................................................... 1

Contribute to the SDK ................................................................................................................ 2

Get started tutorial ............................................................................................................................ 3

Step 1: Set up for this tutorial ..................................................................................................... 3

Step 2: Create the project ........................................................................................................... 3

Step 3: Write the code ................................................................................................................ 6

Step 4: Build and run the application ........................................................................................... 9

Success ........................................................................................................................... 10

Cleanup ........................................................................................................................... 10

Next steps ............................................................................................................................... 10

Setup .............................................................................................................................................. 11

Basic setup .............................................................................................................................. 11

Overview ......................................................................................................................... 11

Sign-in ability to the AWS access portal .............................................................................. 12

Set up single sign-on access for the SDK ............................................................................. 12

Sign in using the AWS CLI ................................................................................................. 13

Install Java and a build tool .............................................................................................. 13

Additional authentication options ....................................................................................... 13

Build tools setup ...................................................................................................................... 14

Set up an Apache Maven project ........................................................................................ 14

Set up a Gradle project ..................................................................................................... 17

Set up a GraalVM Native Image project ....................................................................................... 22

Prerequisites .................................................................................................................... 22

Create a project using the archetype .................................................................................. 22

Build a native image ......................................................................................................... 23

Use the SDK .................................................................................................................................... 24

Work with service clients ........................................................................................................... 24

Create a service client ....................................................................................................... 24

Default client conﬁguration ............................................................................................... 24

Conﬁgure service clients .................................................................................................... 24

Make requests .................................................................................................................. 25

Handle responses ............................................................................................................. 25

Close the service client ..................................................................................................... 25

Handle exceptions .................................................................................................................... 26

Use waiters .............................................................................................................................. 27

HTTP clients ............................................................................................................................ 27

Retries .................................................................................................................................... 27

Timeouts ................................................................................................................................. 27

Execution interceptors ............................................................................................................... 27

Additional information .............................................................................................................. 28

Provide temporary credentials to the SDK ................................................................................... 28

Use temporary credentials ................................................................................................. 28

Default credentials provider chain ...................................................................................... 29

Use a speciﬁc credentials provider or provider chain ............................................................. 30

Use proﬁles ..................................................................................................................... 31

Load temporary credentials from an external process ........................................................... 33

Supply temporary credentials in code ................................................................................. 35

Conﬁgure IAM roles for Amazon EC2 .................................................................................. 37

AWS region selection ................................................................................................................ 38

Choosing a region ............................................................................................................ 38

iii

AWS SDK for Java 2.x Developer Guide for version 2.x

Choosing a speciﬁc endpoint ............................................................................................. 39

Automatically determine the Region from the environment ................................................... 39

Checking for service availability in a Region ......................................................................... 40

Reduce SDK startup time for AWS Lambda .................................................................................. 40

Use the SDK’s UrlConnectionHttpClient ....................................................................... 40

Use the SDK's AwsCrtAsyncHttpClient ........................................................................... 41

Remove unused HTTP client dependencies .......................................................................... 41

Conﬁgure service clients to shortcut lookups ....................................................................... 42

Initialize the SDK client outside of the Lambda function handler ............................................ 42

Minimize dependency injection ......................................................................................... 43

Use a Maven Archetype targeting AWS Lambda ................................................................... 43

Lambda SnapStart ............................................................................................................ 43

Version 2.x changes that aﬀect startup time ........................................................................ 43

Additional resources ......................................................................................................... 43

HTTP clients ............................................................................................................................ 44

Available clients ............................................................................................................... 44

Client recommendations .................................................................................................... 44

Smart defaults ................................................................................................................. 46

Proxy support .................................................................................................................. 47

Conﬁgure the Apache-based HTTP client ............................................................................. 49

Conﬁgure the URLConnection-based HTTP client .................................................................. 52

Conﬁgure the Netty-based HTTP client ............................................................................... 56

Conﬁgure the AWS CRT-based HTTP client .......................................................................... 60

Exception handling ................................................................................................................... 64

Why unchecked exceptions? ............................................................................................... 65

AwsServiceException (and subclasses) ................................................................................. 65

SdkClientException ........................................................................................................... 65

Exceptions and retry behavior ............................................................................................ 66

Logging ................................................................................................................................... 66

Log4j 2 conﬁguration ﬁle .................................................................................................. 66

Add logging dependency ................................................................................................... 66

SDK-speciﬁc errors and warnings ........................................................................................ 67

Request/response summary logging ................................................................................... 67

Verbose wire logging ........................................................................................................ 68

Set the JVM TTL for DNS name lookups ..................................................................................... 71

How to set the JVM TTL ................................................................................................... 72

Best practices .......................................................................................................................... 72

Reuse an SDK client ......................................................................................................... 72

Close input streams .......................................................................................................... 72

Tune HTTP conﬁgurations ................................................................................................. 73

Use OpenSSL for Netty ..................................................................................................... 73

Conﬁgure API timeouts ..................................................................................................... 73

Use metrics ..................................................................................................................... 74

SDK features .................................................................................................................................... 75

Asynchronous programming ...................................................................................................... 75

Non-streaming operations ................................................................................................. 75

Streaming operations ........................................................................................................ 77

Advanced operations ........................................................................................................ 80

DynamoDB Enhanced Client API ................................................................................................ 81

Get started ...................................................................................................................... 81

Basics .............................................................................................................................. 87

Extensions ..................................................................................................................... 123

Advanced table schema features ...................................................................................... 126

Enhanced Document API ................................................................................................. 148

Non-blocking asynchronous operations ............................................................................. 157

Annotations ................................................................................................................... 157

HTTP/2 ................................................................................................................................. 159

iv

AWS SDK for Java 2.x Developer Guide for version 2.x

SDK Metrics ........................................................................................................................... 159

Prerequisites .................................................................................................................. 159

How to enable metrics collection ...................................................................................... 160

What information is collected? ......................................................................................... 161

How can I use this information? ....................................................................................... 161

Service client metrics ...................................................................................................... 161

Pagination ............................................................................................................................. 164

Synchronous pagination .................................................................................................. 164

Asynchronous pagination ................................................................................................. 166

AWS CRT-based S3 client ........................................................................................................ 169

Add dependencies .......................................................................................................... 170

Create an instance .......................................................................................................... 170

Use the AWS CRT-based S3 client ..................................................................................... 171

S3 Transfer Manager ............................................................................................................... 171

Get started .................................................................................................................... 172

Upload a ﬁle .................................................................................................................. 173

Download a ﬁle .............................................................................................................. 174

Copy an object ............................................................................................................... 174

Upload a directory .......................................................................................................... 175

Download to a directory .................................................................................................. 176

Waiters .................................................................................................................................. 177

Prerequisites .................................................................................................................. 177

Using waiters ................................................................................................................. 177

Conﬁgure waiters ........................................................................................................... 178

Code examples ............................................................................................................... 178

IAM Policy Builder API ............................................................................................................. 179

Create an IamPolicy ..................................................................................................... 179

Use an IamPolicy with IAM ........................................................................................... 182

Work with AWS services .................................................................................................................. 185

CloudWatch .......................................................................................................................... 185

Get metrics from CloudWatch .......................................................................................... 186

Publish custom metric data to CloudWatch ........................................................................ 187

Work with CloudWatch alarms ......................................................................................... 188

Use alarm actions in CloudWatch ..................................................................................... 191

Send events to CloudWatch ............................................................................................. 192

Amazon Cognito .................................................................................................................... 195

Create a user pool .......................................................................................................... 195

List users from a user pool .............................................................................................. 196

Create an identity pool ................................................................................................... 196

Add an app client ........................................................................................................... 197

Add a third-party identity provider ................................................................................... 198

Get credentials for an ID ................................................................................................. 199

AWS database services ............................................................................................................ 200

Amazon DynamoDB ........................................................................................................ 200

Amazon RDS .................................................................................................................. 200

Amazon Redshift ............................................................................................................ 201

Amazon Aurora Serverless v1 ........................................................................................... 201

Amazon DocumentDB ..................................................................................................... 201

DynamoDB ........................................................................................................................... 201

Work with tables in DynamoDB ........................................................................................ 202

Work with items in DynamoDB ......................................................................................... 208

Amazon EC2 .......................................................................................................................... 213

Manage Amazon EC2 instances ........................................................................................ 213

Use elastic IP addresses in Amazon EC2 ............................................................................ 218

Use AWS Regions and Availability Zones ............................................................................ 220

Work with Amazon EC2 key pairs ..................................................................................... 223

Work with security groups in Amazon EC2 ......................................................................... 225

v

AWS SDK for Java 2.x Developer Guide for version 2.x

Work with Amazon EC2 instance metadata ........................................................................ 228

IAM ....................................................................................................................................... 232

Manage IAM access keys .................................................................................................. 232

Manage IAM Users .......................................................................................................... 236

Use IAM account aliases .................................................................................................. 239

Work with IAM policies .................................................................................................... 241

Work with IAM server certiﬁcates ..................................................................................... 246

Kinesis ................................................................................................................................... 249

Subscribe to Amazon Kinesis Data Streams ........................................................................ 249

Lambda ................................................................................................................................. 256

Invoke a Lambda function ............................................................................................... 256

List Lambda functions ..................................................................................................... 257

Delete a Lambda function ............................................................................................... 257

Amazon Pinpoint .................................................................................................................... 258

Create a project ............................................................................................................. 258

Create a dynamic segment .............................................................................................. 259

Import a static segment .................................................................................................. 260

List segments for your project .......................................................................................... 261

Create a campaign .......................................................................................................... 262

Send a message ............................................................................................................. 264

Amazon S3 ............................................................................................................................ 265

Use access points or Multi-Region Access Points ................................................................. 266

Bucket operations ........................................................................................................... 266

Object operations ........................................................................................................... 270

Presigned URLs .............................................................................................................. 275

Cross-Region access ........................................................................................................ 278

Checksums ..................................................................................................................... 279

Amazon SNS .......................................................................................................................... 282

Create a topic ................................................................................................................ 282

List your Amazon SNS topics ........................................................................................... 283

Subscribe an endpoint to a topic ...................................................................................... 283

Publish a message to a topic ........................................................................................... 284

Unsubscribe an endpoint from a topic ............................................................................... 285

Delete a topic ................................................................................................................ 285

Amazon SQS .......................................................................................................................... 286

Queue operations ........................................................................................................... 286

Message operations ........................................................................................................ 289

Amazon Transcribe ................................................................................................................. 291

Set up the microphone ................................................................................................... 291

Create a publisher .......................................................................................................... 292

Create the client and start the stream ............................................................................... 294

More information ........................................................................................................... 291

Code examples ............................................................................................................................... 296

Actions and scenarios .............................................................................................................. 296

API Gateway .................................................................................................................. 297

Application Recovery Controller ........................................................................................ 300

Aurora ........................................................................................................................... 302

Auto Scaling .................................................................................................................. 323

CloudFront ..................................................................................................................... 337

CloudWatch ................................................................................................................... 347

CloudWatch Events ......................................................................................................... 376

CloudWatch Logs ............................................................................................................ 378

Amazon Cognito Identity Provider .................................................................................... 381

Amazon Comprehend ...................................................................................................... 392

DynamoDB ..................................................................................................................... 396

Amazon EC2 .................................................................................................................. 425

Amazon ECS .................................................................................................................. 447

vi

AWS SDK for Java 2.x Developer Guide for version 2.x

OpenSearch Service ........................................................................................................ 451

EventBridge ................................................................................................................... 454

Forecast ........................................................................................................................ 475

AWS Glue ...................................................................................................................... 479

HealthImaging ............................................................................................................... 491

IAM ............................................................................................................................... 507

Amazon Keyspaces .......................................................................................................... 528

Kinesis ........................................................................................................................... 545

AWS KMS ...................................................................................................................... 550

Lambda ......................................................................................................................... 556

MediaConvert ................................................................................................................. 566

Migration Hub ................................................................................................................ 575

Amazon Personalize ........................................................................................................ 580

Amazon Personalize Events .............................................................................................. 599

Amazon Personalize Runtime ........................................................................................... 601

Amazon Pinpoint ............................................................................................................ 604

Amazon Pinpoint SMS and Voice API ................................................................................ 619

Amazon Polly ................................................................................................................. 620

Amazon RDS .................................................................................................................. 622

Amazon Redshift ............................................................................................................ 644

Amazon Rekognition ....................................................................................................... 646

Route53 domain registration ........................................................................................... 673

Amazon S3 .................................................................................................................... 687

S3 Glacier ...................................................................................................................... 728

SageMaker ..................................................................................................................... 735

Secrets Manager ............................................................................................................. 754

Amazon SES .................................................................................................................. 758

Amazon SES API v2 ........................................................................................................ 762

Amazon SNS .................................................................................................................. 764

Amazon SQS .................................................................................................................. 781

Step Functions ............................................................................................................... 792

AWS STS ....................................................................................................................... 806

AWS Support ................................................................................................................. 807

Systems Manager ........................................................................................................... 822

Amazon Textract ............................................................................................................ 825

Cross-service examples ............................................................................................................ 829

Build an app to submit data to a DynamoDB table ............................................................. 829

Building an Amazon Lex chatbot ...................................................................................... 830

Building an Amazon SNS application ................................................................................. 830

Create a messaging application ........................................................................................ 830

Create a serverless application to manage photos ............................................................... 831

Create a web application to track DynamoDB data .............................................................. 831

Create a web application to track Amazon Redshift data ...................................................... 831

Create an Aurora Serverless work item tracker ................................................................... 832

Create an application to analyze customer feedback ........................................................... 832

Detect PPE in images ...................................................................................................... 832

Detect objects in images ................................................................................................. 833

Detect people and objects in a video ................................................................................ 833

Publish messages to queues ............................................................................................ 833

Use API Gateway to invoke a Lambda function ................................................................... 834

Use Step Functions to invoke Lambda functions ................................................................. 834

Use scheduled events to invoke a Lambda function ............................................................ 834

Security ......................................................................................................................................... 836

Data protection ...................................................................................................................... 836

Transport Layer Security (TLS) ................................................................................................. 837

Check TLS versions ......................................................................................................... 837

Enforce TLS versions ....................................................................................................... 838

vii

AWS SDK for Java 2.x Developer Guide for version 2.x

Migrate to TLS 1.2 .......................................................................................................... 838

Identity and Access Management .............................................................................................. 838

Audience ....................................................................................................................... 838

Authenticating with identities .......................................................................................... 839

Managing access using policies ......................................................................................... 841

How AWS services work with IAM ..................................................................................... 842

Troubleshooting AWS identity and access .......................................................................... 842

Compliance Validation ............................................................................................................. 844

Resilience .............................................................................................................................. 844

Infrastructure Security ............................................................................................................. 845

Migrate to version 2 ....................................................................................................................... 846

What’s new ............................................................................................................................ 846

What's diﬀerent between 1.x and 2.x ........................................................................................ 846

Package name change ..................................................................................................... 847

Adding version 2.x to your project .................................................................................... 847

Client builders ................................................................................................................ 847

Client Conﬁguration ........................................................................................................ 848

Setter methods .............................................................................................................. 849

Class names ................................................................................................................... 849

Region class ................................................................................................................... 849

Immutable POJOs ........................................................................................................... 850

Streaming operations ...................................................................................................... 850

Exception changes .......................................................................................................... 851

Service-speciﬁc changes .................................................................................................. 851

Additional client changes ................................................................................................. 851

Credentials provider changes ........................................................................................... 852

Region class name changes .............................................................................................. 854

Exception class name changes .......................................................................................... 855

Libraries and utilities ....................................................................................................... 856

Use the SDK for Java 1.x and 2.x side-by-side ............................................................................ 857

Document history ........................................................................................................................... 858

viii

AWS SDK for Java 2.x Developer Guide for version 2.x

Get started with the SDK

Developer Guide - AWS SDK for Java

2.x

The AWS SDK for Java provides a Java API for AWS services. Using the SDK, you can build Java

applications that work with Amazon S3, Amazon EC2, DynamoDB, and more.

The AWS SDK for Java 2.x is a major rewrite of the version 1.x code base. It’s built on top of Java 8+ and

adds several frequently requested features. These include support for non-blocking I/O and the ability to

plug in a diﬀerent HTTP implementation at runtime.

We regularly add support for new services to the AWS SDK for Java. For a list of changes and features in

a particular version, view the change log.

Get started with the SDK

If you’re ready to get hands-on with the SDK, follow the Get started tutorial (p. 3) tutorial.

To set up your development environment, see Setup (p. 11).

If you’re currently using version 1.x of the SDK for Java, see Migrate to version 2 (p. 846) for speciﬁc

guidance.

For information on making requests to Amazon S3, DynamoDB, Amazon EC2 and other AWS services, see

Use the SDK for Java (p. 24) and Work with AWS services (p. 185).

Develop mobile applications

If you’re a mobile app developer, Amazon Web Services provides the AWS Amplify framework. For more

information, see the Amplify Documentation.

Maintenance and support for SDK major versions

For information about maintenance and support for SDK major versions and their underlying

dependencies, see the following topics in the AWS SDKs and Tools Reference Guide:

• AWS SDKs and Tools Maintenance Policy

• AWS SDKs and Tools Version Support Matrix

Additional resources

In addition to this guide, the following are valuable online resources for AWS SDK for Java developers:

• AWS SDK for Java 2.x API Reference

• Java developer blog

1

AWS SDK for Java 2.x Developer Guide for version 2.x

Contribute to the SDK

• Java development topic in AWS re:Post

• GitHub:

• Developer Guide documentation source

• SDK source

• AWS SDK Code Examples library

• @awsforjava (Twitter)

Contribute to the SDK

Developers can also contribute feedback through the following channels:

• Submit issues on GitHub:

• Submit Developer Guide documentation issues

• Submit SDK issues

• Join an informal chat about the SDK on the AWS SDK for Java 2.x gitter channel

2

AWS SDK for Java 2.x Developer Guide for version 2.x

Step 1: Set up for this tutorial

Get started with the AWS SDK for

Java 2.x

The AWS SDK for Java 2.x provides Java APIs for Amazon Web Services (AWS). Using the SDK, you can

build Java applications that work with Amazon S3, Amazon EC2, DynamoDB, and more.

This tutorial shows you how to use Apache Maven to deﬁne dependencies for the SDK for Java 2.x and

then write code that connects to Amazon S3 to upload a ﬁle.

Follow these steps to complete this tutorial:

• Step 1: Set up for this tutorial (p. 3)

• Step 2: Create the project (p. 3)

• Step 3: Write the code (p. 6)

• Step 4: Build and run the application (p. 9)

Step 1: Set up for this tutorial

Before you begin this tutorial, you need the following:

• Permission to access Amazon S3

• A Java development environment that is conﬁgured to access AWS services using single sign-on to the

AWS IAM Identity Center

Use the instructions in Basic setup (p. 11) to get set up for this tutorial. After you have conﬁgured

your development environment with single sign-on access (p. 12) for the Java SDK and you have an

active AWS access portal session (p. 13), continue with Step 2 of this tutorial.

Step 2: Create the project

To create the project for this tutorial, you run a Maven command that prompts you for input on how to

conﬁgure the project. After all input is entered and conﬁrmed, Maven ﬁnishes building out the project by

creating a pom.xml and creates stub Java ﬁles.

1. Open a terminal or command prompt window and navigate to a directory of your choice, for example,

your Desktop or Home folder.

2.

Enter the following command at the terminal and press Enter.

mvn archetype:generate \

-DarchetypeGroupId=software.amazon.awssdk \

-DarchetypeArtifactId=archetype-app-quickstart \

-DarchetypeVersion=2.20.43

3. Enter the value listed in the second column for each prompt.

Prompt Value to enter

Define value for property 'service': s3

3

AWS SDK for Java 2.x Developer Guide for version 2.x

Step 2: Create the project

Prompt Value to enter

Define value for property

'httpClient':

apache-client

Define value for property

'nativeImage':

false

Define value for property

'credentialProvider'

identity-center

Define value for property 'groupId': org.example

Define value for property

'artifactId':

getstarted

Define value for property 'version'

1.0-SNAPSHOT:

<Enter>

Define value for property 'package'

org.example:

<Enter>

4.

After the last value is entered, Maven lists the choices you made. Conﬁrm by entering Y or re-enter

values by entering N.

Maven creates the project folder named getstarted based on the artifactId value that you entered.

Inside the getstarted folder, ﬁnd a README.md ﬁle that you can review, a pom.xml ﬁle, and a src

directory.

Maven builds the following directory tree.

getstarted

### README.md

### pom.xml

### src

### main

# ### java

# # ### org

# # ### example

# # ### App.java

# # ### DependencyFactory.java

# # ### Handler.java

# ### resources

# ### simplelogger.properties

### test

### java

### org

### example

### HandlerTest.java

10 directories, 7 files

The following shows the contents of the pom.xml project ﬁle.

pom.xml

The dependencyManagement section contains a dependency to the AWS SDK for Java 2.x and the

dependencies section has a dependency for Amazon S3. The project uses Java 1.8 because of the 1.8

value in the maven.compiler.source and maven.compiler.target properties.

4

AWS SDK for Java 2.x Developer Guide for version 2.x

Step 2: Create the project

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/

XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://

maven.apache.org/xsd/maven-4.0.0.xsd">

<groupId>org.example</groupId>

<artifactId>getstarted</artifactId>

<version>1.0-SNAPSHOT</version>

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

<maven.compiler.source>1.8</maven.compiler.source>

<maven.compiler.target>1.8</maven.compiler.target>

<maven.shade.plugin.version>3.2.1</maven.shade.plugin.version>

<maven.compiler.plugin.version>3.6.1</maven.compiler.plugin.version>

<exec-maven-plugin.version>1.6.0</exec-maven-plugin.version>

<aws.java.sdk.version>2.20.43</aws.java.sdk.version> <-------- SDK version picked

up from archetype version.

<slf4j.version>1.7.28</slf4j.version>

<junit5.version>5.8.1</junit5.version>

</properties>

<groupId>software.amazon.awssdk</groupId>

<version>${aws.java.sdk.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>s3</artifactId> <-------- S3 dependency

<groupId>software.amazon.awssdk</groupId>

<artifactId>netty-nio-client</artifactId>

</exclusion>

<groupId>software.amazon.awssdk</groupId>

<artifactId>apache-client</artifactId>

</exclusion>

</exclusions>

</dependency>

<groupId>software.amazon.awssdk</groupId>

<artifactId>sso</artifactId> <-------- Required for identity center

authentication.

</dependency>

<groupId>software.amazon.awssdk</groupId>

<artifactId>ssooidc</artifactId> <-------- Required for identity center

authentication.

</dependency>

<groupId>software.amazon.awssdk</groupId>

5

AWS SDK for Java 2.x Developer Guide for version 2.x

Step 3: Write the code

<artifactId>apache-client</artifactId> <-------- HTTP client specified.

<groupId>commons-logging</groupId>

<artifactId>commons-logging</artifactId>

</exclusion>

</exclusions>

</dependency>

<version>${slf4j.version}</version>

</dependency>

<artifactId>slf4j-simple</artifactId>

<version>${slf4j.version}</version>

</dependency>

<!-- Needed to adapt Apache Commons Logging used by Apache HTTP Client to Slf4j to

avoid

ClassNotFoundException: org.apache.commons.logging.impl.LogFactoryImpl during

runtime -->

<version>${slf4j.version}</version>

</dependency>

<groupId>org.junit.jupiter</groupId>

<artifactId>junit-jupiter</artifactId>

<version>${junit5.version}</version>

</dependency>

</dependencies>

<build>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>

<version>${maven.compiler.plugin.version}</version>

</plugin>

</plugins>

</build>

</project>

Step 3: Write the code

The following code shows the App class created by Maven. The main method is the entry point into the

application, which creates an instance of the Handler class and then calls its sendRequest method.

App class

package org.example;

import org.slf4j.Logger;

6

AWS SDK for Java 2.x Developer Guide for version 2.x

Step 3: Write the code

import org.slf4j.LoggerFactory;

public class App {

private static final Logger logger = LoggerFactory.getLogger(App.class);

public static void main(String... args) {

logger.info("Application starts");

Handler handler = new Handler();

handler.sendRequest();

logger.info("Application ends");

}

The DependencyFactory class created by Maven contains the s3Client factory method that build

and returns an S3Client instance. The S3Client instance uses an instance of the Apache-based HTTP

client. This is because you speciﬁed apache-client when Maven prompted you for which HTTP client

to use.

The DependencyFactory is shown in the following code.

DependencyFactory class

package org.example;

import software.amazon.awssdk.http.apache.ApacheHttpClient;

import software.amazon.awssdk.services.s3.S3Client;

/**

* The module containing all dependencies required by the {@link Handler}.

*/

public class DependencyFactory {

private DependencyFactory() {}

/**

* @return an instance of S3Client

*/

public static S3Client s3Client() {

return S3Client.builder()

.httpClientBuilder(ApacheHttpClient.builder())

.build();

}

The Handler class contains the main logic of your program. When an instance of Handler is created

in the App class, the DependencyFactory furnishes the S3Client service client. Your code uses the

S3Client instance to call the Amazon S3 service.

Maven generates the following Handler class with a TODO comment. The next step in the tutorial

replaces the TODO with code.

Handler class, Maven-generated

package org.example;

import software.amazon.awssdk.services.s3.S3Client;

7

AWS SDK for Java 2.x Developer Guide for version 2.x

Step 3: Write the code

public class Handler {

private final S3Client s3Client;

public Handler() {

s3Client = DependencyFactory.s3Client();

}

public void sendRequest() {

// TODO: invoking the api calls using s3Client.

}

To ﬁll in the logic, replace the entire contents of the Handler class with the following code. The

sendRequest method is ﬁlled in and the necessary imports are added.

Handler class, implemented

The code ﬁrst creates a new S3 bucket with the last part of the name generated using

System.currentTimeMillis() in order to make the bucket name unique.

After creating the bucket in the createBucket() method, the program uploads an object using

the putObject method of S3Client. The contents of the object is a simple string created with the

RequestBody.fromString method.

Finally, the program deletes the object followed by the bucket in the cleanUp method.

package org.example;

import software.amazon.awssdk.core.sync.RequestBody;

import software.amazon.awssdk.services.s3.S3Client;

import software.amazon.awssdk.services.s3.model.CreateBucketRequest;

import software.amazon.awssdk.services.s3.model.DeleteBucketRequest;

import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;

import software.amazon.awssdk.services.s3.model.HeadBucketRequest;

import software.amazon.awssdk.services.s3.model.PutObjectRequest;

import software.amazon.awssdk.services.s3.model.S3Exception;

public class Handler {

private final S3Client s3Client;

public Handler() {

s3Client = DependencyFactory.s3Client();

}

public void sendRequest() {

String bucket = "bucket" + System.currentTimeMillis();

String key = "key";

createBucket(s3Client, bucket);

System.out.println("Uploading object...");

s3Client.putObject(PutObjectRequest.builder().bucket(bucket).key(key)

.build(),

RequestBody.fromString("Testing with the {sdk-java}"));

System.out.println("Upload complete");

System.out.printf("%n");

cleanUp(s3Client, bucket, key);

8

AWS SDK for Java 2.x Developer Guide for version 2.x

Step 4: Build and run the application

System.out.println("Closing the connection to {S3}");

s3Client.close();

System.out.println("Connection closed");

System.out.println("Exiting...");

}

public static void createBucket(S3Client s3Client, String bucketName) {

try {

s3Client.createBucket(CreateBucketRequest

.builder()

.bucket(bucketName)

.build());

System.out.println("Creating bucket: " + bucketName);

s3Client.waiter().waitUntilBucketExists(HeadBucketRequest.builder()

.bucket(bucketName)

.build());

System.out.println(bucketName + " is ready.");

System.out.printf("%n");

} catch (S3Exception e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

public static void cleanUp(S3Client s3Client, String bucketName, String keyName) {

System.out.println("Cleaning up...");

try {

System.out.println("Deleting object: " + keyName);

DeleteObjectRequest deleteObjectRequest =

DeleteObjectRequest.builder().bucket(bucketName).key(keyName).build();

s3Client.deleteObject(deleteObjectRequest);

System.out.println(keyName + " has been deleted.");

System.out.println("Deleting bucket: " + bucketName);

DeleteBucketRequest deleteBucketRequest =

DeleteBucketRequest.builder().bucket(bucketName).build();

s3Client.deleteBucket(deleteBucketRequest);

System.out.println(bucketName + " has been deleted.");

System.out.printf("%n");

} catch (S3Exception e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

System.out.println("Cleanup complete");

System.out.printf("%n");

}

Step 4: Build and run the application

After the project is created and contains the complete Handler class, build and run the application.

1. Make sure that you have an active IAM Identity Center session. To do so, run the AWS Command Line

Interface command aws sts get-caller-identity and check the response. If you don't have an

active session, see this section (p. 13) for instructions.

2.

Open a terminal or command prompt window and navigate to your project directory getstarted.

3. Use the following command to build your project:

mvn clean package

4. Use the following command to run the application.

9

AWS SDK for Java 2.x Developer Guide for version 2.x

Success

mvn exec:java -Dexec.mainClass="org.example.App"

To view the new bucket and object that the program creates, perform the following steps.

1.

In Handler.java, comment out the line cleanUp(s3Client, bucket, key) in the

sendRequest method and save the ﬁle.

2.

Rebuild the project by running mvn clean package.

3.

Rerun mvn exec:java -Dexec.mainClass="org.example.App" to upload the text object once

more.

4. Sign in to the S3 console to view the new object in the newly created bucket.

After you view the ﬁle, delete the object, and then delete the bucket.

Success

If your Maven project built and ran without error, then congratulations! You have successfully built your

ﬁrst Java application using the SDK for Java 2.x.

Cleanup

To clean up the resources you created during this tutorial, do the following:

• If you haven't done so already, in the S3 console, delete any objects and any buckets created when you

ran the application.

• In the IAM console, delete the TestSDK user.

If you delete this user, also remove the contents of the credentials ﬁle you created during setup.

•

Delete the project folder (getstarted).

Next steps

Now that you have the basics down, you can learn about the following:

• Working with Amazon S3 (p. 265)

• Working with other Amazon Web Services (p. 185), such as DynamoDB (p. 201), Amazon

EC2 (p. 213), and various database services (p. 200)

• Use the SDK (p. 24)

• Security for the AWS SDK for Java (p. 836)

10

AWS SDK for Java 2.x Developer Guide for version 2.x

Basic setup

Set up the AWS SDK for Java 2.x

The AWS SDK for Java 2.x provides Java APIs for Amazon Web Services (AWS). Using the SDK, you can

build Java applications that work with Amazon S3, Amazon EC2, DynamoDB, and more.

This section provides information about how to set up your development environment and projects to

use the AWS SDK for Java 2.x.

Contents of this chapter

• Basic setup to work with AWS services (p. 11)

• Overview (p. 11)

• Sign-in ability to the AWS access portal (p. 12)

• Set up single sign-on access for the SDK (p. 12)

• Sign in using the AWS CLI (p. 13)

• Install Java and a build tool (p. 13)

• Additional authentication options (p. 13)

• Build tools setup (p. 14)

• Set up an Apache Maven project (p. 14)

• Prerequisites (p. 14)

• Create a Maven project (p. 14)

• Conﬁgure the Java compiler for Maven (p. 14)

• Declare the SDK as a dependency (p. 15)

• Set dependencies for SDK modules (p. 16)

• Build the entire SDK into your project (p. 17)

• Build your project (p. 17)

• Set up a Gradle project (p. 17)

• Set up a GraalVM Native Image project for the AWS SDK for Java (p. 22)

• Prerequisites (p. 22)

• Create a project using the archetype (p. 22)

• Build a native image (p. 23)

Basic setup to work with AWS services

Overview

To successfully develop applications that access AWS services using the AWS SDK for Java, the following

conditions are required:

• You must be able to sign in to the AWS access portal (p. 12) available in the AWS IAM Identity

Center.

• The permissions of the IAM role conﬁgured for the SDK must allow access to the AWS services that

your application requires. The permissions associated with the PowerUserAccess AWS managed policy

are suﬃcient for most development needs.

• A development environment with the following elements:

• Shared conﬁguration ﬁles that are set up in at least one of the following ways:

•

The config ﬁle contains IAM Identity Center single sign-on settings (p. 12) so that the SDK can

get AWS credentials.

11

AWS SDK for Java 2.x Developer Guide for version 2.x

Sign-in ability to the AWS access portal

•

The credentials ﬁle contains temporary credentials.

• An installation of Java 8 (p. 13) or later.

• A build automation tool (p. 13)such as Maven or Gradle.

• A text editor to work with code.

• (Optional, but recommended) An IDE (integrated development environment) such as IntelliJ IDEA,

Eclipse, or NetBeans.

When you use an IDE, you can also integrate AWS Toolkits to more easily work with AWS services.

The AWS Toolkit for IntelliJ and AWS Toolkit for Eclipse are two toolkits that you can use for Java

development.

• An active AWS access portal session when you are ready to run your application. You use the AWS

Command Line Interface to initiate the sign-in process (p. 13) to IAM Identity Center's AWS access

portal.

Important

The instructions in this setup section assume that you or organization uses IAM Identity Center.

If your organization uses an external identity provider that works independently of IAM Identity

Center, ﬁnd out how you can get temporary credentials for the SDK for Java to use. Follow these

instructions (p. 28) to add temporary credentials to the ~/.aws/credentials ﬁle.

If your identity provider adds temporary credentials automatically to the ~/.aws/

credentials ﬁle, make sure that the proﬁle name is [default] so that you do not need to

provide a proﬁle name to the SDK or AWS CLI.

Sign-in ability to the AWS access portal

The AWS access portal is the web location where you manually sign in to the IAM Identity Center. The

format of the URL is d-xxxxxxxxxx.awsapps.com/startor your_subdomain.awsapps.com/

start. If you are not familiar with the AWS access portal, follow the guidance for account access in the

IAM Identity Center authentication topic in the AWS SDKs and Tools Reference Guide.

Set up single sign-on access for the SDK

After you complete Step 2 in the programmatic access section in order for the SDK to use IAM Identity

Center authentication, your system should contain the following elements.

• The AWS CLI, which you use to start an AWS access portal session (p. 13) before you run your

application.

•

An ~/.aws/config ﬁle that contains a default proﬁle. The SDK for Java uses the proﬁle's SSO token

provider conﬁguration to acquire credentials before sending requests to AWS. The sso_role_name

value, which is an IAM role connected to an IAM Identity Center permission set, should allow access to

the AWS services used in your application.

The following sample config ﬁle shows a default proﬁle set up with SSO token provider

conﬁguration. The proﬁle's sso_session setting refers to the named sso-session section. The

sso-session section contains settings to initiate an AWS access portal session.

[default]

sso_session = my-sso

sso_account_id = 111122223333

sso_role_name = SampleRole

region = us-east-1

output = json

12

AWS SDK for Java 2.x Developer Guide for version 2.x

Sign in using the AWS CLI

[sso-session my-sso]

sso_region = us-east-1

sso_start_url = https://provided-domain.awsapps.com/start

sso_registration_scopes = sso:account:access

For more details about the settings used in the SSO token provider conﬁguration, see SSO token provider

conﬁguration in the AWS SDKs and Tools Reference Guide.

If your development environment is not set up for programmatic access as previously shown, follow Step

2 in the SDKs Reference Guide.

Sign in using the AWS CLI

Before running an application that accesses AWS services, you need an active AWS access portal session

in order for the SDK to use IAM Identity Center authentication to resolve credentials. Run the following

command in the AWS CLI to sign in to the AWS access portal.

aws sso login

Since you have a default proﬁle setup, you do not need to call the command with a --profile option.

If your SSO token provider conﬁguration is using a named proﬁle, the command is aws sso login --

profile named-profile.

To test if you already have an active session, run the following AWS CLI command.

aws sts get-caller-identity

The response to this command should report the IAM Identity Center account and permission set

conﬁgured in the shared config ﬁle.

Note

If you already have an active AWS access portal session and run aws sso login, you will not

be required to provide credentials.

However, you will see a dialog that requests permission for botocore to access your

information. botocore is the foundation for the AWS CLI .

Select Allow to authorize access to your information for the AWS CLI and SDK for Java.

Install Java and a build tool

Your development environment needs the following:

• Java 8 or later. The AWS SDK for Java works with the Oracle Java SE Development Kit and with

distributions of Open Java Development Kit (OpenJDK) such as Amazon Corretto, Red Hat OpenJDK,

and AdoptOpenJDK.

• A build tool or IDE that supports Maven Central such as Apache Maven, Gradle, or IntelliJ.

• For information about how to install and use Maven, see http://maven.apache.org/.

• For information about how to install and use Gradle, see https://gradle.org/.

• For information about how to install and use IntelliJ IDEA, see https://www.jetbrains.com/idea/.

Additional authentication options

For more options on authentication for the SDK, such as the use of proﬁles and environment variables,

see the conﬁguration chapter in the AWS SDKs and Tools Reference Guide.

13

AWS SDK for Java 2.x Developer Guide for version 2.x

Build tools setup

Set up an Apache Maven project

You can use Apache Maven to set up and build AWS SDK for Java projects, or to build the SDK itself.

Prerequisites

To use the AWS SDK for Java with Maven, you need the following:

• Java 8.0 or later. You can download the latest Java SE Development Kit software from http://

www.oracle.com/technetwork/java/javase/downloads/. The AWS SDK for Java also works with

OpenJDK and Amazon Corretto, a distribution of the Open Java Development Kit (OpenJDK).

Download the latest OpenJDK version from https://openjdk.java.net/install/index.html. Download the

latest Amazon Corretto 8 or Amazon Corretto 11 version from the Corretto page.

• Apache Maven. If you need to install Maven, go to http://maven.apache.org/ to download and install

it.

Create a Maven project

To create a Maven project from the command line, run the following command from a terminal or

command prompt window.

mvn -B archetype:generate \

-DarchetypeGroupId=software.amazon.awssdk \

-DarchetypeArtifactId=archetype-lambda -Dservice=s3 -Dregion=US_WEST_2 \

-DarchetypeVersion=2.X.X \

-DgroupId=com.example.myapp \

-DartifactId=myapp

Note

Replace com.example.myapp with the full package namespace of your application. Also replace

myapp with your project name. This becomes the name of the directory for your project.

To use the latest version of the archetype, replace 2.X.X with the latest from Maven central.

This command creates a Maven project using the archetype templating toolkit. The archetype generates

the scaﬀolding for an AWS Lambda function handler project . This project archetype is preconﬁgured to

compile with Java SE 8 and includes a dependency to the version of the SDK for Java 2.x speciﬁed with -

DarchetypeVersion.

For more information about creating and conﬁguring Maven projects, see the Maven Getting Started

Guide.

Conﬁgure the Java compiler for Maven

If you created your project using the AWS Lambda project archetype as described previously, the

conﬁguration of the Java compiler is already done for you.

To verify that this conﬁguration is present, start by opening the pom.xml ﬁle from the project folder

you created (for example, myapp) when you executed the previous command. Look on lines 11 and 12

to see the Java compiler version setting for this Maven project, and the required inclusion of the Maven

compiler plugin on lines 71-75.

14

AWS SDK for Java 2.x Developer Guide for version 2.x

Set up an Apache Maven project

<maven.compiler.source>1.8</maven.compiler.source>

<maven.compiler.target>1.8</maven.compiler.target>

</properties>

<build>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>

<version>${maven.compiler.plugin.version}</version>

</plugin>

</plugins>

</build>

</project>

If you create your project with a diﬀerent archetype or by using another method, you must ensure that

the Maven compiler plugin is part of the build and that its source and target properties are both set to

1.8 in the pom.xml ﬁle.

See the previous snippet for one way to conﬁgure these required settings.

Alternatively, you can conﬁgure the compiler conﬁguration inline with the plugin declaration, as follows.

<build>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>

</configuration>

</plugin>

</plugins>

</build>

</project>

Declare the SDK as a dependency

To use the AWS SDK for Java in your project, you need to declare it as a dependency in your project’s

pom.xml ﬁle.

If you created your project using the project archetype as described previously, the latest version of the

SDK is already conﬁgured as a dependency in your project.

The archetype generates a BOM (bill of materials) artifact dependency for the

software.amazon.awssdk group id. With a BOM, you do not have to specify the maven version for

individual artifact dependencies that share the same group id.

If you created your Maven project in a diﬀerent way, conﬁgure the latest version of the SDK for your

project by ensuring that the pom.xml ﬁle contains the following.

<aws.java.sdk.version>2.X.X</aws.java.sdk.version>

</properties>

<groupId>software.amazon.awssdk</groupId>

15

AWS SDK for Java 2.x Developer Guide for version 2.x

Set up an Apache Maven project

<version>${aws.java.sdk.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

</project>

Note

Replace 2.X.X in the pom.xml ﬁle with the latest version of the AWS SDK for Java 2.x.

Set dependencies for SDK modules

Now that you have conﬁgured the SDK, you can add dependencies for one or more of the AWS SDK for

Java modules to use in your project.

Although you can specify the version number for each component, you don’t need to because you

already declared the SDK version in the dependencyManagement section using the bill of materials

artifact. To load a diﬀerent version of a given module, specify a version number for its dependency.

If you created your project using the project archetype as described previously, your project is already

conﬁgured with multiple dependencies. These include dependences for AWS Lambda function handlers

and Amazon S3, as follows.

<groupId>software.amazon.awssdk</groupId>

<groupId>software.amazon.awssdk</groupId>

<artifactId>netty-nio-client</artifactId>

</exclusion>

<groupId>software.amazon.awssdk</groupId>

<artifactId>apache-client</artifactId>

</exclusion>

</exclusions>

</dependency>

<groupId>software.amazon.awssdk</groupId>

<artifactId>url-connection-client</artifactId>

</dependency>

<groupId>com.amazonaws</groupId>

<artifactId>aws-lambda-java-core</artifactId>

<version>${aws.lambda.java.version}</version>

</dependency>

</dependencies>

</project>

Note

In the pom.xml example above, the dependencies are from diﬀerent groupIds. The s3

dependency is from software.amazon.awssdk, whereas the aws-lambda-java-core

dependency is from com.amazonaws. The BOM dependency management conﬁguration aﬀects

artifacts for software.amazon.awssdk, so a version is needed for the aws-lambda-java-

core artifact.

16

AWS SDK for Java 2.x Developer Guide for version 2.x

Set up a Gradle project

For the development of Lambda function handlers using the SDK for Java 2.x, aws-lambda-

java-core is the correct dependency. However, if your application needs to manage Lambda

resources, using operations such as listFunctions, deleteFunction, invokeFunction,

and createFunction, your application requires the following dependency.

<groupId>software.amazon.awssdk</groupId>

<artifactId>lambda</artifactId>

Note

The s3 dependency excludes the the netty-nio-client and apache-client transitive

dependencies. In place of either of those HTTP clients, the archetype includes the url-

connection-client dependency, which helps reduce the startup latency for AWS Lambda

functions (p. 40).

Add the modules to your project for the AWS service and features you need for your project. The

modules (dependencies) that are managed by the AWS SDK for Java BOM are listed on the Maven central

repository.

Note

You can look at the pom.xml ﬁle from a code example to determine which dependencies you

need for your project. For example, if you’re interested in the dependencies for the DynamoDB

service, see this example from the AWS Code Examples Repository on GitHub. (Look for the

pom.xml ﬁle under /javav2/example_code/dynamodb.)

Build the entire SDK into your project

To optimize your application, we strongly recommend that you pull in only the components you need

instead of the entire SDK. However, to build the entire AWS SDK for Java into your project, declare it in

your pom.xml ﬁle, as follows.

<groupId>software.amazon.awssdk</groupId>

</dependency>

</dependencies>

</project>

Build your project

After you conﬁgure the pom.xml ﬁle, you can use Maven to build your project.

To build your Maven project from the command line, open a terminal or command prompt window,

navigate to your project directory (for example, myapp), enter or paste the following command, then

press Enter or Return.

mvn package

This creates a single .jar ﬁle (JAR) in the target directory (for example, myapp/target). This JAR

contains all of the SDK modules you speciﬁed as dependencies in your pom.xml ﬁle.

Set up a Gradle project

You can use Gradle to set up and build AWS SDK for Java projects.

17

AWS SDK for Java 2.x Developer Guide for version 2.x

Set up a Gradle project

The initial steps in the following example come from Gradle's Getting Started guide for version 8.4. If

you use a diﬀerent version, your results may diﬀer slightly.

To create a Java application with Gradle (command line)

1.

Create a directory to hold your project. In this example, demo is the directory name.

2.

Inside the demo directory, execute the gradle init command and supply the values highlighted in

red as shown in the following command line output. For the walk through, we choose Kotlin as the

build script DSL language, but a complete example for Groovy is also shown at the end of this topic.

> gradle init

Starting a Gradle Daemon (subsequent builds will be faster)

Select type of project to generate:

1: basic

2: application

3: library

4: Gradle plugin

Enter selection (default: basic) [1..4] 2

Select implementation language:

1: C++

2: Groovy

3: Java

4: Kotlin

5: Scala

6: Swift

Enter selection (default: Java) [1..6] 3

Generate multiple subprojects for application? (default: no) [yes, no] no

Select build script DSL:

1: Kotlin

2: Groovy

Enter selection (default: Kotlin) [1..2] <Enter>

Select test framework:

1: JUnit 4

2: TestNG

3: Spock

4: JUnit Jupiter

Enter selection (default: JUnit Jupiter) [1..4] 4

Project name (default: demo): <Enter>

Source package (default: demo): <Enter>

Enter target version of Java (min. 7) (default: 11): <Enter>

Generate build using new APIs and behavior (some features may change in the next minor

release)? (default: no) [yes, no] <Enter>

> Task :init

To learn more about Gradle by exploring our Samples at https://docs.gradle.org/8.4/

samples/sample_building_java_applications.html

BUILD SUCCESSFUL in 3m 43s

2 actionable tasks: 2 executed

3.

After the init task completes, the demo directory contains the following tree structure. We take a

closer look at the main build ﬁle, build.gradle.kts (highlighted in red), in the next section.

### app

# ### build.gradle.kts

# ### src

# ### main

# # ### java

18

AWS SDK for Java 2.x Developer Guide for version 2.x

Set up a Gradle project

# # # ### demo

# # # ### App.java

# # ### resources

# ### test

# ### java

# # ### demo

# # ### AppTest.java

# ### resources

### gradle

# ### wrapper

# ### gradle-wrapper.jar

# ### gradle-wrapper.properties

### gradlew

### gradlew.bat

### settings.gradle.kts

The build.gradle.kts ﬁle contains the following scaﬀolded content.

/*

* This file was generated by the Gradle 'init' task.

*

* This generated file contains a sample Java application project to get you started.

* For more details on building Java & JVM projects, please refer to https://

docs.gradle.org/8.4/userguide/building_java_projects.html in the Gradle documentation.

*/

plugins {

// Apply the application plugin to add support for building a CLI application in

Java.

application

}

repositories {

// Use Maven Central for resolving dependencies.

mavenCentral()

}

dependencies {

// Use JUnit Jupiter for testing.

testImplementation("org.junit.jupiter:junit-jupiter:5.9.3")

testRuntimeOnly("org.junit.platform:junit-platform-launcher")

// This dependency is used by the application.

implementation("com.google.guava:guava:32.1.1-jre")

}

// Apply a specific Java toolchain to ease working on different environments.

java {

toolchain {

languageVersion.set(JavaLanguageVersion.of(11))

}

application {

// Define the main class for the application.

mainClass.set("demo.App")

}

tasks.named<Test>("test") {

// Use JUnit Platform for unit tests.

useJUnitPlatform()

}

19

AWS SDK for Java 2.x Developer Guide for version 2.x

Set up a Gradle project

4. Use the scaﬀolded Gradle build ﬁle as the basis for your AWS project.

a. To manage SDK dependencies for your Gradle project, add the Maven bill of materials (BOM) for

the AWS SDK for Java 2.x to the dependencies section of the build.gradle.kts ﬁle.

...

dependencies {

implementation(platform("software.amazon.awssdk:bom:2.21.1"))

// With the bom declared, you specify individual SDK dependencies without a

version.

...

}

...

Note

In this example build ﬁle, replace 2.21.1 with the latest version of the SDK for Java 2.x.

Find the latest version available in Maven central repository.

b.

Specify the SDK modules your application needs in the dependencies section. As an example,

the following adds a dependency on Amazon Simple Storage Service.

...

dependencies {

implementation(platform("software.amazon.awssdk:bom:2.21.1"))

implementation("software.amazon.awssdk:s3")

...

}

...

Gradle automatically resolves the correct version of declared dependencies by using the

information from the BOM.

The following examples show complete Gradle build ﬁles in both the Kotlin and Groovy DSLs. The build

ﬁle contains dependencies for Amazon S3, authentication, logging, and testing. The source and target

version of Java is version 11.

Kotlin DSL (build.gradle.kts)

/*

* This file was generated by the Gradle 'init' task.

*

* This generated file contains a sample Java application project to get you started.

* For more details on building Java & JVM projects, please refer to https://

docs.gradle.org/8.4/userguide/building_java_projects.html in the Gradle documentation.

*/

plugins {

// Apply the application plugin to add support for building a CLI application in

Java.

application

}

repositories {

// Use Maven Central for resolving dependencies.

mavenCentral()

}

dependencies {

implementation(platform("software.amazon.awssdk:bom:2.20.56"))

implementation("software.amazon.awssdk:s3")

implementation("software.amazon.awssdk:sso")

20

AWS SDK for Java 2.x Developer Guide for version 2.x

Set up a Gradle project

implementation("software.amazon.awssdk:ssooidc")

implementation(platform("org.apache.logging.log4j:log4j-bom:2.20.0"))

implementation("org.apache.logging.log4j:log4j-slf4j2-impl")

implementation("org.apache.logging.log4j:log4j-1.2-api")

testImplementation(platform("org.junit:junit-bom:5.10.0"))

testImplementation("org.junit.jupiter:junit-jupiter")

}

// Apply a specific Java toolchain to ease working on different environments.

java {

toolchain {

languageVersion.set(JavaLanguageVersion.of(11))

}

application {

// Define the main class for the application.

mainClass.set("demo.App")

}

tasks.named<Test>("test") {

// Use JUnit Platform for unit tests.

useJUnitPlatform()

}

Groovy DSL (build.gradle)

/*

* This file was generated by the Gradle 'init' task.

*

* This generated file contains a sample Java application project to get you started.

* For more details on building Java & JVM projects, please refer to https://

docs.gradle.org/8.4/userguide/building_java_projects.html in the Gradle documentation.

*/

plugins {

// Apply the application plugin to add support for building a CLI application in

Java.

id 'application'

}

repositories {

// Use Maven Central for resolving dependencies.

mavenCentral()

}

dependencies {

implementation platform('software.amazon.awssdk:bom:2.21.1')

implementation 'software.amazon.awssdk:s3'

implementation 'software.amazon.awssdk:sso'

implementation 'software.amazon.awssdk:ssooidc'

implementation platform('org.apache.logging.log4j:log4j-bom:2.20.0')

implementation 'org.apache.logging.log4j:log4j-slf4j2-impl'

implementation 'org.apache.logging.log4j:log4j-1.2-api'

testImplementation platform('org.junit:junit-bom:5.10.0')

testImplementation 'org.junit.jupiter:junit-jupiter'

}

// Apply a specific Java toolchain to ease working on different environments.

java {

toolchain {

languageVersion = JavaLanguageVersion.of(11)

}

21

AWS SDK for Java 2.x Developer Guide for version 2.x

Set up a GraalVM Native Image project

application {

// Define the main class for the application.

mainClass = 'demo_groovy.App'

}

tasks.named('test') {

// Use JUnit Platform for unit tests.

useJUnitPlatform()

}

For next steps, see the Getting Started guide on the Gradle website for instructions on how to build and

run a Gradle application.

Set up a GraalVM Native Image project for the

AWS SDK for Java

With versions 2.16.1 and later, the AWS SDK for Java provides out-of-the-box support for GraalVM

Native Image applications. Use the archetype-app-quickstart Maven archetype to set up a project

with built-in native image support.

Prerequisites

• Complete the steps in Setting up the AWS SDK for Java 2.x (p. 11).

• Install GraalVM Native Image.

Create a project using the archetype

To create a Maven project with built-in native image support, in a terminal or command prompt window,

use the following command.

Note

Replace com.example.mynativeimageapp with the full package namespace of your

application. Also replace mynativeimageapp with your project name. This becomes the name

of the directory for your project.

mvn archetype:generate \

-DarchetypeGroupId=software.amazon.awssdk \

-DarchetypeArtifactId=archetype-app-quickstart \

-DarchetypeVersion=2.16.1 \

-DnativeImage=true \

-DhttpClient=apache-client \

-Dservice=s3 \

-DgroupId=com.example.mynativeimageapp \

-DartifactId=mynativeimageapp \

-DinteractiveMode=false

This command creates a Maven project conﬁgured with dependencies for the AWS SDK for Java, Amazon

S3, and the ApacheHttpClient HTTP client. It also includes a dependency for the GraalVM Native

Image Maven plugin, so that you can build native images using Maven.

To include dependencies for a diﬀerent Amazon Web Services, set the value of the -Dservice

parameter to the artifact ID of that service. Examples include dynamodb, comprehend, and pinpoint.

22

AWS SDK for Java 2.x Developer Guide for version 2.x

Build a native image

For a complete list of artifact IDs, see the list of managed dependencies for software.amazon.awssdk on

Maven Central.

To use an asynchronous HTTP client, set the -DhttpClient parameter to netty-nio-client. To use

UrlConnectionHttpClient as the synchronous HTTP client instead of apache-client, set the -

DhttpClient parameter to url-connection-client.

Build a native image

After you create the project, run the following command from your project directory, for example,

mynativeimageapp:

mvn package -P native-image

This creates a native image application in the target directory, for example, target/

mynativeimageapp.

23

AWS SDK for Java 2.x Developer Guide for version 2.x

Work with service clients

Use the AWS SDK for Java 2.x

After completing the steps in Setting up the SDK (p. 11), you are ready to make requests to AWS services

such as Amazon S3, DynamoDB, IAM, Amazon EC2, and more.

Work with service clients

Create a service client

To make a request to an AWS service, you must ﬁrst instantiate a service client for that service by using

the static factory method, builder(). The builder() method returns a builder object that allows

you to customize the service client. The ﬂuent setter methods return the builder object, so that

you can chain the method calls for convenience and for more readable code. After you conﬁgure the

properties you want, call the build() method to create the client.

As an example, the following code snippet instantiates an Ec2Client object as a service client for

Amazon EC2.

Region region = Region.US_WEST_2;

Ec2Client ec2Client = Ec2Client.builder()

.region(region)

.build();

Note

Service clients in the SDK are thread-safe. For best performance, treat them as long-lived

objects. Each client has its own connection pool resource that is released when the client is

garbage collected.

A service client object is immutable, so you must create a new client for each service to which

you make requests, or if you want to use a diﬀerent conﬁguration for making requests to the

same service.

Specifying the Region in the service client builder is not required for all AWS services; however,

it is a best practice to set the Region for the API calls you make in your applications. See AWS

region selection (p. 38) for more information.

Default client conﬁguration

The client builders have another factory method named create(). This method creates a service client

with the default conﬁguration. It uses the default provider chain to load credentials and the AWS Region.

If credentials or the Region can’t be determined from the environment that the application is running

in, the call to create fails. See Using credentials (p. 28) and Region selection (p. 38) for more

information about how the SDK determines the credentials and Region to use.

For example, the following code snippet instantiates a DynamoDbClient object as a service client for

Amazon DynamoDB:

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

Conﬁgure service clients

To customize the conﬁguration of a service client, use the setters on the builder() factory method. For

convenience and to create more readable code, chain the methods to set multiple conﬁguration options.

24

AWS SDK for Java 2.x Developer Guide for version 2.x

Make requests

The following example shows an S3Client that is conﬁgured with several custom settings.

ClientOverrideConfiguration clientOverrideConfiguration =

ClientOverrideConfiguration.builder()

.apiCallAttemptTimeout(Duration.ofSeconds(1))

.retryPolicy(RetryPolicy.builder().numRetries(10).build())

.addMetricPublisher(CloudWatchMetricPublisher.create())

.build();

Region region = Region.US_WEST_2;

S3Client s3Client = S3Client.builder()

.region(region)

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.overrideConfiguration(clientOverrideConfiguration)

.httpClientBuilder(ApacheHttpClient.builder()

.proxyConfiguration(proxyConfig.build(ProxyConfiguration.builder()))

.build())

.build();

Make requests

Use the service client to make requests to the corresponding AWS service.

For example, this code snippet shows how to create a RunInstancesRequest object to create a new

Amazon EC2 instance:

// Create the request by using the fluid setter methods of the request builder.

RunInstancesRequest runInstancesRequest = RunInstancesRequest.builder()

.imageId(amiId)

.instanceType(InstanceType.T1_MICRO)

.maxCount(1)

.minCount(1)

.build();

// Use the configured request with the service client.

ec2Client.runInstances(runInstancesRequest);

Handle responses

You use a response handler to process the response back from the AWS service.

For example, this code snippet shows how to create a RunInstancesResponse object to handle the

response from Amazon EC2 by printing out the instanceId for the new instance from the request

above:

RunInstancesResponse runInstancesResponse = ec2Client.runInstances(runInstancesRequest);

System.out.println(runInstancesResponse.instances().get(0).instanceId());

Close the service client

As a best practice, you should use a service clients for multiple API service calls during the life of an

application. However, if you need a service client for a one-time use or no longer need the service client,

close it.

Call the close() method when the service client is no longer needed to free up resources.

25

AWS SDK for Java 2.x Developer Guide for version 2.x

Handle exceptions

ec2Client.close();

If you need a service client for one-time use, you can instantiate the service client as a resource in a

try-with-resources statement. Service clients implement the Autoclosable interface, so the JDK

automatically calls the close() method at the end of the statement.

The following example demonstrates how to use a service client for a one-oﬀ call. The StsClient that

calls the AWS Security Token Service is closed after it returns the account ID.

import software.amazon.awssdk.services.sts.StsClient;

String getAccountID() {

try (StsClient stsClient = StsClient.create()) {

return stsClient.getCallerIdentity().account();

}

Handle exceptions

The SDK uses runtime (or unchecked) exceptions, providing you ﬁne-grained control over error handling

and ensuring that exception handling will scale with your application.

An SdkServiceException, or one of its sub-classes, is the most common form of exception the

SDK will throw. These exceptions represent responses from the AWS service. You can also handle

an SdkClientException, which occurs when there’s a problem on the client side (i.e., in your

development or application environment), such a network connection failure.

This code snippet demonstrates one way to handle service exceptions when you upload a ﬁle to

Amazon S3. The example code catches both client and server exceptions, logs the details, and exists the

application.

Region region = Region.US_WEST_2;

s3Client = S3Client.builder()

.region(region)

.build();

try {

PutObjectRequest putObjectRequest = PutObjectRequest.builder()

.bucket(bucketName)

.key(key)

.build();

s3Client.putObject(putObjectRequest, RequestBody.fromString("SDK for Java test"));

} catch (S3Exception se) {

System.err.println("Service exception thrown.");

System.err.println(se.awsErrorDetails().errorMessage());

} catch (SdkClientExeption ce){

System.err.println("Client exception thrown.");

System.err.println(ce.getMessage());

} finally {

System.exit(1);

}

See Handling exceptions (p. 64) for more information.

26

AWS SDK for Java 2.x Developer Guide for version 2.x

Use waiters

Some requests take time to process, such as creating a new table in DynamoDB or creating a new

Amazon S3 bucket. To ensure the resource is ready before your code continues to run, use a Waiter.

For example, this code snippet creates a new table ("myTable") in DynamoDB, waits for the table to be in

an ACTIVE status, and then prints out the response:

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

DynamoDbWaiter dynamoDbWaiter = dynamoDbClient.waiter();

WaiterResponse<DescribeTableResponse> waiterResponse =

dynamoDbWaiter.waitUntilTableExists(r -> r.tableName("myTable"));

waiterResponse.matched().response().ifPresent(System.out::println);

See Using waiters (p. 177) for more information.

HTTP clients

You can change the default conﬁguration for HTTP clients in applications you build with the

AWS SDK for Java. For information on how to conﬁgure HTTP clients and settings, see HTTP

conﬁguration (p. 44).

Retries

You can change the default settings for retries in your service clients, including the retry mode and

back-oﬀ strategy. For more information, refer to the RetryPolicy class in the AWS SDK for Java API

Reference.

For more information about retries in AWS services, see Error retries and exponential backoﬀ in AWS.

Timeouts

You can conﬁgure timeouts for each of your service clients using the apiCallTimeout and the

apiCallAttemptTimeout setters. The apiCallTimeout setting is the amount of time to allow the

client to complete the execution of an API call. The apiCallAttemptTimeout setting is the amount of

time to wait for the HTTP request to complete before giving up.

For more information, see apiCallTimeout and apiCallAttemptTimeout in the AWS SDK for Java

API Reference.

Execution interceptors

You can write code that intercepts the execution of your API requests and responses at diﬀerent parts

of the request/response lifecycle. This enables you to publish metrics, modify a request in-ﬂight, debug

request processing, view exceptions, and more. For more information, see the ExecutionInterceptor

interface in the AWS SDK for Java API Reference.

27

AWS SDK for Java 2.x Developer Guide for version 2.x

Additional information

• For complete examples of the code snippets above, see Working with Amazon DynamoDB (p. 201),

Working with Amazon EC2 (p. 213), and Working with Amazon S3 (p. 265).

Provide temporary credentials to the SDK

Before making a request to Amazon Web Services using the AWS SDK for Java 2.x, the SDK

cryptographically signs temporary credentials issued by AWS. To access temporary credentials, the SDK

retrieves conﬁguration values by checking several locations.

This topic discusses several ways that you enable to SDK to access temporary credentials.

Topics

• Use temporary credentials (p. 28)

• Default credentials provider chain (p. 29)

• Use a speciﬁc credentials provider or provider chain (p. 30)

• Use proﬁles (p. 31)

• Load temporary credentials from an external process (p. 33)

• Supply temporary credentials in code (p. 35)

• Conﬁgure IAM roles for Amazon EC2 (p. 37)

Use temporary credentials

For increased security, AWS recommends that you conﬁgure the SDK for Java to use temporary

credentials instead of long-lived credentials. Temporary credentials consist of access keys (access key

id and secret access key) and a session token. We recommend that you conﬁgure the SDK (p. 28) to

automatically get temporary credentials, since the token refresh process is automatic. You can, however,

provide the SDK with temporary credentials (p. 28) directly.

IAM Identity Center conﬁguration

When you conﬁgure the SDK to use IAM Identity Center single sign-on access as described in the section

called “Basic setup” (p. 11) in this guide, the SDK automatically uses temporary credentials.

The SDK uses the IAM Identity Center access token to gain access to the IAM role that is conﬁgured with

the sso_role_name setting in your config ﬁle. The SDK assumes this IAM role and retrieves temporary

credentials to use for AWS service requests.

For more details about how the SDK gets temporary credentials from the conﬁguration, see the

Understanding IAM Identity Center authentication section of the AWS SDKs and Tools Reference Guide.

Retrieve from AWS access portal

As an alternative to IAM Identity Center single sign-on conﬁguration, you can copy and use temporary

credentials available in the AWS access portal. You can use the temporary credentials in a proﬁle or use

them as values for system properties and environment variables.

Set up a local credentials ﬁle for temporary credentials

1. Create a shared credentials ﬁle

28

AWS SDK for Java 2.x Developer Guide for version 2.x

Default credentials provider chain

2. In the credentials ﬁle, paste the following placeholder text until you paste in working temporary

credentials.

[default]

aws_access_key_id=<value from AWS access portal>

aws_secret_access_key=<value from AWS access portal>

aws_session_token=<value from AWS access portal>

3.

Save the ﬁle. The ﬁle ~/.aws/credentials should now exist on your local development system.

This ﬁle contains the [default] proﬁle that the SDK for Java uses if a speciﬁc named proﬁle is not

speciﬁed.

4. Sign in to the AWS access portal

5. Follow these instructions under the Manual credential refresh heading to copy IAM role credentials

from the AWS access portal.

a. For step 4 in the linked instructions, choose the IAM role name that grants access for your

development needs. This role typically has a name like PowerUserAccess or Developer.

b. For step 7, select the Manually add a proﬁle to your AWS credentials ﬁle option and copy the

contents.

6.

Paste the copied credentials into your local credentials ﬁle and remove the generated proﬁle

name. Your ﬁle should resemble the following.

[default]

aws_access_key_id=AKIAIOSFODNN7EXAMPLE

aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE

7.

Save the credentials ﬁle.

When the SDK for Java creates a service client, it will access these temporary credentials and use them

for each request. The settings for the IAM role chosen in step 5a determine how long the temporary

credentials are valid. The maximum duration is twelve hours.

After the temporary credentials expire, repeat steps 4 through 7.

Default credentials provider chain

The default credentials provider chain is implemented by the DefaultCredentialsProvider class. It

sequentially checks each place where you can set the default conﬁguration for supplying temporary

credentials, and then selects the ﬁrst one you set.

To use the default credentials provider chain to supply temporary credentials that are used in your

application, create a service client builder but don't specify a credentials provider. The following code

snippet creates a DynamoDbEnhancedClient that uses the default credentials provider chain to locate

and retrieve default conﬁguration settings.

Region region = Region.US_WEST_2;

DynamoDbEnhancedClient ddb =

DynamoDbEnhancedClient.builder()

.region(region)

.build();

Credential settings retrieval order

The default credentials provider chain of the SDK for Java 2.x searches for conﬁguration in your

environment using a predeﬁned sequence.

29

AWS SDK for Java 2.x Developer Guide for version 2.x

Use a speciﬁc credentials provider or provider chain

1. Java system properties

• The SDK uses the SystemPropertyCredentialsProvider class to load temporary credentials from the

aws.accessKeyId, aws.secretAccessKey, and aws.sessionToken Java system properties.

Note

For information on how to set Java system properties, see the System Properties tutorial on

the oﬃcial Java Tutorials website.

2. Environment variables

• The SDK uses the EnvironmentVariableCredentialsProvider class to load temporary credentials from

the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment

variables.

3. Web identity token from AWS Security Token Service

• The SDK uses the WebIdentityTokenFileCredentialsProvider class to load temporary credentials

from Java system properties or environment variables.

4.

The shared credentials and config ﬁles

• The SDK uses the ProﬁleCredentialsProvider to load IAM Identity Center single sign-on settings or

temporary credentials from the [default] proﬁle in the shared credentials and config ﬁles.

The AWS SDKs and Tools Reference Guide has detailed information about how the SDK for Java

works with the IAM Identity Center single sign-on token to get temporary credentials that the SDK

uses to call AWS services.

Note

The credentials and config ﬁles are shared by various AWS SDKs and Tools. For more

information, see The .aws/credentials and .aws/conﬁg ﬁles in the AWS SDKs and Tools

Reference Guide.

5. Amazon ECS container credentials

• The SDK uses the ContainerCredentialsProvider class to load temporary credentials from the

AWS_CONTAINER_CREDENTIALS_RELATIVE_URI system environment variable.

6. Amazon EC2 instance IAM role-provided credentials

• The SDK uses the InstanceProﬁleCredentialsProvider class to load temporary credentials from the

Amazon EC2 metadata service.

Use a speciﬁc credentials provider or provider chain

As an alternative to the default credentials provider chain, you can specify which credentials provider the

SDK should use. When you supply a speciﬁc credentials provider, the SDK skips the process of checking

various locations, which slightly reduces the time to create a service client.

For example, if you set your default conﬁguration using environment variables, supply an

EnvironmentVariableCredentialsProvider object to the credentialsProvider method on the service

client builder, as in the following code snippet.

Region region = Region.US_WEST_2;

DynamoDbClient ddb = DynamoDbClient.builder()

.region(region)

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.build();

For a complete list of credential providers and provider chains, see All Known Implementing Classes in

AwsCredentialsProvider.

Note

You can use your own credentials provider or provider chains by implementing the

AwsCredentialsProvider interface.

30

AWS SDK for Java 2.x Developer Guide for version 2.x

Use proﬁles

Using the shared config and credentials ﬁle, you can set up several proﬁles. This enables your

application to use multiple sets of credentials conﬁguration. The [default] proﬁle was mentioned

previously. The SDK uses the ProﬁleCredentialsProvider class to load settings from proﬁles deﬁned in the

shared credentials ﬁle.

The following code snippet demonstrates how to build a service client that uses the settings deﬁned as

part of the proﬁle named my_profile.

Region region = Region.US_WEST_2;

DynamoDbClient ddb = DynamoDbClient.builder()

.region(region)

.credentialsProvider(ProfileCredentialsProvider.create("my_profile"))

.build();

Set a diﬀerent proﬁle as the default

To set a proﬁle other than the [default] proﬁle as the default for your application, set the

AWS_PROFILE environment variable to the name of your custom proﬁle.

To set this variable on Linux, macOS, or Unix, use export:

export AWS_PROFILE="other_profile"

To set these variables on Windows, use set:

set AWS_PROFILE="other_profile"

Alternatively, set the aws.profile Java system property to the name of the proﬁle.

Reload proﬁle credentials

You can conﬁgure any credentials provider that has a profileFile() method on its builder to

reload proﬁle credentials. These credentials proﬁle classes are: ProfileCredentialsProvider,

DefaultCredentialsProvider, InstanceProfileCredentialsProvider, and

ProfileTokenProvider.

Note

Proﬁle credential reloading works only with the following settings in the proﬁle ﬁle :

aws_access_key_id, aws_secret_access_key, and aws_session_token.

Settings such as region, sso_session, sso_account_id, and source_profile are

ignored.

To conﬁgure a supported credentials provider to reload proﬁle settings, provide an instance of

ProfileFileSupplier to the profileFile() builder method. The following code example

demonstrates a ProfileCredentialsProvider that reloads credential settings from the [default]

proﬁle.

ProfileCredentialsProvider provider = ProfileCredentialsProvider

.builder()

.profileFile(ProfileFileSupplier.defaultSupplier())

.build();

// Set up a service client with the provider instance.

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()

.region(Region.US_EAST_1)

31

AWS SDK for Java 2.x Developer Guide for version 2.x

Use proﬁles

.credentialsProvider(provider)

.build();

/*

Before dynamoDbClient makes a request, it reloads the credentials settings

by calling provider.resolveCredentials().

*/

When ProfileCredentialsProvider.resolveCredentials() is called, the SDK for Java

reloads the settings. ProfileFileSupplier.defaultSupplier() is one of several convenience

implementations of ProfileFileSupplier provided by the SDK. If your use case requires, you can

provide your own implementation.

The following example shows the use of the ProfileFileSupplier.reloadWhenModified()

convenience method. reloadWhenModified() takes a Path parameter, which gives you ﬂexibility in

designating the source ﬁle for the conﬁguration rather than the standard ~/.aws/credentials (or

config) location.

The settings will be reloaded when resolveCredentials() is called only if SDK determines the ﬁle's

content has been modiﬁed.

Path credentialsFilePath = ...

ProfileCredentialsProvider provider = ProfileCredentialsProvider

.builder()

.profileFile(ProfileFileSupplier.reloadWhenModified(credentialsFilePath,

ProfileFile.Type.CREDENTIALS))

.profileName("my-profile")

.build();

/*

A service client configured with the provider instance calls

provider.resolveCredential()

before each request.

*/

The ProfileFileSupplier.aggregate() method merges the contents of multiple conﬁguration

ﬁles. You decide whether a ﬁle is reloaded per call to resolveCredentials() or a ﬁle's settings are

ﬁxed at the time it was ﬁrst read.

The following example shows a DefaultCredentialsProvider that merges the settings of

two ﬁles that contain proﬁle settings. The SDK reloads the settings in the ﬁle pointed to by the

credentialsFilePath variable each time resolveCredentials() is called and the settings have

changed. The settings from the profileFile object remain the same.

Path credentialsFilePath = ...;

ProfileFile profileFile = ...;

DefaultCredentialsProvider provider = DefaultCredentialsProvider

.builder()

.profileFile(ProfileFileSupplier.aggregate(

ProfileFileSupplier.reloadWhenModified(credentialsFilePath,

ProfileFile.Type.CREDENTIALS),

ProfileFileSupplier.fixedProfileFile(profileFile)))

.profileName("my-profile")

.build();

/*

A service client configured with the provider instance calls

provider.resolveCredential()

before each request.

*/

32

AWS SDK for Java 2.x Developer Guide for version 2.x

Load temporary credentials from an external process

Warning

The following describes a method of sourcing temporary credentials from an external process.

This can potentially be dangerous, so proceed with caution. Other credential providers should be

preferred if at all possible. If using this option, you should make sure that the config ﬁle is as

locked down as possible using security best practices for your operating system.

Make sure that your custom credentials tool does not write any secret information to StdErr.

SDKs and AWS CLI can capture and log such information, potentially exposing it to unauthorized

users.

With the SDK for Java 2.x, you can acquire temporary credentials from an external process for custom

use cases. There are two ways to conﬁgure this functionality.

Use the credential_process setting

If you have a method that provides temporary credentials, you can integrate it by adding the

credential_process setting as part of a proﬁle deﬁnition in the config ﬁle. The value you specify

must use the full path to the command ﬁle. If the ﬁle path contains any spaces, you must surround it

with quotation marks.

The SDK calls the command exactly as given and then reads JSON data from stdout.

The following examples show the use of this setting for ﬁle paths without spaces and ﬁle paths with

spaces.

Linux/macOS

No spaces in ﬁle path

[profile process-credential-profile]

credential_process = /path/to/credential/file/credential_file.sh --custom-command

custom_parameter

Spaces in ﬁle path

[profile process-credential-profile]

credential_process = "/path/with/space to/credential/file/credential_file.sh" --

custom-command custom_parameter

Windows

No spaces in ﬁle path

[profile process-credential-profile]

credential_process = C:\Path\To\credentials.cmd --custom_command custom_parameter

Spaces in ﬁle path

[profile process-credential-profile]

credential_process = "C:\Path\With Space To\credentials.cmd" --custom_command

custom_parameter

The following code snippet demonstrates how to build a service client that uses the temporary

credentials deﬁned as part of the proﬁle named process-credential-profile.

33

AWS SDK for Java 2.x Developer Guide for version 2.x

Load temporary credentials from an external process

Region region = Region.US_WEST_2;

S3Client s3Client = S3Client.builder()

.region(region)

.credentialsProvider(ProfileCredentialsProvider.create("process-credential-profile"))

.build();

For detailed information about using an external process as a source of temporary credentials, refer to

the process credentials section in the AWS SDKs and Tools Reference Guide.

Use the ProcessCredentialsProvider

As an alternative to using settings in the config ﬁle, you can use the SDK's

ProcessCredentialsProvider to load temporary credentials using Java.

The following examples show various versions of how to specify an external process using the

ProcessCredentialsProvider and conﬁguring a service client that uses the temporary credentials.

Linux/macOS

No spaces in ﬁle path

ProcessCredentialsProvider credentials =

ProcessCredentialsProvider

.builder()

.command("/path/to/credentials.sh optional_param1 optional_param2")

.build();

S3Client s3 = S3Client.builder()

.region(Region.US_WEST_2)

.credentialsProvider(credentials)

.build();

Spaces in ﬁle path

ProcessCredentialsProvider credentials =

ProcessCredentialsProvider

.builder()

.command("/path\\ with\\ spaces\\ to/credentials.sh optional_param1

optional_param2")

.build();

S3Client s3 = S3Client.builder()

.region(Region.US_WEST_2)

.credentialsProvider(credentials)

.build();

Windows

No spaces in ﬁle path

ProcessCredentialsProvider credentials =

ProcessCredentialsProvider

.builder()

.command("C:\\Path\\To\\credentials.exe optional_param1 optional_param2")

.build();

S3Client s3 = S3Client.builder()

.region(Region.US_WEST_2)

.credentialsProvider(credentials)

34

AWS SDK for Java 2.x Developer Guide for version 2.x

Supply temporary credentials in code

.build();

Spaces in ﬁle path

ProcessCredentialsProvider credentials =

ProcessCredentialsProvider

.builder()

.command("\"C:\\Path\\With Spaces To\\credentials.exe\" optional_param1

optional_param2")

.build();

S3Client s3 = S3Client.builder()

.region(Region.US_WEST_2)

.credentialsProvider(credentials)

.build();

Supply temporary credentials in code

If the default credential chain or a speciﬁc or custom provider or provider chain doesn't work for your

application, you can supply temporary credentials directly in code. These can be IAM role credentials as

described above (p. 28) or temporary credentials retrieved from AWS Security Token Service (AWS

STS). If you retrieved temporary credentials using AWS STS, provide them to an AWS service client as

shown in the following code example.

1.

Assume a role by calling StsClient.assumeRole().

2.

Create a StaticCredentialsProvider object and supply it with the AwsSessionCredentials object.

3.

Conﬁgure the service client builder with the StaticCredentialsProvider and build the client.

The following example creates an Amazon S3 service client using temporary credentials returned by AWS

STS for an IAM assumed role.

// The AWS IAM Identity Center identity (user) who executes this method does not have

permission to list buckets.

// The identity is configured in the [default] profile.

public static void assumeRole(String roleArn, String roleSessionName) {

// The IAM role represented by the 'roleArn' parameter can be assumed by identities

in two different accounts

// and the role permits the user to only list buckets.

// The SDK's default credentials provider chain will find the single sign-on

settings in the [default] profile.

// The identity configured with the [default] profile needs permission to call

AssumeRole on the STS service.

try {

Credentials tempRoleCredentials;

try (StsClient stsClient = StsClient.create()) {

AssumeRoleRequest roleRequest = AssumeRoleRequest.builder()

.roleArn(roleArn)

.roleSessionName(roleSessionName)

.build();

AssumeRoleResponse roleResponse = stsClient.assumeRole(roleRequest);

tempRoleCredentials = roleResponse.credentials();

}

// Use the following temporary credential items for the S3 client.

String key = tempRoleCredentials.accessKeyId();

String secKey = tempRoleCredentials.secretAccessKey();

String secToken = tempRoleCredentials.sessionToken();

35

AWS SDK for Java 2.x Developer Guide for version 2.x

Supply temporary credentials in code

// List all buckets in the account associated with the assumed role

// by using the temporary credentials retrieved by invoking

stsClient.assumeRole().

StaticCredentialsProvider staticCredentialsProvider =

StaticCredentialsProvider.create(

AwsSessionCredentials.create(key, secKey, secToken));

try (S3Client s3 = S3Client.builder()

.credentialsProvider(staticCredentialsProvider)

.build()) {

List<Bucket> buckets = s3.listBuckets().buckets();

for (Bucket bucket : buckets) {

System.out.println("bucket name: " + bucket.name());

}

} catch (StsException | S3Exception e) {

logger.error(e.getMessage());

System.exit(1);

}

Permission set

The following permission set deﬁned in AWS IAM Identity Center allows the identity (user) to perform

the following two operations

1.

The GetObject operation of the Amazon Simple Storage Service.

2.

The AssumeRole operation of the AWS Security Token Service.

Without assuming the role, the s3.listBuckets() method shown in the example would fail.

{

"Version": "2012-10-17",

"Statement": [

{

"Effect": "Allow",

"Action": [

"s3:GetObject",

"sts:AssumeRole"

],

"Resource": [

"*"

]

}

]

}

Assumed role

Assumed role permissions policy

The following permissions policy is attached to the role that is assume in the previous example. This

permissions polilcy permits the ability to list all buckets in the same account as the role.

{

"Version": "2012-10-17",

"Statement": [

{

"Effect": "Allow",

"Action": [

"s3:ListAllMyBuckets"

36

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure IAM roles for Amazon EC2

],

"Resource": [

"*"

]

}

]

}

Assumed role trust policy

The following trust policy is attached to the role that is assume in the previous example. The policy

allows the role to be assumed by identities (users) in two accounts.

{

"Version": "2012-10-17",

"Statement": [

{

"Effect": "Allow",

"Principal": {

"AWS": [

"arn:aws:iam::111122223333:root",

"arn:aws:iam::555555555555:root"

]

},

"Action": "sts:AssumeRole",

"Condition": {}

}

]

}

Conﬁgure IAM roles for Amazon EC2

You can use an IAM role to manage temporary credentials for applications that are running on an EC2

instance and making AWS CLI or AWS API requests. This is preferable to storing access keys within the

EC2 instance. To assign an AWS role to an EC2 instance and make it available to all of its applications,

you create an instance proﬁle that is attached to the instance. An instance proﬁle contains the role

and enables programs that are running on the EC2 instance to get temporary credentials. For more

information, see Using an IAM role to grant permissions to applications running on Amazon EC2

instances in the IAM User Guide.

This topic provides information about how to use IAM roles with AWS SDK for Java applications running

on Amazon EC2.

Default provider chain and Amazon EC2 instance proﬁles

If your application creates an AWS client using the create method, the client searches for temporary

credentials using the default credentials provider chain, as described in the the section called “Default

credentials provider chain” (p. 29) section .

The ﬁnal step in the default provider chain is available only when running your application on an

Amazon EC2 instance. However, it provides better ease of use and security when working with Amazon

EC2 instances. You can also pass an InstanceProﬁleCredentialsProvider instance directly to the client

constructor to get instance proﬁle credentials without going through the entire default provider chain.

This is demonstrated in the following example:

S3Client s3 = S3Client.builder()

.credentialsProvider(InstanceProfileCredentialsProvider.builder().build())

.build();

37

AWS SDK for Java 2.x Developer Guide for version 2.x

AWS region selection

When you use this approach, the SDK retrieves temporary AWS credentials that have the same

permissions as those associated with the IAM role that is associated with the Amazon EC2 instance

in its instance proﬁle. Although these credentials are temporary and would eventually expire,

InstanceProfileCredentialsProvider periodically refreshes them for you so that they continue to

allow access to AWS.

Walkthrough: Using IAM roles for EC2 instances

This walkthrough shows you how to retrieve an object from Amazon S3 using an IAM role to manage

access.

Create an IAM role

Create an IAM role that grants read-only access to Amazon S3.

1. Open the IAM console.

2. In the navigation pane, choose Roles, then Create Role.

3. On the Select trusted entity page, choose AWS service. Under Use case, choose EC2. Choose Next.

4. On the Add permissions page, choose Amazon S3ReadOnlyAccess from the permissions policy list,

then choose Next.

Enter a name for the role, then select Create role. Note this name. You need it to launch your Amazon

EC2 instance.

Launch an EC2 instance and specify your IAM role

To launch an Amazon EC2 instance with an IAM role using the console, follow the instructions in the

Amazon EC2 User Guide for Linux Instances.

Note

You need to create or use an existing security group and key pair to connect to the instance.

With this IAM and Amazon EC2 setup, you can deploy your application to the Amazon EC2 instance and it

will have read access to Amazon S3.

AWS region selection

Regions enable you to access AWS services that physically reside in a speciﬁc geographic area. This can

be useful both for redundancy and to keep your data and applications running close to where you and

your users will access them.

In AWS SDK for Java 2.x, all the diﬀerent region related classes from version 1.x have been collapsed into

one Region class. You can use this class for all region-related actions such as retrieving metadata about a

region or checking whether a service is available in a region.

Choosing a region

You can specify a region name and the SDK will automatically choose an appropriate endpoint for you.

To explicitly set a region, we recommend that you use the constants deﬁned in the Region class. This is

an enumeration of all publicly available regions. To create a client with a region from the class, use the

following code.

Ec2Client ec2 = Ec2Client.builder()

.region(Region.US_WEST_2)

38

AWS SDK for Java 2.x Developer Guide for version 2.x

Choosing a speciﬁc endpoint

.build();

If the region you are attempting to use isn’t one of the constants in the Region class, you can create a

new region using the of method. This feature allows you access to new Regions without upgrading the

SDK.

Region newRegion = Region.of("us-east-42");

Ec2Client ec2 = Ec2Client.builder()

.region(newRegion)

.build();

Note

After you build a client with the builder, it’s immutable and the region cannot be changed. If you

are working with multiple AWS Regions for the same service, you should create multiple clients

—one per region.

Choosing a speciﬁc endpoint

Each AWS client can be conﬁgured to use a speciﬁc endpoint within a region by calling the

endpointOverride method.

For example, to conﬁgure the Amazon EC2 client to use the Europe (Ireland) Region, use the following

code.

Ec2Client ec2 = Ec2Client.builder()

.region(Region.EU_WEST_1)

.endpointOverride(URI.create("https://ec2.eu-west-1.amazonaws.com"))

.build();

See Regions and Endpoints for the current list of regions and their corresponding endpoints for all AWS

services.

Automatically determine the Region from the

environment

When running on Amazon EC2 or AWS Lambda, you might want to conﬁgure clients to use the same

region that your code is running on. This decouples your code from the environment it’s running in and

makes it easier to deploy your application to multiple regions for lower latency or redundancy.

To use the default credential/region provider chain to determine the region from the environment, use

the client builder’s create method.

Ec2Client ec2 = Ec2Client.create();

If you don’t explicitly set a region using the region method, the SDK consults the default region

provider chain to try and determine the region to use.

Default region provider chain

The following is the region lookup process:

1.

Any explicit region set by using region on the builder itself takes precedence over anything else.

2.

The AWS_REGION environment variable is checked. If it’s set, that region is used to conﬁgure the

client.

39

AWS SDK for Java 2.x Developer Guide for version 2.x

Checking for service availability in a Region

Note

This environment variable is set by the Lambda container.

3.

The SDK checks the AWS shared conﬁguration ﬁle (usually located at ~/.aws/config). If the region

property is present, the SDK uses it.

•

The AWS_CONFIG_FILE environment variable can be used to customize the location of the shared

conﬁg ﬁle.

•

The AWS_PROFILE environment variable or the aws.profile system property can be used to

customize the proﬁle that the SDK loads.

4. The SDK attempts to use the Amazon EC2 instance metadata service to determine the region of the

currently running Amazon EC2 instance.

5. If the SDK still hasn’t found a region by this point, client creation fails with an exception.

When developing AWS applications, a common approach is to use the shared conﬁguration ﬁle (described

in Credential retrieval order (p. 29)) to set the region for local development, and rely on the default

region provider chain to determine the region when running on AWS infrastructure. This greatly

simpliﬁes client creation and keeps your application portable.

Checking for service availability in a Region

To see if a particular AWS service is available in a region, use the serviceMetadata and region

method on the service that you’d like to check.

DynamoDbClient.serviceMetadata().regions().forEach(System.out::println);

See the Region class documentation for the regions you can specify, and use the endpoint preﬁx of the

service to query.

Reduce SDK startup time for AWS Lambda

One of the goals of the AWS SDK for Java 2.x is to reduce the startup latency for AWS Lambda functions.

The SDK contains changes that reduce startup time, which are discussed at the end of this topic.

First, this topic focuses on changes that you can make to reduce cold start times. These include making

changes in your code structure and in the conﬁguration of service clients.

Use the SDK’s UrlConnectionHttpClient

For synchronous scenarios, the SDK for Java 2.x oﬀers the UrlConnectionHttpClient class, which is

based on the JDK's HTTP client classes. Because the UrlConnectionHttpClient is based on classes

already on the classpath, there are no extra dependencies to load.

For information on adding the UrlConnectionHttpClient to your Lambda project and conﬁguring its

use, see Conﬁgure the URLConnection-based HTTP client (p. 52).

Note

There are some feature limitations with the UrlConnectionHttpClient in comparison to the

SDK's ApacheHttpClient. The ApacheHttpClient is the default asynchronous HTTP client

in the SDK. For example, the UrlConnectionHttpClient does not support the HTTP PATCH

method.

A handful of AWS API operations require PATCH requests. Those operation names usually start

with Update*. The following are several examples.

40

AWS SDK for Java 2.x Developer Guide for version 2.x

Use the SDK's AwsCrtAsyncHttpClient

•

Several Update* operations in the AWS Security Hub API and also the BatchUpdateFindings

operation

•

All Amazon API Gateway API Update* operations

•

Several Update* operations in the Amazon WorkDocs API

If you might use the UrlConnectionHttpClient, ﬁrst refer to the API Reference for the AWS

service that you're using. Check to see if the operations you need use the PATCH operation.

Use the SDK's AwsCrtAsyncHttpClient

The AwsCrtAsyncHttpClient is the asynchronous counterpart for reducing Lambda startup time in

the SDK.

The AwsCrtAsyncHttpClient is an asynchronous, non-blocking HTTP client. It's built on top of the

Java bindings of the AWS Common Runtime, which is written in the C programming language. Among

the goals in the development of the AWS Common Runtime is fast performance.

This guide's section on conﬁguring HTTP clients (p. 60) has information about adding an

AwsCrtAsyncHttpClient to your Lambda project and conﬁguring its use.

Remove unused HTTP client dependencies

Along with the explicit use of UrlConnectionHttpClient or AwsCrtAsyncHttpClient, you can

remove other HTTP clients that the SDK brings in by default. Lambda startup time is reduced when fewer

libraries need to be loaded, so you should remove any unused artifacts that the JVM needs to load.

The following snippet of a Maven pom.xml ﬁle shows the exclusion of the Apache-based

HTTP client and the Netty-based HTTP client. (These clients aren't needed when you use the

UrlConnectionHttpClient.) This example excludes the HTTP client artifacts from the

S3 client dependency and adds the url-connection-client artifact, which brings in the

UrlConnectionHttpClient class.

<aws.java.sdk.version>2.17.290</aws.java.sdk.version>

<groupId>software.amazon.awssdk</groupId>

<version>${aws.java.sdk.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>url-connection-client</artifactId>

</dependency>

<groupId>software.amazon.awssdk</groupId>

<groupId>software.amazon.awssdk</groupId>

<artifactId>netty-nio-client</artifactId>

41

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure service clients to shortcut lookups

</exclusion>

<groupId>software.amazon.awssdk</groupId>

<artifactId>apache-client</artifactId>

</exclusion>

</exclusions>

</dependency>

</dependencies>

</project>

If you use the AwsCrtAsyncHttpClient, replace the dependency on the url-connection-client to

a dependency on the aws-crt-client.

Note

Add the <exclusions> element to all service client dependencies in your pom.xml ﬁle.

Conﬁgure service clients to shortcut lookups

Specify a region

When you create a service client, call the region method on the service client builder. This shortcuts

the SDK's default Region lookup process that checks several places for the AWS Region information.

To keep the Lambda code independent of the region, use the following code inside the region

method. This code accesses the AWS_REGION environment variable set by the Lambda container.

Region.of(System.getenv(SdkSystemSetting.AWS_REGION.environmentVariable()))

Use the EnvironmentVariableCredentialProvider

Much like the default lookup behavior for the Region information, the SDK looks in several places

for credentials. By specifying the EnvironmentVariableCredentialProvider when you build a

service client, you save time in the SDK's lookup process.

Note

Using this credentials provider enables the code to be used in Lambda functions, but might

not work on Amazon EC2 or other systems.

The following code snippet shows an S3 service client appropriately conﬁgured for use in a Lambda

environment.

S3Client client = S3Client.builder()

.region(Region.of(System.getenv(SdkSystemSetting.AWS_REGION.environmentVariable())))

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.httpClient(UrlConnectionHttpClient.builder().build())

.build();

Initialize the SDK client outside of the Lambda

function handler

We recommend initializing an SDK client outside of the Lambda handler method. This way, if the

execution context is reused, the initialization of the service client can be skipped. By reusing the client

instance and its connections, subsequent invocations of the handler method occur more quickly.

In the following example, the S3Client instance is initialized in the constructor using a static factory

method. If the container that is managed by the Lambda environment is reused, the initialized

S3Client instance is reused.

42

AWS SDK for Java 2.x Developer Guide for version 2.x

Minimize dependency injection

public class App implements RequestHandler<Object, Object> {

private final S3Client s3Client;

public App() {

s3Client = DependencyFactory.s3Client();

}

@Override

public Object handle Request(final Object input, final Context context) {

ListBucketResponse response = s3Client.listBuckets();

// Process the response.

}

Minimize dependency injection

Dependency injection (DI) frameworks might take additional time to complete the setup process. They

might also require additional dependencies, which take time to load.

If a DI framework is needed, we recommend using lightweight DI frameworks such as Dagger.

Use a Maven Archetype targeting AWS Lambda

The AWS Java SDK team has developed a Maven Archetype template to bootstrap a Lambda project

with minimal startup time. You can build out a Maven project from the archetype and know that the

dependencies are conﬁgured suitably for the Lambda environment.

To learn more about the archetype and work through an example deployment, see this blog post.

Consider Lambda SnapStart for Java

If your runtime requirements are compatible, AWS oﬀers Lambda SnapStart for Java. Lambda SnapStart

is an infrastructure-based solution that improves startup performance for Java functions. When you

publish a new version of a function, Lambda SnapStart initializes it and takes an immutable, encrypted

snapshot of the memory and disk state. SnapStart then caches the snapshot for reuse.

Version 2.x changes that aﬀect startup time

In addition to changes that you make to your code, version 2.x of the SDK for Java includes three primary

changes that reduce startup time:

• Use of jackson-jr, which is a serialization library that improves initialization time

• Use of the java.time libraries for date and time objects, which is part of the JDK

• Use of Slf4j for a logging facade

Additional resources

The AWS Lambda Developer Guide contains a section on best practices for developing Lambda functions

that is not Java speciﬁc.

For an example of building a cloud-native application in Java that uses AWS Lambda, see this workshop

content. The workshop discussion performance optimization and other best practices.

You can consider using static images that are compiled ahead of time to reduce startup latency. For

example, you can use the SDK for Java 2.x and Maven to build a GraalVM native image (p. 22).

43

AWS SDK for Java 2.x Developer Guide for version 2.x

HTTP clients

You can change the default conﬁguration for HTTP clients in applications you build with the AWS SDK

for Java 2.x. This section discusses HTTP clients and settings for the SDK.

Clients available in the SDK for Java

Synchronous clients

A synchronous service client, such as the S3Client or the DynamoDbClient, requires the use of a

synchronous HTTP client. The AWS SDK for Java oﬀers two synchronous HTTP clients.

ApacheHttpClient (default)

ApacheHttpClient is the default HTTP client for synchronous service clients. For information about

conﬁguring the ApacheHttpClient, see Conﬁgure the Apache-based HTTP client (p. 49).

UrlConnectionHttpClient

As a lighter weight option to the ApacheHttpClient, you can use the UrlConnectionHttpClient.

For information about conﬁguring the UrlConnectionHttpClient, see Conﬁgure the

URLConnection-based HTTP client (p. 52).

Asynchronous clients

An asynchronous service client, such as the S3AsyncClient or the DynamoDbAsyncClient, requires the

use of an asynchronous HTTP client. The AWS SDK for Java oﬀers two asynchronous HTTP clients.

NettyNioAsyncHttpClient (default)

NettyNioAsyncHttpClient is the default HTTP client used by asynchronous clients. For information

about conﬁguring the NettyNioAsyncHttpClient, see the section called “Conﬁgure the Netty-

based HTTP client” (p. 56).

AwsCrtAsyncHttpClient

The new AwsCrtAsyncHttpClient, which also has a quicker loading time compared to the

NettyNioAsyncHttpClient, is also available. For information about conﬁguring the

AwsCrtAsyncHttpClient, see the section called “Conﬁgure the AWS CRT-based HTTP

client” (p. 60).

HTTP client recommendations

Several factors come into play when you choose an HTTP client implemenation. Use the following

information to help you decide.

Recommendation ﬂowchart

The following ﬂowchart provides general guidance to help you determine which HTTP client to use.

44

AWS SDK for Java 2.x Developer Guide for version 2.x

Client recommendations

45

AWS SDK for Java 2.x Developer Guide for version 2.x

Smart defaults

HTTP client comparison

The following table provides detailed information for each HTTP client.

HTTP client Sync or async When to use Limitation/

drawback

Apache-based

HTTP client

(default sync HTTP

client)

Sync Use it if you prefer low latency over

high throughput

Slower startup

time compared to

other HTTP clients

URLConnection-

based HTTP client

Sync Use it if you have a hard requirement

for limiting third-party dependencies

Does not support

the HTTP PATCH

method, required

by some APIS

like Amazon

APIGateway

Update operations

Netty-based HTTP

client

(default async

HTTP client)

Async • Use it if your application invokes APIs

that require HTTP/2 support such as

Kinesis API SubscribeToShard

Slower startup

time compared to

other HTTP clients

AWS CRT-based

HTTP client

1

Async • Use it if your application is running in

AWS Lambda

• Use it if you prefer high throughput

over low latency

• Does not support

service clients that

require HTTP/2

support such as

KinesisAsynClient

and

TranscribeStreamingAsyncClient

1

We recommend that you use the AWS CRT-based HTTP client if possible, because of its added beneﬁts.

Smart conﬁguration defaults

The AWS SDK for Java 2.x (version 2.17.102 or later) oﬀers a smart conﬁguration defaults feature. This

feature optimizes two HTTP client properties along with other properties that don't aﬀect the HTTP

client.

The smart conﬁguration defaults set sensible values for the connectTimeoutInMillis and

tlsNegotiationTimeoutInMillis properties based on a defaults mode value that you provide. You

choose the defaults mode value based on your application's characteristics.

For more information about smart conﬁguration defaults and how to choose the defaults mode value

that is best suited for your applications, see the AWS SDKs and Tools Reference Guide.

Following are four ways to set the defaults mode for your application.

Service client

Use the service client builder to conﬁgure the defaults mode directly on the service client. The

following example sets the defaults mode to auto for the DynamoDbClient.

46

AWS SDK for Java 2.x Developer Guide for version 2.x

Proxy support

DynamoDbClient ddbClient = DynamoDbClient.builder()

.defaultsMode(DefaultsMode.AUTO)

.build();

System property

You can use the aws.defaultsMode system property to specify the defaults mode. If you set the

system property in Java, you need to set the property before initializing any service client.

The following example shows you how to set the defaults mode to auto using a system property set

in Java.

System.setProperty("aws.defaultsMode", "auto");

The following example demonstrates how you set the defaults mode to auto using a -D option of

the java command.

java -Daws.defaultsMode=auto

Environment variable

Set a value for environment variable AWS_DEFAULTS_MODE to select the defaults mode for your

application.

The following information shows the command to run to set the value for the defaults mode to

auto using an environment variable.

Operating system Command to set environment variables

Linux, macOS, or Unix

export AWS_DEFAULTS_MODE=auto

Windows

set AWS_DEFAULTS_MODE=auto

AWS conﬁg ﬁle

You can add a defaults_mode conﬁguration property to the shared AWS config ﬁle as the

following example shows.

[default]

defaults_mode = auto

If you set the defaults mode globally with the system property, environment variable, or AWS conﬁg ﬁle,

you can override the settings when you build an HTTP client.

When you build an HTTP client with the httpClientBuilder() method, settings apply only to the

instance that you are building. An example of this is shown here (p. 57). The Netty-based HTTP client

in this example overrides any default mode values set globally for connectTimeoutInMillis and

tlsNegotiationTimeoutInMillis.

Proxy support

You can conﬁgure HTTP proxies by using code, by setting Java system properties, or by combining both

approaches. The SDK currently does not support environment variables to conﬁgure proxies.

47

AWS SDK for Java 2.x Developer Guide for version 2.x

Proxy support

You conﬁgure proxies in code with a client-speciﬁc ProxyConfiguration builder when you build the

service client. The section for each HTTP client in this topic shows a proxy conﬁguration example. This

example is for the Apache HTTP client (p. 52).

HTTP client support of Java system properties for HTTP proxies

System property Description HTTP client support

http.proxyHost Host name of the HTTP proxy

server

All

http.proxyPort Port number of the HTTP proxy

server

All

http.proxyUser Username for HTTP proxy

authentication

All

http.proxyPassword Password for HTTP proxy

authentication

All

http.nonProxyHosts List of hosts that should be

reached directly, bypassing the

proxy. Also valid when HTTPS is

used.

All

https.proxyHost Host name of the HTTPS proxy

server

Netty, CRT

https.proxyPort Port number of the HTTPS proxy

server

Netty, CRT

https.proxyUser Username for HTTPS proxy

authentication

Netty, CRT

https.proxyPassword Password for HTTPS proxy

authentication

Netty, CRT

The terms used in the tables mean:

•

All: All HTTP clients oﬀered by the SDK–UrlConnectionHttpClient, ApacheHttpClient,

NettyNioAsyncHttpClient, AwsCrtAsyncHttpClient

•

Netty: the Netty-based HTTP client (NettyNioAsyncHttpClient)

•

CRT: the AWS CRT-based HTTP client, (AwsCrtAsyncHttpClient)

You can use a mix of HTTP client conﬁguration and system properties. Each HTTP client's

ProxyConfiguration builder provides a useSystemPropertyValues setting. By default, the setting

is true. When the setting is true, the SDK automatically uses system property values for options that

are not provided by using the ProxyConfiguration builder.

The following example shows conﬁguration provided by a system property and by code.

// Command line with the proxy password set as a system property.

$ java -Dhttp.proxyPassword=password -cp ... App

// Since the 'useSystemPropertyValues' setting is 'true' (the default), the SDK will

supplement

// the proxy configuration in code with the 'http.proxyPassword' value from the system

property.

48

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the Apache-based HTTP client

SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()

.proxyConfiguration(ProxyConfiguration.builder()

.endpoint(URI.create("http://localhost:1234"))

.username("username")

.build())

.build();

// Use the apache HTTP client with proxy configuration.

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()

.httpClient(apacheHttpClient)

.build();

Note

Instead of setting the endpoint property in code as shown in the previous code snippet, you

can use the following system properties.

-Dhttp.proxyHost=localhost -Dhttp.proxyPort=1234

Conﬁgure the Apache-based HTTP client

Synchronous service clients in the AWS SDK for Java 2.x use an Apache-based HTTP client,

ApacheHttpClient by default. The SDK's ApacheHttpClient is based on the Apache HttpClient.

The SDK also oﬀers the UrlConnectionHttpClient, which loads more quickly, but has fewer features. For

information about conﬁguring the UrlConnectionHttpClient, see the section called “Conﬁgure the

URLConnection-based HTTP client” (p. 52).

To see the full set of conﬁguration options available to you for the ApacheHttpClient, see

ApacheHttpClient.Builder and ProxyConﬁguration.Builder.

Access the ApacheHttpClient

In most situations, you use the ApacheHttpClient without any explicit conﬁguration. You declare your

service clients and the SDK will conﬁgure the ApacheHttpClient with standard values for you.

If you want to explicitly conﬁgure the ApacheHttpClient or use it with multiple service clients, you

need to make it available for conﬁguration.

No conﬁguration needed

When you declare a dependency on a service client in Maven, the SDK adds a runtime dependency on the

apache-client artifact. This makes the ApacheHttpClient class available to your code at runtime. If

you are not conﬁguring the Apache-based HTTP client, you do not need to specify a dependency for it.

In the following XML snippet of a Maven pom.xml ﬁle, the dependency declared with

<artifactId>s3</artifactId> automatically brings in the Apache-based HTTP client. You don't

need to declare a dependency speciﬁcally for it.

<groupId>software.amazon.awssdk</groupId>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

49

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the Apache-based HTTP client

<!-- The s3 dependency automatically adds a runtime dependency on the

ApacheHttpClient-->

<groupId>software.amazon.awssdk</groupId>

</dependency>

</dependencies>

With these dependencies, you cannot make any explicit HTTP conﬁguration changes, because the

ApacheHttpClient library is only on the runtime classpath.

Conﬁguration needed

To conﬁgure the ApacheHttpClient, you need to add a dependency on the apache-client library at

compile time.

Refer to the following example of a Maven pom.xml ﬁle to conﬁgure the ApacheHttpClient.

<groupId>software.amazon.awssdk</groupId>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

</dependency>

<!-- By adding the apache-client dependency, ApacheHttpClient will be added to

the compile classpath so you can configure it. -->

<groupId>software.amazon.awssdk</groupId>

<artifactId>apache-client</artifactId>

</dependency>

</dependencies>

Conﬁgure the ApacheHttpClient

You can conﬁgure an instance of ApacheHttpClient along with building a service client, or you can

conﬁgure a single instance to share across multiple service clients.

With either approach, you use the ApacheHttpClient.Builder to conﬁgure the properties for the

Apache-based HTTP client.

Best practice: dedicate an ApacheHttpClient instance to a service client

If you need to conﬁgure an instance of the ApacheHttpClient, we recommend that you build the

dedicated ApacheHttpClient instance. You can do so by using the httpClientBuilder method of

the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK, which helps

avoid potential memory leaks if the ApacheHttpClient instance is not closed down when it's no longer

needed.

The following example creates an S3Client and conﬁgures the embedded instance of

ApacheHttpClient with maxConnections and connectionTimeout values. The HTTP instance is

created using the httpClientBuilder method of S3Client.Builder.

50

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the Apache-based HTTP client

Imports

import software.amazon.awssdk.http.apache.ApacheHttpClient;

import software.amazon.awssdk.services.s3.S3Client;

import java.time.Duration;

Code

S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.

.builder()

.httpClientBuilder(ApacheHttpClient.builder()

.maxConnections(100)

.connectionTimeout(Duration.ofSeconds(5))

).build();

// Perform work with the s3Client.

s3Client.close(); // Requests completed: Close all service clients.

Alternative approach: share an ApacheHttpClient instance

To help keep resource and memory usage lower for your application, you can conﬁgure an

ApacheHttpClient and share it across multiple service clients. The HTTP connection pool will be

shared, which lowers resource usage.

Note

When an ApacheHttpClient instance is shared, you must close it when it is ready to be

disposed. The SDK will not close the instance when the service client is closed.

The following example conﬁgures an Apache-based HTTP client, which is used by two service clients. The

conﬁgured ApacheHttpClient instance is passed to the httpClient method of the service client's

builder. When the service clients and the HTTP client are no longer needed, they are explicitly closed.

The HTTP client is closed last.

Imports

import software.amazon.awssdk.http.SdkHttpClient;

import software.amazon.awssdk.http.apache.ApacheHttpClient;

import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

import software.amazon.awssdk.services.s3.S3Client;

Code

SdkHttpClient apacheHttpClient = ApacheHttpClient.create();

// Singletons: Use the s3Client and dynamoDbClient for all requests.

S3Client s3Client =

S3Client.builder()

.httpClient(apacheHttpClient).build();

DynamoDbClient dynamoDbClient =

DynamoDbClient.builder()

.httpClient(apacheHttpClient).build();

// Perform work with the s3Client and dynamoDbClient.

// Requests completed: Close all service clients.

s3Client.close();

dynamoDbClient.close();

51

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the URLConnection-based HTTP client

apacheHttpClient.close(); // Explicitly close apacheHttpClient.

Proxy conﬁguration example

The following code snippet uses the proxy conﬁguration builder for the Apache HTTP client.

SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()

.proxyConfiguration(ProxyConfiguration.builder()

.endpoint(URI.create("http://example.com:1234"))

.username("username")

.password("password")

.addNonProxyHost("localhost")

.addNonProxyHost("host.example.com")

.build())

.build();

The equivalent Java system properties for the proxy conﬁguration are shown in the following command

line snippet.

$ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \

-Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=locahost|host.example.com -cp ... App

Note

The Apache HTTP client does not currently support HTTPS proxy system properties.

Conﬁgure the URLConnection-based HTTP client

The AWS SDK for Java 2.x oﬀers a lighter-weight UrlConnectionHttpClient HTTP client in

comparison to the default ApacheHttpClient. The UrlConnectionHttpClient is based on Java's

URLConnection.

The UrlConnectionHttpClient loads more quickly than the Apache-based HTTP client, but has fewer

features. Because it loads more quickly, it is a good solution (p. 40) for Java AWS Lambda functions.

The UrlConnectionHttpClient has several conﬁgurable options that you can access.

To learn how to conﬁgure the Apache-based HTTP client, see Conﬁgure the Apache-based HTTP

client (p. 49).

Note

The UrlConnectionHttpClient does not support the HTTP PATCH method.

A handful of AWS API operations require PATCH requests. Those operation names usually start

with Update*. The following are several examples.

•

Several Update* operations in the AWS Security Hub API and also the BatchUpdateFindings

operation

•

All Amazon API Gateway API Update* operations

•

Several Update* operations in the Amazon WorkDocs API

If you might use the UrlConnectionHttpClient, ﬁrst refer to the API Reference for the AWS

service that you're using. Check to see if the operations you need use the PATCH operation.

Access the UrlConnectionHttpClient

To conﬁgure and use the UrlConnectionHttpClient, you declare a dependency on the url-

connection-client Maven artifact in your pom.xml ﬁle.

52

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the URLConnection-based HTTP client

Unlike the ApacheHttpClient, the UrlConnectionHttpClient is not automatically added to your

project, so use must speciﬁcally declare it.

The following example of a pom.xml ﬁle shows the dependencies required to use and conﬁgure the

HTTP client.

<groupId>software.amazon.awssdk</groupId>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>url-connection-client</artifactId>

</dependency>

</dependencies>

Conﬁgure the UrlConnectionHttpClient

You can conﬁgure an instance of UrlConnectionHttpClient along with building a service client, or

you can conﬁgure a single instance to share across multiple service clients.

With either approach, you use the UrlConnectionHttpClient.Builder to conﬁgure the properties for the

URLConnection-based HTTP client.

Best practice: dedicate an UrlConnectionHttpClient instance to a service

client

If you need to conﬁgure an instance of the UrlConnectionHttpClient, we recommend that you build

the dedicated UrlConnectionHttpClient instance. You can do so by using the httpClientBuilder

method of the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK,

which helps avoid potential memory leaks if the UrlConnectionHttpClient instance is not closed

down when it's no longer needed.

The following example creates an S3Client and conﬁgures the embedded instance of

UrlConnectionHttpClient with maxConnections and connectionTimeout values. The HTTP

instance is created using the httpClientBuilder method of S3Client.Builder.

The following example creates an S3Client and conﬁgures the embedded instance

of UrlConnectionHttpClient with socketTimeout and proxyConfiguration

values. The proxyConfiguration method takes a Java lambda expression of type

Consumer<ProxyConfiguration.Builder>. The HTTP instance is created using the

httpClientBuilder method of S3Client.Builder.

Imports

import software.amazon.awssdk.http.SdkHttpClient;

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;

import java.net.URI;

53

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the URLConnection-based HTTP client

import java.time.Duration;

Code

// Singleton: Use the s3Client for all requests.

S3Client s3Client =

S3Client.builder()

.httpClientBuilder(UrlConnectionHttpClient.builder()

.socketTimeout(Duration.ofMinutes(5))

.proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://

proxy.mydomain.net:8888"))))

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.build();

// Perform work with the s3Client.

s3Client.close(); // Requests completed: Close the s3client.

Alternative approach: share an UrlConnectionHttpClient instance

To help keep resource and memory usage lower for your application, you can conﬁgure an

UrlConnectionHttpClient and share it across multiple service clients. The HTTP connection pool will

be shared, which lowers resource usage.

Note

When an UrlConnectionHttpClient instance is shared, you must close it when it is ready to

be disposed. The SDK will not close the instance when the service client is closed.

The following example conﬁgures an URLConnection-based HTTP client, which is used by two service

clients. The conﬁgured UrlConnectionHttpClient instance is passed to the httpClient method of

the service client's builder. When the service clients and the HTTP client are no longer needed, they are

explicitly closed. The HTTP client is closed last.

Imports

import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;

import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;

import software.amazon.awssdk.http.SdkHttpClient;

import software.amazon.awssdk.http.urlconnection.ProxyConfiguration;

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;

import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

import software.amazon.awssdk.services.s3.S3Client;

import java.net.URI;

import java.time.Duration;

Code

SdkHttpClient urlHttpClient = UrlConnectionHttpClient.create();

// Singletons: Use the s3Client and dynamoDbClient for all requests.

S3Client s3Client =

S3Client.builder()

.httpClient(urlHttpClient)

.defaultsMode(DefaultsMode.IN_REGION)

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.build();

DynamoDbClient dynamoDbClient =

DynamoDbClient.builder()

.httpClient(urlHttpClient)

54

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the URLConnection-based HTTP client

.defaultsMode(DefaultsMode.IN_REGION)

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.build();

// Perform work with the s3Client and dynamoDbClient.

// Requests completed: Close all service clients.

s3Client.close();

dynamoDbClient.close();

urlHttpClient.close();

Use URLConnectionHttpClient and ApacheHttpClient together

When using the UrlConnectionHttpClient in your application, you must supply each service client

with either a URLConnectionHttpClient instance or a ApacheHttpClient instance using the service

client builder's httpClientBuilder method.

An exception occurs if your program uses multiple service clients and both of the following are true:

•

One service client is conﬁgured to use a UrlConnectionHttpClient instance

•

Another service client uses the default ApacheHttpClient without explicitly building it with the

httpClient() or httpClientBuilder() methods

The exception will state that multiple HTTP implementations were found on the classpath.

The following example code snippet leads to an exception.

// The dynamoDbClient uses the UrlConnectionHttpClient

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()

.httpClient(UrlConnectionHttpClient.create())

.build();

// The s3Client below uses the ApacheHttpClient at runtime, without specifying it.

// An SdkClientException is thrown with the message that multiple HTTP implementations were

found on the classpath.

S3Client s3Client = S3Client.create();

// Perform work with the s3Client and dynamoDbClient.

dynamoDbClient.close();

s3Client.close();

Avoid the exception by explicitly conﬁguring the S3Client with an ApacheHttpClient.

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()

.httpClient(UrlConnectionHttpClient.create())

.build();

S3Client s3Client = S3Client.builder()

.httpClient(ApacheHttpClient.create()) // Explicitly build the ApacheHttpClient.

.build();

// Perform work with the s3Client and dynamoDbClient.

dynamoDbClient.close();

s3Client.close();

Note

To explicitly create the ApacheHttpClient, you must add a dependency (p. 49) on the

apache-client artifact in your Maven project ﬁle.

55

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the Netty-based HTTP client

Proxy conﬁguration example

The following code snippet uses the proxy conﬁguration builder for the URL connection HTTP client.

SdkHttpClient urlHttpClient = UrlConnectionHttpClient.builder()

.proxyConfiguration(ProxyConfiguration.builder()

.endpoint(URI.create("http://example.com:1234"))

.username("username")

.password("password")

.addNonProxyHost("localhost")

.addNonProxyHost("host.example.com")

.build())

.build();

The equivalent Java system properties for the proxy conﬁguration are shown in the following command

line snippet.

$ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \

-Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=locahost|host.example.com -cp ... App

Note

The URL connection HTTP client does not currently support HTTPS proxy system properties.

Conﬁgure the Netty-based HTTP client

The default HTTP client for asynchronous operations in the AWS SDK for Java 2.x is the Netty-based

NettyNioAsyncHttpClient. The Netty-based client is based on the asynchronous event-driven network

framework of the Netty project.

As an alternative, you can use the new AWS CRT-based HTTP client (p. 60). This topic shows you how

to conﬁgure the NettyNioAsyncHttpClient.

Access the NettyNioAsyncHttpClient

In most situations, you use the NettyNioAsyncHttpClient without any explicit conﬁguration in

asynchronous programs. You declare your asynchronous service clients and the SDK will conﬁgure the

NettyNioAsyncHttpClient with standard values for you.

If you want to explicitly conﬁgure the NettyNioAsyncHttpClient or use it with multiple service

clients, you need to make it available for conﬁguration.

No conﬁguration needed

When you declare a dependency on a service client in Maven, the SDK adds a runtime dependency on

the netty-nio-client artifact. This makes the NettyNioAsyncHttpClient class available to your

code at runtime. If you are not conﬁguring the Netty-based HTTP client, you don't need to specify a

dependency for it.

In the following XML snippet of a Maven pom.xml ﬁle, the dependency declared with

<artifactId>dynamodb-enhanced</artifactId> transitively brings in the Netty-based HTTP

client. You don't need to declare a dependency speciﬁcally for it.

<groupId>software.amazon.awssdk</groupId>

56

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the Netty-based HTTP client

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>dynamodb-enhanced</artifactId>

</dependency>

</dependencies>

With these dependencies, you cannot make any HTTP conﬁguration changes, since the

NettyNioAsyncHttpClient library is only on the runtime classpath.

Conﬁguration needed

To conﬁgure the NettyNioAsyncHttpClient, you need to add a dependency on the netty-nio-

client artifact at compile time.

Refer to the following example of a Maven pom.xml ﬁle to conﬁgure the NettyNioAsyncHttpClient.

<groupId>software.amazon.awssdk</groupId>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>dynamodb-enhanced</artifactId>

</dependency>

<!-- By adding the netty-nio-client dependency, NettyNioAsyncHttpClient will be

added to the compile classpath so you can configure it. -->

<groupId>software.amazon.awssdk</groupId>

<artifactId>netty-nio-client</artifactId>

</dependency>

</dependencies>

Conﬁgure the NettyNioAsyncHttpClient

You can conﬁgure an instance of NettyNioAsyncHttpClient along with building a service client, or

you can conﬁgure a single instance to share across multiple service clients.

With either approach, you use the NettyNioAsyncHttpClient.Builder to conﬁgure the properties for the

Netty-based HTTP client instance.

Best practice: dedicate a NettyNioAsyncHttpClient instance to a service

client

If you need to conﬁgure an instance of the NettyNioAsyncHttpClient, we recommend that you build

the dedicated NettyNioAsyncHttpClient instance. You can do so by using the httpClientBuilder

57

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the Netty-based HTTP client

method of the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK,

which helps avoid potential memory leaks if the NettyNioAsyncHttpClient instance is not closed

down when it's no longer needed.

The following example creates a DynamoDbAsyncClient instance, which is also used by a

DynamoDbEnhancedAsyncClient instance. The DynamoDbAsyncClient instance contains the

NettyNioAsyncHttpClient instance with connectionTimeout and maxConcurrency values. The

HTTP instance is created using httpClientBuilder method of DynamoDbAsyncClient.Builder.

Imports

import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;

import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;

import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;

import

software.amazon.awssdk.enhanced.dynamodb.extensions.AutoGeneratedTimestampRecordExtension;

import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;

import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;

import java.time.Duration;

Code

// DynamoDbAsyncClient is the lower-level client used by the enhanced client.

DynamoDbAsyncClient dynamoDbAsyncClient =

DynamoDbAsyncClient

.builder()

.httpClientBuilder(NettyNioAsyncHttpClient.builder()

.connectionTimeout(Duration.ofMillis(5_000))

.maxConcurrency(100)

.tlsNegotiationTimeout(Duration.ofMillis(3_500)))

.defaultsMode(DefaultsMode.IN_REGION)

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.build();

// Singleton: Use dynamoDbAsyncClient and enhancedClient for all requests.

DynamoDbEnhancedAsyncClient enhancedClient =

DynamoDbEnhancedAsyncClient

.builder()

.dynamoDbClient(dynamoDbAsyncClient)

.extensions(AutoGeneratedTimestampRecordExtension.create())

.build();

// Perform work with the dynamoDbAsyncClient and enhancedClient.

// Requests completed: Close dynamoDbAsyncClient.

dynamoDbAsyncClient.close();

Alternative approach: share a NettyNioAsyncHttpClient instance

To help keep resource and memory usage lower for your application, you can conﬁgure a

NettyNioAsyncHttpClient and share it across multiple service clients. The HTTP connection pool will

be shared, which lowers resource usage.

Note

When a NettyNioAsyncHttpClient instance is shared, you must close it when it is ready to

be disposed. The SDK will not close the instance when the service client is closed.

The following example conﬁgures a Netty-based HTTP client, which is used by two service clients. The

conﬁgured NettyNioAsyncHttpClient instance is passed to the httpClient method of each service

client's builder. When the service clients and the HTTP client are no longer needed, they are explicitly

closed. The HTTP client is closed last.

58

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the Netty-based HTTP client

Imports

import software.amazon.awssdk.http.SdkHttpClient;

import software.amazon.awssdk.http.apache.ApacheHttpClient;

import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

import software.amazon.awssdk.services.s3.S3Client;

Code

// Create a NettyNioAsyncHttpClient shared instance.

SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.create();

// Singletons: Use the s3AsyncClient, dbAsyncClient, and enhancedAsyncClient for all

requests.

S3AsyncClient s3AsyncClient =

S3AsyncClient.builder()

.httpClient(nettyHttpClient)

.build();

DynamoDbAsyncClient dbAsyncClient =

DynamoDbAsyncClient.builder()

.httpClient(nettyHttpClient)

.defaultsMode(DefaultsMode.IN_REGION)

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.build();

DynamoDbEnhancedAsyncClient enhancedAsyncClient =

DynamoDbEnhancedAsyncClient.builder()

.dynamoDbClient(dbAsyncClient)

.extensions(AutoGeneratedTimestampRecordExtension.create())

.build();

// Perform work with s3AsyncClient, dbAsyncClient, and enhancedAsyncClient.

// Requests completed: Close all service clients.

s3AsyncClient.close();

dbAsyncClient.close()

nettyHttpClient.close(); // Explicitly close nettyHttpClient.

Proxy conﬁguration example

The following code snippet uses the proxy conﬁguration builder for the Netty HTTP client.

SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder()

.proxyConfiguration(ProxyConfiguration.builder()

.scheme("https")

.host("myproxy")

.port(1234)

.username("username")

.password("password")

.build())

.build();

The equivalent Java system properties for the proxy conﬁguration are shown in the following command

line snippet.

$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \

-Dhttps.proxyPassword=password -cp ... App

59

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the AWS CRT-based HTTP client

Important

To use any of the HTTPS proxy system properties, the scheme property must be set in code

to https. If the scheme property is not set in code, the scheme defaults to HTTP and the SDK

looks only for http.* system properties.

Conﬁgure the AWS CRT-based HTTP client

The AwsCrtAsyncHttpClient is a new asynchronous HTTP client that you can use with the AWS SDK

for Java 2.x. The AwsCrtAsyncHttpClient brings the following beneﬁts for an HTTP client to the SDK.

• faster SDK startup time

• smaller memory footprint

• reduced latency time

• connection health management

• DNS load balancing

This topic is about using and conﬁguring the AWS CRT-based HTTP client. For information about

conﬁguring the Netty-based HTTP client, see the previous topic (p. 56).

AWS CRT-based components in the SDK

The AWS CRT-based HTTP client, described in this topic, and the AWS CRT-based S3 client are diﬀerent

components in the SDK.

The AWS CRT-based HTTP client is an implementation of the SdkAsyncHttpClient interface and

is used for general HTTP communication. It is an alternative to the Netty implementation of the

SdkAsyncHttpClient interface and oﬀers several beneﬁts.

The AWS CRT-based S3 client (p. 169) is an implementation of the S3AsyncClient interface and is used

for working with the Amazon S3 service. It is an alternative to the Java-based implementation of the

S3AsyncClient interface and oﬀers several advantages.

Although both components use libraries from the AWS Common Runtime, the AWS CRT-based HTTP

client does not use the aws-c-s3 library and does not support the S3 multipart upload API features.

The AWS CRT-based S3 client, by contrast, was purpose-built to support the S3 multipart upload API

features.

Access the AwsCrtAsyncHttpClient

Before you can use the AWS CRT-based HTTP client, add the aws-crt-client artifact to your project's

dependencies.

The following Maven pom.xml shows the AWS CRT-based HTTP client declared using the bill of

materials (BOM) mechanism.

<aws.sdk.version>VERSION</aws.sdk.version>

</properties>

<groupId>software.amazon.awssdk</groupId>

<version>${aws.sdk.version}</version>

<scope>import</scope>

60

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the AWS CRT-based HTTP client

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>aws-crt-client</artifactId>

</dependency>

</dependencies>

</project>

Visit the Maven central repository for the latest VERSION value.

Conﬁgure the AwsCrtAsyncHttpClient

You can conﬁgure an instance of AwsCrtAsyncHttpClient along with building a service client, or you

can conﬁgure a single instance to share across multiple service clients.

With either approach, you use the AwsCrtAsyncHttpClient.Builder to conﬁgure the properties for the

AWS CRT-based HTTP client instance.

Best practice: dedicate a AwsCrtAsyncHttpClient instance to a service client

If you need to conﬁgure an instance of the AwsCrtAsyncHttpClient, we recommend that you build

the dedicated AwsCrtAsyncHttpClient instance. You can do so by using the httpClientBuilder

method of the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK,

which helps avoid potential memory leaks if the AwsCrtAsyncHttpClient instance is not closed down

when it's no longer needed.

The following example creates an S3Client and conﬁgures the AwsCrtAsyncHttpClient with

connectionTimeout and maxConcurrency values.

Imports

import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;

import software.amazon.awssdk.services.s3.S3AsyncClient;

import java.time.Duration;

Code

// Singleton: Use s3AsyncClient for all requests.

S3AsyncClient s3AsyncClient = S3AsyncClient.builder()

.httpClientBuilder(AwsCrtAsyncHttpClient

.builder()

.connectionTimeout(Duration.ofSeconds(3))

.maxConcurrency(100))

.build();

// Perform work with the s3AsyncClient.

// Requests completed: Close the s3AsyncClient.

s3AsyncClient.close();

Alternative approach: share a AwsCrtAsyncHttpClient instance

To help keep resource and memory usage lower for your application, you can conﬁgure a

AwsCrtAsyncHttpClient and share it across multiple service clients. The HTTP connection pool will

be shared, which lowers resource usage.

61

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the AWS CRT-based HTTP client

Note

When a AwsCrtAsyncHttpClient instance is shared, you must close it when it is ready to be

disposed. The SDK will not close the instance when the service client is closed.

The following example conﬁgures a AWS CRT-based HTTP client instance with connectionTimeout

and maxConcurrency values. The conﬁgured AwsCrtAsyncHttpClient instance is passed to the

httpClient method of each service client's builder. When the service clients and the HTTP client are no

longer needed, they are explicitly closed. The HTTP client is closed last.

Imports

import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;

import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;

import software.amazon.awssdk.http.async.SdkAsyncHttpClient;

import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;

import software.amazon.awssdk.services.s3.S3AsyncClient;

import java.time.Duration;

Code

// Create an AwsCrtAsyncHttpClient shared instance.

SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.create();

// Singletons: Use the s3AsyncClient and dynamoDbAsyncClient for all requests.

S3AsyncClient s3AsyncClient = S3AsyncClient.builder()

.httpClient(crtAsyncHttpClient)

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.defaultsMode(DefaultsMode.IN_REGION)

.region(Region.US_EAST_1)

.build();

DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder()

.httpClient(crtAsyncHttpClient)

.credentialsProvider(EnvironmentVariableCredentialsProvider.create())

.defaultsMode(DefaultsMode.IN_REGION)

.region(Region.US_EAST_1)

.build();

// Requests completed: Close all service clients.

s3AsyncClient.close();

dynamoDbAsyncClient.close()

crtAsyncHttpClient.close(); // Explicitly close crtAsyncHttpClient.

Set the AWS CRT-based HTTP client as the default

For asynchronous operations in the AWS SDK for Java 2.x, you can replace the

NettyNioAsyncHttpClient as the default asynchronous HTTP client in your program with the

AwsCrtAsyncHttpClient.

You set this in your project’s Maven pom.xml ﬁle by excluding the dependency on the netty-nio-

client for each service client. Alternatively, you can set the default HTTP client by using a Java system

property when you run your app or in your application code.

Remove Netty from the project dependencies

The following pom.xml example removes the Netty-based HTTP client from the classpath so that the

AWS CRT-based HTTP client will be used instead.

62

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure the AWS CRT-based HTTP client

<aws.sdk.version>VERSION</aws.sdk.version>

</properties>

<groupId>software.amazon.awssdk</groupId>

<version>${aws.sdk.version}</version>

<groupId>software.amazon.awssdk</groupId>

<artifactId>netty-nio-client</artifactId>

</exclusion>

</exclusions>

</dependency>

<groupId>software.amazon.awssdk</groupId>

<artifactId>aws-crt-client</artifactId>

</dependency>

</dependencies>

</project>

Visit the Maven central repository for the latest VERSION value.

Note

If multiple service clients are declared in a pom.xml ﬁle, all require the exclusionsXML

element.

Set via Java system property

To use the AWS CRT-based HTTP client as the default HTTP for your application, you can set the

Java system property software.amazon.awssdk.http.async.service.impl to a value of

software.amazon.awssdk.http.crt.AwsCrtSdkHttpService.

To set during application startup, run a command similar to the following.

java app.jar -Dsoftware.amazon.awssdk.http.async.service.impl=\

software.amazon.awssdk.http.crt.AwsCrtSdkHttpService

Use the following code snippet to set the system property in your application code.

System.setProperty("software.amazon.awssdk.http.async.service.impl",

"software.amazon.awssdk.http.crt.AwsCrtSdkHttpService");

Note

You need to add a dependency on the aws-crt-client artifact in your poml.xml ﬁle when

you use a system property to conﬁgure the use of the AWS CRT-based HTTP client.

Advanced conﬁguration of AwsCrtAsyncHttpClient

You can use the AWS CRT-based HTTP client to conﬁgure various settings, including connection health

conﬁguration and maximum idle time. You can review the conﬁguration options available for the

AwsCrtAsyncHttpClient.

Connection health conﬁguration

You can conﬁgure connection health conﬁguration for the AWS CRT-based HTTP client using the

connectionHealthConfiguration method on the HTTP client builder.

63

AWS SDK for Java 2.x Developer Guide for version 2.x

Exception handling

The following example creates an S3AsyncClient that uses a AwsCrtAsyncHttpClient instance

conﬁgured with connection health conﬁguration and a maximum idle time for connections.

// Singleton: Use the s3AsyncClient for all requests.

S3AsyncClient s3AsyncClient = S3AsyncClient.builder()

.httpClientBuilder(AwsCrtAsyncHttpClient

.builder()

.connectionHealthConfiguration(builder -> builder

.minimumThroughputInBps(32000L)

.minimumThroughputTimeout(Duration.ofSeconds(3)))

.connectionMaxIdleTime(Duration.ofSeconds(5)))

.build();

// Perform work with s3AsyncClient.

// Requests complete: Close the service client.

s3AsyncClient.close();

HTTP/2 support

The HTTP/2 protocol is not yet supported in the AWS CRT-based HTTP client, but is planned for a future

release.

In the meantime, if you are using service clients that require HTTP/2 support such as the

KinesisAsyncClient or the TranscribeStreamingAsyncClient, consider using the NettyNioAsyncHttpClient

instead.

Proxy conﬁguration example

The following code snippet uses the proxy conﬁguration builder for the AWS CRT-based HTTP client.

SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()

.proxyConfiguration(ProxyConfiguration.builder()

.scheme("https")

.host("myproxy")

.port(1234)

.username("username")

.password("password")

.build())

.build();

The equivalent Java system properties for the proxy conﬁguration are shown in the following command

line snippet.

$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \

-Dhttps.proxyPassword=password -cp ... App

Important

To use any of the HTTPS proxy system properties, the scheme property must be set in code

to https. If the scheme property is not set in code, the scheme defaults to HTTP and the SDK

looks only for http.* system properties.

Exception handling for the AWS SDK for Java 2.x

Understanding how and when the AWS SDK for Java 2.x throws exceptions is important to building high-

quality applications using the SDK. The following sections describe the diﬀerent cases of exceptions that

are thrown by the SDK and how to handle them appropriately.

64

AWS SDK for Java 2.x Developer Guide for version 2.x

Why unchecked exceptions?

The AWS SDK for Java uses runtime (or unchecked) exceptions instead of checked exceptions for these

reasons:

• To allow developers ﬁne-grained control over the errors they want to handle without forcing them to

handle exceptional cases they aren’t concerned about (and making their code overly verbose)

• To prevent scalability issues inherent with checked exceptions in large applications

In general, checked exceptions work well on small scales, but can become troublesome as applications

grow and become more complex.

AwsServiceException (and subclasses)

AwsServiceException is the most common exception that you’ll experience when using the AWS

SDK for Java. AwsServiceException is a subclass of the more general SdkServiceException.

AwsServiceExceptions represent an error response from an AWS service. For example, if you try to

terminate an Amazon EC2 instance that doesn’t exist, Amazon EC2 will return an error response and all

the details of that error response will be included in the AwsServiceException that’s thrown.

When you encounter an AwsServiceException, you know that your request was successfully sent to

the AWS service but couldn’t be successfully processed. This can be because of errors in the request’s

parameters or because of issues on the service side.

AwsServiceException provides you with information such as:

• Returned HTTP status code

• Returned AWS error code

• Detailed error message from the service in the AwsErrorDetails class

• AWS request ID for the failed request

In most cases, a service-speciﬁc subclass of AwsServiceException is thrown to allow developers

ﬁne-grained control over handling error cases through catch blocks. The Java SDK API reference for

AwsServiceException displays the large number of AwsServiceException subclasses. Use the subclass

links to drill down to see the granular exceptions thrown by a service.

For example, the following links to the SDK API reference show the exception hierarchies for a few

common AWS services. The list of subclasses shown on each pages shows the speciﬁc exceptions that

your code can catch.

• Amazon S3

• DynamoDB

• Amazon SQS

To learn more about an exception, inspect the errorCode on the AwsErrorDetails object. You can use

the errorCode value to look up information in the service guide API. For example if an S3Exception is

caught and the AwsErrorDetails#errorCode() value is InvalidRequest, use the list of error codes

in the Amazon S3 API Reference to see more details.

SdkClientException

SdkClientException indicates that a problem occurred inside the Java client code, either while trying

to send a request to AWS or while trying to parse a response from AWS. An SdkClientException

65

AWS SDK for Java 2.x Developer Guide for version 2.x

Exceptions and retry behavior

is generally more severe than an SdkServiceException, and indicates a major problem that is

preventing the client from making service calls to AWS services. For example, the AWS SDK for Java

throws an SdkClientException if no network connection is available when you try to call an

operation on one of the clients.

Exceptions and retry behavior

The SDK for Java retries requests for several client-side exceptions and for HTTP status codes that it

receives from AWS service responses. These errors are handled as part of the legacy RetryMode that

service clients use by default. The Java API reference for RetryMode describes the various ways that you

can conﬁgure the mode.

To customize the exceptions and HTTP status codes that trigger automatic retries, conﬁgure

your service client with a RetryPolicy that adds RetryOnExceptionsCondition and

RetryOnStatusCodeCondition instances.

Logging with the SDK for Java 2.x

The AWS SDK for Java 2.x uses SLF4J, which is an abstraction layer that enables the use of any one of

several logging systems at runtime.

Supported logging systems include the Java Logging Framework and Apache Log4j 2, among others.

This topic shows you how to use Log4j 2 as the logging system for working with the SDK.

Log4j 2 conﬁguration ﬁle

You typically use a conﬁguration ﬁle, namedlog4j2.xml with Log4j 2. Example conﬁguration ﬁles are

shown below. To learn more about the values used in the conﬁguration ﬁle, see the manual for Log4j

conﬁguration.

Place the log4j2.xml ﬁle in the <project-dir>/src/main/resources directory when using

Maven.

The log4j2.xml conﬁguration ﬁle speciﬁes properties such as logging level, where logging output is

sent (for example, to a ﬁle or to the console), and the format of the output. The logging level speciﬁes

the level of detail that Log4j 2 outputs. Log4j 2 supports the concept of multiple logging hierarchies. The

logging level is set independently for each hierarchy. The main logging hierarchy that you use with the

AWS SDK for Java 2.x is software.amazon.awssdk.

Add logging dependency

To conﬁgure the Log4j 2 binding for SLF4J in your build ﬁle, use the following.

Maven

Add the following elements to your pom.xml ﬁle.

...

<groupId>org.apache.logging.log4j</groupId>

<version>VERSION</version>

</dependency>

...

66

AWS SDK for Java 2.x Developer Guide for version 2.x

SDK-speciﬁc errors and warnings

Gradle–Kotlin DSL

Add the following to your build.gradle.kts ﬁle.

...

dependencies {

...

implementation("org.apache.logging.log4j:log4j-slf4j2-impl:VERSION")

...

}

...

Use 2.20.0 for the minimum version of the log4j-slf4j2-impl artifact. For the latest version, use

the version published to Maven central. Replace VERSION with version you'll use.

SDK-speciﬁc errors and warnings

We recommend that you always leave the "software.amazon.awssdk" logger hierarchy set to "WARN"

to catch any important messages from the SDK's client libraries. For example, if the Amazon S3 client

detects that your application hasn’t properly closed an InputStream and could be leaking resources,

the S3 client reports it through a warning message to the logs. This also ensures that messages are

logged if the client has any problems handling requests or responses.

The following log4j2.xml ﬁle sets the rootLogger to "WARN", which causes warning and

error-level messages from all loggers in the application to be output, including those in the

"software.amazon.awssdk" hierarchy. Alternatively, you can explicitly set the "software.amazon.awssdk"

logger hierarchy to "WARN" if <Root level="ERROR"> is used.

Example Log4j2.xml conﬁguration ﬁle

This conﬁguration will log messages at the "ERROR" and "WARN" levels to the console for all logger

hierarchies.

</Console>

</Appenders>

</Root>

</Loggers>

</Configuration>

Request/response summary logging

Every request to an AWS service generates a unique AWS request ID that is useful if you run into an issue

with how an AWS service is handling a request. AWS request IDs are accessible programmatically through

SdkServiceException objects in the SDK for any failed service call, and can also be reported through

the "DEBUG" log level of the "software.amazon.awssdk.request" logger.

The following log4j2.xml ﬁle enables a summary of requests and responses.

67

AWS SDK for Java 2.x Developer Guide for version 2.x

Verbose wire logging

</Console>

</Appenders>

</Root>

</Loggers>

</Configuration>

Here is an example of the log output:

2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Sending Request:

DefaultSdkHttpFullRequest(httpMethod=POST, protocol=https, host=dynamodb.us-

east-1.amazonaws.com, encodedPath=/, headers=[amz-sdk-invocation-id, Content-Length,

Content-Type, User-Agent, X-Amz-Target], queryParameters=[])

2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Received successful

response: 200, Request ID: QS9DUMME2NHEDH8TGT9N5V53OJVV4KQNSO5AEMVJF66Q9ASUAAJG, Extended

Request ID: not available

If you are interested in only the request ID use <Logger

name="software.amazon.awssdk.requestId" level="DEBUG" />.

Verbose wire logging

It can be useful to see the exact requests and responses that the SDK for Java 2.x sends and receives. If

you need access to this information, you can temporarily enable it by adding the necessary conﬁguration

depending on the HTTP client the service client uses.

By default, synchronous service clients, such as the S3Client, use an underlying Apache HttpClient, and

asynchronous service clients, such as the S3AsyncClient, use a Netty non-blocking HTTP client.

Here is a breakdown of HTTP clients you can use for the two categories of service clients:

Synchronous HTTP Clients Asynchronous HTTP Clients

ApacheHttpClient (default) NettyNioAsyncHttpClient (default)

UrlConnectionHttpClient AwsCrtAsyncHttpClient

Consult the appropriate tab below for conﬁguration settings you need to add depending on the

underlying HTTP client.

Warning

We recommend you only use wire logging for debugging purposes. Disable it in your production

environments because it can log sensitive data. It logs the full request or response without

encryption, even for an HTTPS call. For large requests (e.g., to upload a ﬁle to Amazon S3) or

responses, verbose wire logging can also signiﬁcantly impact your application’s performance.

ApacheHttpClient

Add the "org.apache.http.wire" logger to the log4j2.xml conﬁguration ﬁle and set the level to

"DEBUG".

68

AWS SDK for Java 2.x Developer Guide for version 2.x

Verbose wire logging

The following log4j2.xml ﬁle turns on full wire logging for the Apache HttpClient.

</Console>

</Appenders>

</Root>

</Loggers>

</Configuration>

An additional Maven dependency on the log4j-1.2-api artifact is required for wire logging with

Apache since it uses 1.2 under the hood.

The full set of Maven dependencies for log4j 2, including wire logging for the Apache HTTP client

are shown in the following build ﬁle snippets.

Maven

...

...

<groupId>org.apache.logging.log4j</groupId>

<version>VERSION</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

...

<groupId>org.apache.logging.log4j</groupId>

</dependency>

<groupId>org.apache.logging.log4j</groupId>

</dependency>

...

Gradle–Kotlin DSL

...

dependencies {

...

implementation(platform("org.apache.logging.log4j:log4j-bom:VERSION"))

implementation("org.apache.logging.log4j:log4j-slf4j2-impl")

implementation("org.apache.logging.log4j:log4j-1.2-api")

69

AWS SDK for Java 2.x Developer Guide for version 2.x

Verbose wire logging

}

...

Use 2.20.0 for the minimum version of the log4j-bom artifact. For the latest version, use the

version published to Maven central. Replace VERSION with version you'll use.

UrlConnectionHttpClient

To log details for service clients that use the UrlConnectionHttpClient, ﬁrst create a

logging.properties ﬁle with the following contents:

handlers=java.util.logging.ConsoleHandler

java.util.logging.ConsoleHandler.level=FINEST

sun.net.www.protocol.http.HttpURLConnection.level=ALL

Set the following JVM system property with the full path of the logging.properties:

-Djava.util.logging.config.file=/full/path/to/logging.properties

This conﬁguration will log the only the headers of the request and response, for example:

<Request> FINE: sun.net.www.MessageHeader@35a9782c11 pairs: {GET /fileuploadtest

HTTP/1.1: null}{amz-sdk-invocation-id: 5f7e707e-4ac5-bef5-ba62-00d71034ffdc}

{amz-sdk-request: attempt=1; max=4}{Authorization: AWS4-HMAC-SHA256

Credential=<deleted>/20220927/us-east-1/s3/aws4_request, SignedHeaders=amz-sdk-

invocation-id;amz-sdk-request;host;x-amz-content-sha256;x-amz-date;x-amz-te,

Signature=e367fa0bc217a6a65675bb743e1280cf12fbe8d566196a816d948fdf0b42ca1a}{User-

Agent: aws-sdk-java/2.17.230 Mac_OS_X/12.5 OpenJDK_64-Bit_Server_VM/25.332-b08

Java/1.8.0_332 vendor/Amazon.com_Inc. io/sync http/UrlConnection cfg/retry-mode/

legacy}{x-amz-content-sha256: UNSIGNED-PAYLOAD}{X-Amz-Date: 20220927T133955Z}{x-amz-te:

append-md5}{Host: tkhill-test1.s3.amazonaws.com}{Accept: text/html, image/gif, image/

jpeg, *; q=.2, */*; q=.2}{Connection: keep-alive}

<Response> FINE: sun.net.www.MessageHeader@70a36a6611 pairs: {null: HTTP/1.1 200 OK}{x-

amz-id-2: sAFeZDOKdUMsBbkdjyDZw7P0oocb4C9KbiuzfJ6TWKQsGXHM/dFuOvr2tUb7Y1wEHGdJ3DSIxq0=}

{x-amz-request-id: P9QW9SMZ97FKZ9X7}{Date: Tue, 27 Sep 2022 13:39:57 GMT}{Last-

Modified: Tue, 13 Sep 2022 14:38:12 GMT}{ETag: "2cbe5ad4a064cedec33b452bebf48032"}

{x-amz-transfer-encoding: append-md5}{Accept-Ranges: bytes}{Content-Type: text/plain}

{Server: AmazonS3}{Content-Length: 67}

To see the request/response bodies, add -Djavax.net.debug=all to the JVM properties. This

additional property logs a great deal of information, including all SSL information.

Within the log console or log ﬁle, search for "GET" or "POST" to quickly go to the section of the

log containing actual requests and responses. Search for "Plaintext before ENCRYPTION" for

requests and "Plaintext after DECRYPTION" for responses to see the full text of the headers

and bodies.

NettyNioAsyncHttpClient

If your asynchronous service client uses the default NettyNioAsyncHttpClient, add two

additional loggers to your log4j2.xml ﬁle to log HTTP headers and request/response bodies.

Here is a complete log4j2.xml example:

70

AWS SDK for Java 2.x Developer Guide for version 2.x

Set the JVM TTL for DNS name lookups

</Console>

</Appenders>

</Root>

</Loggers>

</Configuration>

These settings log all header details and request/response bodies.

AwsCrtAsyncHttpClient

If you have conﬁgured your service client to use an instance of AwsCrtAsyncHttpClient, you can

log details by setting JVM system properties or programmatically.

Log to a ﬁle at "Debug" level

Using system properties:

-Daws.crt.log.level=Trace

-

Daws.crt.log.destination=File

-

Daws.crt.log.filename=<path

to file>

Programmatically:

import import software.amazon.awssdk.crt.Log;

// Execute this statement before constructing the SDK

service client.

Log.initLoggingToFile(Log.LogLevel.Trace, "<path to

file>");

Log to the console at "Debug" level

Using system properties:

-Daws.crt.log.level=Trace

-

Daws.crt.log.destination=Stdout

Programmatically:

import import software.amazon.awssdk.crt.Log;

// Execute this statement before constructing the SDK

service client.

Log.initLoggingToStdout(Log.LogLevel.Trace);

For security reasons, at the "Trace" level the AwsCrtAsyncHttpClient logs only response headers.

Request headers, request bodies, and response bodies are not logged.

Set the JVM TTL for DNS name lookups

The Java virtual machine (JVM) caches DNS name lookups. When the JVM resolves a hostname to an IP

address, it caches the IP address for a speciﬁed period of time, known as the time-to-live (TTL).

Because AWS resources use DNS name entries that occasionally change, we recommend that you

conﬁgure your JVM with a TTL value of no more than 60 seconds. This ensures that when a resource’s

IP address changes, your application will be able to receive and use the resource’s new IP address by

requerying the DNS.

71

AWS SDK for Java 2.x Developer Guide for version 2.x

How to set the JVM TTL

On some Java conﬁgurations, the JVM default TTL is set so that it will never refresh DNS entries until

the JVM is restarted. Thus, if the IP address for an AWS resource changes while your application is still

running, it won’t be able to use that resource until you manually restart the JVM and the cached IP

information is refreshed. In this case, it’s crucial to set the JVM’s TTL so that it will periodically refresh its

cached IP information.

Note

The default TTL can vary according to the version of your JVM and whether a security manager

is installed. Many JVMs provide a default TTL less than 60 seconds. If you’re using such a JVM

and not using a security manager, you can ignore the remainder of this topic.

How to set the JVM TTL

To modify the JVM’s TTL, set the networkaddress.cache.ttl property value. Use one of the following

methods, depending on your needs:

•

globally, for all applications that use the JVM. Set networkaddress.cache.ttl in the

$JAVA_HOME/jre/lib/security/java.security ﬁle:

networkaddress.cache.ttl=60

•

for your application only, set networkaddress.cache.ttl in your application’s initialization code:

java.security.Security.setProperty("networkaddress.cache.ttl" , "60");

Best practices for AWS SDK for Java 2.x

This section lists best practices for using the SDK for Java 2.x.

Topics

• Reuse an SDK client, if possible (p. 72)

• Close input streams from client operations (p. 72)

• Tune HTTP conﬁgurations based on performance tests (p. 73)

• Use OpenSSL for the Netty-based HTTP client (p. 73)

• Conﬁgure API timeouts (p. 73)

• Use metrics (p. 74)

Reuse an SDK client, if possible

Each SDK client maintains its own HTTP connection pool. A connection that already exists in the pool can

be reused by a new request to cut down the time to establish a new connection. We recommend sharing

a single instance of the client to avoid the overhead of having too many connection pools that aren't

used eﬀectively. All SDK clients are thread safe.

If you don't want to share a client instance, call close() on the instance to release the resources when

the client is not needed.

Close input streams from client operations

For streaming operations such as S3Client#getObject, if you are working with

ResponseInputStream directly, we recommend that you do the following:

72

AWS SDK for Java 2.x Developer Guide for version 2.x

Tune HTTP conﬁgurations

• Read all the data from the input stream as soon as possible.

• Close the input stream as soon as possible.

We make these recommendations because the input stream is a direct stream of data from the HTTP

connection and the underlying HTTP connection can't be reused until all data from the stream has been

read and the stream is closed. If these rules are not followed, the client can run out of resources by

allocating too many open, but unused, HTTP connections.

Tune HTTP conﬁgurations based on performance

tests

The SDK provides a set of default http conﬁgurations that apply to general use cases. We recommend

that customers tune HTTP conﬁgurations for their applications based on their use cases.

As a good starting point, the SDK oﬀers a smart conﬁguration defaults (p. 46) feature. This feature is

available starting with version 2.17.102. You choose a mode depending on your use case, which provides

sensible conﬁguration values.

Use OpenSSL for the Netty-based HTTP client

By default, the SDK's NettyNioAsyncHttpClient uses the JDK's default SSL implementation as the

SslProvider. Our testing found that OpenSSL performs better than JDK's default implementation. The

Netty community also recommends using OpenSSL.

To use OpenSSL, add netty-tcnative to your dependencies. For conﬁguration details, see the Netty

project documentation.

After you have netty-tcnative conﬁgured for your project, the NettyNioAsyncHttpClient

instance will automatically select OpenSSL. Alternatively, you can set the SslProvider explicitly using

the NettyNioAsyncHttpClient builder as shown in the following snippet.

NettyNioAsyncHttpClient.builder()

.sslProvider(SslProvider.OPENSSL)

.build();

Conﬁgure API timeouts

The SDK provides default values for some timeout options, such as connection timeout and socket

timeouts, but not for API call timeouts or individual API call attempt timeouts. It is a good practice to set

timeouts for both the individual attempts and the entire request. This will ensure your application fails

fast in an optimal way when there are transient issues that could cause request attempts to take longer

to complete or fatal network issues.

You can conﬁgure timeouts for all requests made by a service clients using

ClientOverrideConfiguration#apiCallAttemptTimeout and

ClientOverrideConfiguration#apiCallTimeout.

The following example shows the conﬁguration of an Amazon S3 client with custom timeout values.

S3Client.builder()

.overrideConfiguration(

b -> b.apiCallTimeout(Duration.ofSeconds(<custom value>))

.apiCallAttemptTimeout(Duration.ofMillis(<custom value>))

.build();

73

AWS SDK for Java 2.x Developer Guide for version 2.x

Use metrics

apiCallAttemptTimeout

This setting sets the amount of time for a single HTTP attempt, after which the API call can be

retried.

apiCallTimeout

The value for this property conﬁgures the amount of time for the entire execution, including all retry

attempts.

As an alternative to setting these timeout values on the service client, you

can use RequestOverrideConfiguration#apiCallTimeout() and

RequestOverrideConfiguration#apiCallAttemptTimeout() to conﬁgure a single request .

The following example conﬁgures a single listBuckets request with custom timeout values.

s3Client.listBuckets(lbr -> lbr.overrideConfiguration(

b -> b.apiCallTimeout(Duration.ofSeconds(<custom value>))

.apiCallAttemptTimeout(Duration.ofMillis(<custom value>))));

When you use these properties together, you set a hard limit on the total time spent on all attempts

across retries. You also set an individual HTTP request to fail fast on a slow request.

Use metrics

The SDK for Java can collect metrics (p. 159) for the service clients in your application. You can use

these metrics to identify performance issues, review overall usage trends, review service client exceptions

returned, or to dig in to understand a particular issue.

We recommend that you collect metrics, then analyze the Amazon CloudWatch Logs, in order to gain a

deeper understanding of your application's performance.

74

AWS SDK for Java 2.x Developer Guide for version 2.x

Asynchronous programming

Features of the AWS SDK for Java 2.x

This section provides information about the features of the AWS SDK for Java 2.x.

Topics

• Asynchronous programming (p. 75)

• DynamoDB Enhanced Client API in the AWS SDK for Java 2.x (p. 81)

• Working with HTTP/2 in the AWS SDK for Java (p. 159)

• Enable SDK metrics for the AWS SDK for Java (p. 159)

• Retrieving paginated results using the AWS SDK for Java 2.x (p. 164)

• AWS CRT-based S3 client (p. 169)

• Amazon S3 Transfer Manager (p. 171)

• Use waiters in the AWS SDK for Java 2.x (p. 177)

• IAM Policy Builder API (p. 179)

Asynchronous programming

The AWS SDK for Java 2.x features truly nonblocking asynchronous clients that implement high

concurrency across a few threads. The AWS SDK for Java 1.x has asynchronous clients that are wrappers

around a thread pool and blocking synchronous clients that don’t provide the full beneﬁt of nonblocking

I/O.

Synchronous methods block your thread’s execution until the client receives a response from the service.

Asynchronous methods return immediately, giving control back to the calling thread without waiting for

a response.

Because an asynchronous method returns before a response is available, you need a way to get the

response when it’s ready. The methods for asynchronous client in 2.x of the AWS SDK for Java return

CompletableFuture objects that allow you to access the response when it’s ready.

Non-streaming operations

For non-streaming operations, asynchronous method calls are similar to synchronous methods. However,

the asynchronous methods in the AWS SDK for Java return a CompletableFuture object that contains the

results of the asynchronous operation in the future.

Call the CompletableFuture whenComplete() method with an action to complete when the result

is available. CompletableFuture implements the Future interface, so you can also get the response

object by calling the get() method.

The following is an example of an asynchronous operation that calls a Amazon DynamoDB function to

get a list of tables, receiving a CompletableFuture that can hold a ListTablesResponse object. The

action deﬁned in the call to whenComplete() is done only when the asynchronous call is complete.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;

import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest;

import software.amazon.awssdk.services.dynamodb.model.ListTablesResponse;

import java.util.List;

75

AWS SDK for Java 2.x Developer Guide for version 2.x

Non-streaming operations

import java.util.concurrent.CompletableFuture;

Code

public class DynamoDBAsyncListTables {

public static void main(String[] args) throws InterruptedException {

// Create the DynamoDbAsyncClient object

Region region = Region.US_EAST_1;

DynamoDbAsyncClient client = DynamoDbAsyncClient.builder()

.region(region)

.build();

listTables(client);

}

public static void listTables(DynamoDbAsyncClient client) {

CompletableFuture<ListTablesResponse> response =

client.listTables(ListTablesRequest.builder()

.build());

// Map the response to another CompletableFuture containing just the table names

CompletableFuture<List<String>> tableNames =

response.thenApply(ListTablesResponse::tableNames);

// When future is complete (either successfully or in error) handle the response

tableNames.whenComplete((tables, err) -> {

try {

if (tables != null) {

tables.forEach(System.out::println);

} else {

// Handle error

err.printStackTrace();

}

} finally {

// Lets the application shut down. Only close the client when you are

completely done with it.

client.close();

}

});

tableNames.join();

}

The following code example shows you how to retrieve an Item from a table by using the Asynchronous

client. Invoke the getItem method of the DynamoDbAsyncClient and pass it a GetItemRequest object

with the table name and primary key value of the item you want. This is typically how you pass data that

the operation requires. In this example, notice that a String value is passed.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;

import software.amazon.awssdk.services.dynamodb.model.AttributeValue;

import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;

import java.util.HashMap;

import java.util.Map;

import java.util.Set;

import java.util.stream.Collectors;

import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;

76

AWS SDK for Java 2.x Developer Guide for version 2.x

Streaming operations

Code

public static void getItem(DynamoDbAsyncClient client, String tableName, String key,

String keyVal) {

HashMap<String, AttributeValue> keyToGet =

new HashMap<String, AttributeValue>();

keyToGet.put(key, AttributeValue.builder()

.s(keyVal).build());

try {

// Create a GetItemRequest instance

GetItemRequest request = GetItemRequest.builder()

.key(keyToGet)

.tableName(tableName)

.build();

// Invoke the DynamoDbAsyncClient object's getItem

java.util.Collection<AttributeValue> returnedItem =

client.getItem(request).join().item().values();

// Convert Set to Map

Map<String, AttributeValue> map =

returnedItem.stream().collect(Collectors.toMap(AttributeValue::s, s->s));

Set<String> keys = map.keySet();

for (String sinKey : keys) {

System.out.format("%s: %s\n", sinKey, map.get(sinKey).toString());

}

} catch (DynamoDbException e) {

System.err.println(e.getMessage());

System.exit(1);

}

See the complete example on GitHub.

Streaming operations

For streaming operations, you must provide an AsyncRequestBody to provide the content incrementally,

or an AsyncResponseTransformer to receive and process the response.

The following example uploads a ﬁle to Amazon S3 asynchronously by using the PutObject operation.

Imports

import software.amazon.awssdk.core.async.AsyncRequestBody;

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.s3.S3AsyncClient;

import software.amazon.awssdk.services.s3.model.PutObjectRequest;

import software.amazon.awssdk.services.s3.model.PutObjectResponse;

import java.nio.file.Paths;

import java.util.concurrent.CompletableFuture;

Code

/**

* To run this AWS code example, ensure that you have setup your development environment,

including your AWS credentials.

*

77

AWS SDK for Java 2.x Developer Guide for version 2.x

Streaming operations

* For information, see this documentation topic:

*

* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html

*/

public class S3AsyncOps {

public static void main(String[] args) {

final String USAGE = "\n" +

"Usage:\n" +

" S3AsyncOps <bucketName> <key> <path>\n\n" +

"Where:\n" +

" bucketName - the name of the Amazon S3 bucket (for example, bucket1).

\n\n" +

" key - the name of the object (for example, book.pdf). \n" +

" path - the local path to the file (for example, C:/AWS/book.pdf).

\n" ;

if (args.length != 3) {

System.out.println(USAGE);

System.exit(1);

}

String bucketName = args[0];

String key = args[1];

String path = args[2];

Region region = Region.US_WEST_2;

S3AsyncClient client = S3AsyncClient.builder()

.region(region)

.build();

PutObjectRequest objectRequest = PutObjectRequest.builder()

.bucket(bucketName)

.key(key)

.build();

// Put the object into the bucket

CompletableFuture<PutObjectResponse> future = client.putObject(objectRequest,

AsyncRequestBody.fromFile(Paths.get(path))

);

future.whenComplete((resp, err) -> {

try {

if (resp != null) {

System.out.println("Object uploaded. Details: " + resp);

} else {

// Handle error

err.printStackTrace();

}

} finally {

// Only close the client when you are completely done with it

client.close();

}

});

future.join();

}

The following example gets a ﬁle from Amazon S3 asynchronously by using the GetObject operation.

Imports

import software.amazon.awssdk.core.async.AsyncResponseTransformer;

78

AWS SDK for Java 2.x Developer Guide for version 2.x

Streaming operations

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.s3.S3AsyncClient;

import software.amazon.awssdk.services.s3.model.GetObjectRequest;

import software.amazon.awssdk.services.s3.model.GetObjectResponse;

import java.nio.file.Paths;

import java.util.concurrent.CompletableFuture;

Code

/**

* To run this AWS code example, ensure that you have setup your development environment,

including your AWS credentials.

*

* For information, see this documentation topic:

*

* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html

*/

public class S3AsyncStreamOps {

public static void main(String[] args) {

final String USAGE = "\n" +

"Usage:\n" +

" S3AsyncStreamOps <bucketName> <objectKey> <path>\n\n" +

"Where:\n" +

" bucketName - the name of the Amazon S3 bucket (for example, bucket1).

\n\n" +

" objectKey - the name of the object (for example, book.pdf). \n" +

" path - the local path to the file (for example, C:/AWS/book.pdf).

\n" ;

if (args.length != 3) {

System.out.println(USAGE);

System.exit(1);

}

String bucketName = args[0];

String objectKey = args[1];

String path = args[2];

Region region = Region.US_WEST_2;

S3AsyncClient client = S3AsyncClient.builder()

.region(region)

.build();

GetObjectRequest objectRequest = GetObjectRequest.builder()

.bucket(bucketName)

.key(objectKey)

.build();

CompletableFuture<GetObjectResponse> futureGet = client.getObject(objectRequest,

AsyncResponseTransformer.toFile(Paths.get(path)));

futureGet.whenComplete((resp, err) -> {

try {

if (resp != null) {

System.out.println("Object downloaded. Details: "+resp);

} else {

err.printStackTrace();

}

} finally {

// Only close the client when you are completely done with it

client.close();

}

79

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced operations

});

futureGet.join();

}

Advanced operations

The AWS SDK for Java 2.x uses Netty, an asynchronous event-driven network application framework, to

handle I/O threads. The AWS SDK for Java 2.x creates an ExecutorService behind Netty, to complete

the futures returned from the HTTP client request through to the Netty client. This abstraction reduces

the risk of an application breaking the async process if developers choose to stop or sleep threads. By

default, each asynchronous client creates a threadpool based on the number of processors and manages

the tasks in a queue within the ExecutorService.

Advanced users can specify their thread pool size when creating an asynchronous client using the

following option when building.

Code

S3AsyncClient clientThread = S3AsyncClient.builder()

.asyncConfiguration(

b -> b.advancedOption(SdkAdvancedAsyncClientOption

.FUTURE_COMPLETION_EXECUTOR,

Executors.newFixedThreadPool(10)

)

.build();

To optimize performance, you can manage your own thread pool executor, and include it when

conﬁguring your client.

ThreadPoolExecutor executor = new ThreadPoolExecutor(50, 50,

10, TimeUnit.SECONDS,

new LinkedBlockingQueue<>(<custom_value>),

new ThreadFactoryBuilder()

.threadNamePrefix("sdk-async-response").build());

// Allow idle core threads to time out

executor.allowCoreThreadTimeOut(true);

S3AsyncClient clientThread = S3AsyncClient.builder()

.asyncConfiguration(

b -> b.advancedOption(SdkAdvancedAsyncClientOption

.FUTURE_COMPLETION_EXECUTOR,

executor

)

.build();

If you prefer to not use a thread pool, at all, use Runnable::run instead of using a thread pool executor.

S3AsyncClient clientThread = S3AsyncClient.builder()

.asyncConfiguration(

b -> b.advancedOption(SdkAdvancedAsyncClientOption

.FUTURE_COMPLETION_EXECUTOR,

Runnable::run

)

.build();

80

AWS SDK for Java 2.x Developer Guide for version 2.x

DynamoDB Enhanced Client API

DynamoDB Enhanced Client API in the AWS SDK

for Java 2.x

The DynamoDB Enhanced Client API is a high-level library that is the successor to the DynamoDBMapper

class of in the SDK for Java v1.x. It oﬀers a straightforward way to map client-side classes to DynamoDB

tables. You deﬁne the relationships between tables and their corresponding model classes in your code.

After you deﬁne those relationships, you can intuitively perform various create, read, update, or delete

(CRUD) operations on tables or items in DynamoDB.

The DynamoDB Enhanced Client API also includes the Enhanced Document API that enables you to work

with document-type items that do not follow a deﬁned schema.

The DynamoDB Enhanced Client API is discussed in the following topics.

• Get Started using the DynamoDB Enhanced Client API (p. 81)

• Basics of the DynamoDB Enhanced Client API (p. 87)

• Extensions (p. 123)

• Advanced table schema features (p. 126)

• Enhanced Document API for DynamoDB (p. 148)

• Non-blocking asynchronous operations (p. 157)

• Data class annotations (p. 157)

Get Started using the DynamoDB Enhanced Client

API

The following tutorial introduces you to fundamentals that you need to work with the DynamoDB

Enhanced Client API.

Add dependencies

To begin working with the DynamoDB Enhanced Client API in your project, add a dependency on the

dynamodb-enhanced Maven artifact. This is shown in the following examples.

Maven

<groupId>software.amazon.awssdk</groupId>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>dynamodb-enhanced</artifactId>

</dependency>

</dependencies>

81

AWS SDK for Java 2.x Developer Guide for version 2.x

Get started

...

</project>

Perform a search of the Maven central repository for the latest version and replace <VERSION> with

this value.

Gradle

repositories {

mavenCentral()

}

dependencies {

implementation(platform("software.amazon.awssdk:bom:<VERSION>"))

implementation("software.amazon.awssdk:dynamodb-enhanced")

...

}

Perform a search of the Maven central repository for the latest version and replace <VERSION> with

this value.

Generate a TableSchema

A TableSchema enables the enhanced client to map DynamoDB attribute values to and from your

client-side classes. In this tutorial, you learn about TableSchemas derived from a static data class and

generated from code by using a builder.

Use an annotated data class

The SDK for Java 2.x includes a set of annotations that you can use with a data class to quickly generate

a TableSchema for mapping your classes to tables.

Start by creating a data class that conforms to the JavaBean speciﬁcation. The speciﬁcation requires that

a class has a no-argument public constructor and has getters and setters for each attribute in the class.

Include a class-level annotation to indicate that the data class is a DynamoDbBean. Also, at a minimum,

include a DynamoDbPartitionKey annotation on the getter or setter for the primary key attribute.

Note

The term property is normally used for a value encapsulated in a JavaBean. However, this

guide uses the term attribute instead, to be consistent with the terminology used by

DynamoDB.

The following Customer class shows the annotations that link the class deﬁnition to the DynamoDB

table.

Customer class

package org.example.tests.model;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSortKey;

import java.time.Instant;

@DynamoDbBean

public class Customer {

private String id;

82

AWS SDK for Java 2.x Developer Guide for version 2.x

Get started

private String name;

private String email;

private Instant regDate;

@DynamoDbPartitionKey

public String getId() { return this.id; }

public void setId(String id) { this.id = id; }

public String getCustName() { return this.name; }

public void setCustName(String name) { this.name = name; }

@DynamoDbSortKey

public String getEmail() { return this.email; }

public void setEmail(String email) { this.email = email; }

public Instant getRegistrationDate() { return this.regDate; }

public void setRegistrationDate(Instant registrationDate) { this.regDate =

registrationDate; }

@Override

public String toString() {

return "Customer [id=" + id + ", name=" + name + ", email=" + email

+ ", regDate=" + regDate + "]";

}

After you have created an annotated data class, use it to create the TableSchema, as shown in the

following snippet.

static final TableSchema<Customer> customerTableSchema =

TableSchema.fromBean(Customer.class);

A TableSchema is designed to be static and immutable. You can usually instantiate it at class-load time.

The static TableSchema.fromBean() factory method introspects the bean to generate the mapping of

data class attributes to and from DynamoDB attributes.

For an example of working with a data model made up of several data classes, see the Person class in

the ??? (p. 136) section.

Use a builder

You can skip the cost of bean introspection if you deﬁne the table schema in code. If you code the

schema, your class does not need to follow JavaBean naming standards nor does it need to be

annotated. The following example uses a builder and is equivalent to the Customer class example that

uses annotations.

static final TableSchema<Customer> customerTableSchema =

TableSchema.builder(Customer.class)

.newItemSupplier(Customer::new)

.addAttribute(String.class, a -> a.name("id")

.getter(Customer::getId)

.setter(Customer::setId)

.tags(StaticAttributeTags.primaryPartitionKey()))

.addAttribute(String.class, a -> a.name("email")

.getter(Customer::getEmail)

.setter(Customer::setEmail)

83

AWS SDK for Java 2.x Developer Guide for version 2.x

Get started

.tags(StaticAttributeTags.primarySortKey()))

.addAttribute(String.class, a -> a.name("name")

.getter(Customer::getCustName)

.setter(Customer::setCustName))

.addAttribute(Instant.class, a -> a.name("registrationDate")

.getter(Customer::getRegistrationDate)

.setter(Customer::setRegistrationDate))

.build();

Create an enhanced client and DynamoDbTable

Create an enhanced client

The DynamoDbEnhancedClient class or its asynchronous counterpart, DynamoDbEnhancedAsyncClient,

is the entry point to working with the DynamoDB Enhanced Client API.

The enhanced client requires a standard DynamoDbClient to perform work. The API oﬀers two ways to

create a DynamoDbEnhancedClient instance. The ﬁrst option, shown in the following snippet, creates a

standard DynamoDbClient with default settings picked up from conﬁguration settings.

DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create();

If you want to conﬁgure the underlying standard client, you can supply it to the enhanced client's builder

method as shown in the following snippet.

DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()

.dynamoDbClient(

// Configure an instance of the standard client.

DynamoDbClient.builder()

.region(Region.US_EAST_1)

.credentialsProvider(ProfileCredentialsProvider.create())

.build())

.build();

Create a DynamoDbTable instance

Think of a DynamoDbTable as the client-side representation of a DynamoDB table that uses the

mapping functionality provided by a TableSchema. The DyanamoDbTable class provides methods for

CRUD operations that let you interact with a single DynamoDB table.

DynamoDbTable<T> is a generic class that takes a single type argument, whether it is a custom class or

an EnhancedDocument when working with document-type items. This argument type establishes the

relationship between the class that you use and the single DynamoDB table.

Use the table() factory method of the DynamoDbEnhancedClient to create a DynamoDbTable

instance as shown in the following snippet.

static final DynamoDbTable<Customer> customerTable =

enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));

DynamoDbTable instances are candidates for singletons because they are immutable and can be used

throughout your application.

Your code now has an in-memory representation of a DynamoDB table that can store Customer

instances. The actual DynamoDB table might or might not exist. If the table named Customer already

84

AWS SDK for Java 2.x Developer Guide for version 2.x

Get started

exists, you can begin performing CRUD operations against it. If it doesn't exist, use the DynamoDbTable

instance to create the table as discussed in the next section.

Create a DynamoDB table if needed

After you have created a DynamoDbTable instance, use it to perform a one-time creation of a table in

DynamoDB.

Create table example code

The following example creates a DynamoDB table based on the Customer data class.

This example creates a DynamoDB table with the name Customer—identical to the class name—but the

table name can be something else. Whatever you name the table, you must use this name in additional

applications to work with the table. Supply this name to the table() method anytime you create

another DynamoDbTable object in order to work with the underlying DynamoDB table.

The Java lambda parameter, builder, passed to the createTable method lets you customize the

table. In this example, provisioned throughput is conﬁgured. If you want to use default settings when

you create a table, skip the builder as shown in the following snippet.

customerDynamoDbTable.createTable();

When default settings are used, values for provisioned throughput are not set. Instead, the billing mode

for the table is set to on-demand.

The example also uses a DynamoDbWaiter before attempting to print out the table name received in

the response. The creation of a table takes some time. Therefore, using a waiter means you don't have to

write logic that polls the DynamoDB service to see if the table exists before using the table.

Imports

import com.example.dynamodb.Customer;

import software.amazon.awssdk.core.internal.waiters.ResponseOrException;

import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;

import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;

import software.amazon.awssdk.enhanced.dynamodb.TableSchema;

import software.amazon.awssdk.services.dynamodb.model.DescribeTableResponse;

import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;

Code

public static void createCustomerTable(DynamoDbTable<Customer> customerDynamoDbTable,

DynamoDbClient dynamoDbClient) {

// Create the DynamoDB table by using the 'customerDynamoDbTable' DynamoDbTable

instance.

customerDynamoDbTable.createTable(builder -> builder

.provisionedThroughput(b -> b

.readCapacityUnits(10L)

.writeCapacityUnits(10L)

.build())

);

// The 'dynamoDbClient' instance that's passed to the builder for the DynamoDbWaiter is

the same instance

// that was passed to the builder of the DynamoDbEnhancedClient instance used to create

the 'customerDynamoDbTable'.

// This means that the same Region that was configured on the standard 'dynamoDbClient'

instance is used for all service clients.

85

AWS SDK for Java 2.x Developer Guide for version 2.x

Get started

try (DynamoDbWaiter waiter = DynamoDbWaiter.builder().client(dynamoDbClient).build())

{ // DynamoDbWaiter is Autocloseable

ResponseOrException<DescribeTableResponse> response = waiter

.waitUntilTableExists(builder -> builder.tableName("Customer").build())

.matched();

DescribeTableResponse tableDescription = response.response().orElseThrow(

() -> new RuntimeException("Customer table was not created."));

// The actual error can be inspected in response.exception()

logger.info("Customer table was created.");

}

Note

A DynamoDB table's attribute names begin with a lowercase letter when the table is generated

from a data class. If you want the table's attribute name to begin with an uppercase letter, use

the @DynamoDbAttribute(NAME) annotation (p. 127) and provide the name you want as a

parameter.

Perform operations

After the table is created, use the DynamoDbTable instance to perform operations against the

DynamoDB table.

In the following example, a singleton DynamoDbTable<Customer> is passed as a parameter along with

a Customer data class (p. 82) instance to add a new item to the table.

public static void putItemExample(DynamoDbTable<Customer> customerTable, Customer

customer){

logger.info(customer.toString());

customerTable.putItem(customer);

}

Customer object

Customer customer = new Customer();

customer.setId("1");

customer.setCustName("Customer Name");

customer.setEmail("[email protected]");

customer.setRegistrationDate(Instant.parse("2023-07-03T10:15:30.00Z"));

Before sending the customer object to the DynamoDB service, log the output of the object's

toString() method to compare it to what the enhanced client sends.

Customer [id=1, name=Customer Name, [email protected],

regDate=2023-07-03T10:15:30Z]

Wire-level logging shows the payload of the generated request. The enhanced client generated the low-

level representation from the data class. The regDate attribute, which is an Instant type in Java, is

represented as a DynamoDB string.

{

"TableName": "Customer",

"Item": {

"registrationDate": {

"S": "2023-07-03T10:15:30Z"

},

"id": {

"S": "1"

86

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

},

"custName": {

"S": "Customer Name"

},

"email": {

"S": "[email protected]"

}

Work with an existing table

The previous section showed how to create a DynamoDB table starting with a Java data class. If you

already have an existing table and want to use the features of the enhanced client, you can create a

Java data class to work with the table. You need to examine the DynamoDB table and add the necessary

annotations to the data class.

Before you work with an existing table, call the DynamoDbEnhanced.table() method. This was done

in the previous example with the following statement.

DynamoDbTable<Customer> customerTable = enhancedClient.table("Customer",

TableSchema.fromBean(Customer.class));

After the DynamoDbTable instance is returned, you can begin working right away with the underlying

table. You do not need to recreate the table by calling the DynamoDbTable.createTable() method.

The following example demonstrates this by immediately retrieving a Customer instance from the

DynamoDB table.

DynamoDbTable<Customer> customerTable = enhancedClient.table("Customer",

TableSchema.fromBean(Customer.class));

// The Customer table exists already and has an item with a primary key value of "1" and a

sort key value of "[email protected]".

customerTable.getItem(

Key.builder().

partitionValue("1").

sortValue("[email protected]").build());

Important

The table name used in the table() method must match the existing DynamoDB table name.

Basics of the DynamoDB Enhanced Client API

This topic discusses the basic features of the DynamoDB Enhanced Client API and compares it to the

standard DynamoDB client API.

If you are new to the DynamoDB Enhanced Client API, we recommend that you go through the

introductory tutorial (p. 81) to familiarize yourself with fundamental classes.

DynamoDB items in Java

DynamoDB tables store items. Depending on your use case, items on the Java side can take the form of

statically structured data or structures created dynamically.

If your use case calls for items with a consistent set of attributes, use annotated classes (p. 82) or use

a builder (p. 83) to generate the appropriate statically-typed TableSchema.

87

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

Alternatively, if you need to store items that consist of varying structures, create a

DocumentTableSchema. DocumentTableSchema is part of the Enhanced Document API (p. 148) and

requires only a statically-typed primary key and works with EnhancedDocument instances to hold the

data elements. The Enhanced Document API is covered in another topic. (p. 148)

Attribute types

Although DynamoDB supports a small number of attribute types compared to the rich type system of

Java, the DynamoDB Enhanced Client API provides mechanisms to convert members of a Java class to

and from DynamoDB attribute types.

By default, the DynamoDB Enhanced Client API supports attribute converters for a large number of

types, such as Integer, String, BigDecimal, and Instant. The list appears in the known implementing

classes of the AttributeConverter interface. The list includes many types and collections such as maps,

lists, and sets.

To store the data for an attribute type that isn't supported by default or doesn't conform to the

JavaBean convention, you can write a custom AttributeConverter implementation to do the

conversion. See the attribute conversion section for an example (p. 129).

To store the data for an attribute type whose class conforms to the Java beans speciﬁcation (or an

immutable data class (p. 94)), you can take two approaches.

•

If you have access to the source ﬁle, you can annotate the class with @DynamoDbBean (or

@DynamoDbImmutable). The section that discusses nested attributes shows examples (p. 139) of

using annotated classes.

• If do not have access to the source ﬁle of the JavaBean data class for the attribute (or you don't

want to annotate the source ﬁle of a class that you do have access to), then you can use the builder

approach. This creates a table schema without deﬁning the keys. Then, you can nest this table

schema inside another table schema to perform the mapping. The nested attribute section has an

example (p. 139) showing use of nested schemas.

Java primitive type values

Although the enhanced client can work with attributes of primitive types, we encourage the use of object

types because you cannot represent null values with primitive types.

Null values

When you use the putItem API, the enhanced client does not include null-valued attributes of a

mapped data object in the request to DynamoDB.

For updateItem requests, null-valued attributes are removed from the item on the database. If you

intend to update some attribute values and keep the other unchanged, either copy the values of other

attributes that should not be changed or use the ignoreNull() method on the update builder.

The following example demonstrates ignoreNulls() for the updateItem() method.

public void updateItemNullsExample(){

Customer customer = new Customer();

customer.setCustName("CustName");

customer.setEmail("email");

customer.setId("1");

customer.setRegistrationDate(Instant.now());

88

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

// Put item with values for all attributes.

customerDynamoDbTable.putItem(customer);

// Create a Customer instance with the same id value, but a different name value.

// Do not set the 'registrationDate' attribute.

Customer custForUpdate = new Customer();

custForUpdate.setCustName("NewName");

custForUpdate.setEmail("email");

custForUpdate.setId("1");

// Update item without setting the registrationDate attribute.

customerDynamoDbTable.updateItem(b -> b

.item(custForUpdate)

.ignoreNulls(Boolean.TRUE));

Customer updatedWithNullsIgnored = customerDynamoDbTable.getItem(customer);

// registrationDate value is unchanged.

logger.info(updatedWithNullsIgnored.toString());

customerDynamoDbTable.updateItem(custForUpdate);

Customer updatedWithNulls = customerDynamoDbTable.getItem(customer);

// registrationDate value is null because ignoreNulls() was not used.

logger.info(updatedWithNulls.toString());

}

// Logged lines.

Customer [id=1, custName=NewName, email=email, registrationDate=2023-04-05T16:32:32.056Z]

Customer [id=1, custName=NewName, email=email, registrationDate=null]

DynamoDB Enhanced Client basic methods

Basic methods of the enhanced client map to the DynamoDB service operations that they're named after.

The following examples show the simplest variation of each method. You can customize each method by

passing in an enhanced request object. Enhanced request objects oﬀer most of the features available in

the standard DynamoDB client. They are fully documented in the AWS SDK for Java 2.x API Reference.

The example uses the the section called “Customer class” (p. 82) shown previously.

// CreateTable

customerTable.createTable();

// GetItem

Customer customer = customerTable.getItem(Key.builder().partitionValue("a123").build());

// UpdateItem

Customer updatedCustomer = customerTable.updateItem(customer);

// PutItem

customerTable.putItem(customer);

// DeleteItem

Customer deletedCustomer =

customerTable.deleteItem(Key.builder().partitionValue("a123").sortValue(456).build());

// Query

PageIterable<Customer> customers = customerTable.query(keyEqualTo(k ->

k.partitionValue("a123")));

// Scan

PageIterable<Customer> customers = customerTable.scan();

// BatchGetItem

89

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

BatchGetResultPageIterable batchResults =

enhancedClient.batchGetItem(r -> r.addReadBatch(ReadBatch.builder(Customer.class)

.mappedTableResource(customerTable)

.addGetItem(key1)

.addGetItem(key2)

.addGetItem(key3)

.build()));

// BatchWriteItem

batchResults = enhancedClient.batchWriteItem(r ->

r.addWriteBatch(WriteBatch.builder(Customer.class)

.mappedTableResource(customerTable)

.addPutItem(customer)

.addDeleteItem(key1)

.build()));

// TransactGetItems

transactResults = enhancedClient.transactGetItems(r -> r.addGetItem(customerTable, key1)

.addGetItem(customerTable, key2));

// TransactWriteItems

enhancedClient.transactWriteItems(r -> r.addConditionCheck(customerTable,

i -> i.key(orderKey)

.conditionExpression(conditionExpression))

.addUpdateItem(customerTable, customer)

.addDeleteItem(customerTable, key));

Compare DynamoDB Enhanced Client to standard DynamoDB

client

Both DynamoDB client APIs—standard and enhanced—let you work with DynamoDB tables to perform

CRUD (create, read, update and delete) data-level operations. The diﬀerence between the client APIs is

how that is accomplished. Using the standard client, you work directly with low-level data attributes. The

enhanced client API uses familiar Java classes and maps to the low-level API behind the scenes.

While both client APIs support data-level operations, the standard DynamoDB client also supports

resource-level operations. Resource-level operations manage the database, such as creating backups,

listing tables, and updating tables. The enhanced client API supports a select number of resource-level

operations such as creating, describing, and deleting tables.

To illustrate the diﬀerent approaches used by the two client APIs, the following code examples show the

creation of the same ProductCatalog table using the standard client and the enhanced client.

Compare: Create a table using the standard DynamoDB client

DependencyFactory.dynamoDbClient().createTable(builder -> builder

.tableName(TABLE_NAME)

.attributeDefinitions(

b -> b.attributeName("id").attributeType(ScalarAttributeType.N),

b -> b.attributeName("title").attributeType(ScalarAttributeType.S),

b -> b.attributeName("isbn").attributeType(ScalarAttributeType.S)

)

.keySchema(

builder1 -> builder1.attributeName("id").keyType(KeyType.HASH),

builder2 -> builder2.attributeName("title").keyType(KeyType.RANGE)

)

.globalSecondaryIndexes(builder3 -> builder3

.indexName("products_by_isbn")

.keySchema(builder2 -> builder2

90

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

.attributeName("isbn").keyType(KeyType.HASH))

.projection(builder2 -> builder2

.projectionType(ProjectionType.INCLUDE)

.nonKeyAttributes("price", "authors"))

.provisionedThroughput(builder4 -> builder4

.writeCapacityUnits(5L).readCapacityUnits(5L))

)

.provisionedThroughput(builder1 -> builder1

.readCapacityUnits(5L).writeCapacityUnits(5L))

);

Compare: Create a table using the DynamoDB Enhanced Client

DynamoDbEnhancedClient enhancedClient = DependencyFactory.enhancedClient();

productCatalog = enhancedClient.table(TABLE_NAME,

TableSchema.fromImmutableClass(ProductCatalog.class));

productCatalog.createTable(b -> b

.provisionedThroughput(b1 -> b1.readCapacityUnits(5L).writeCapacityUnits(5L))

.globalSecondaryIndices(b2 -> b2.indexName("products_by_isbn")

.projection(b4 -> b4

.projectionType(ProjectionType.INCLUDE)

.nonKeyAttributes("price", "authors"))

.provisionedThroughput(b3 ->

b3.writeCapacityUnits(5L).readCapacityUnits(5L))

)

);

The enhanced client uses the following annotated data class. The DynamoDB Enhanced Client maps Java

data types to DynamoDB data types for less verbose code that is easier to follow. ProductCatalog is an

example of using an immutable class with the DynamoDB Enhanced Client. The use of Immutable classes

for mapped data classes is discussed later (p. 94) in this topic.

ProductCatalog class

package org.example.tests.model;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbIgnore;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbImmutable;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;

import

software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondaryPartitionKey;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSortKey;

import java.math.BigDecimal;

import java.util.Objects;

import java.util.Set;

@DynamoDbImmutable(builder = ProductCatalog.Builder.class)

public class ProductCatalog implements Comparable<ProductCatalog> {

private Integer id;

private String title;

private String isbn;

private Set<String> authors;

private BigDecimal price;

private ProductCatalog(Builder builder){

this.authors = builder.authors;

this.id = builder.id;

this.isbn = builder.isbn;

this.price = builder.price;

this.title = builder.title;

91

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

}

public static Builder builder(){ return new Builder(); }

@DynamoDbPartitionKey

public Integer id() { return id; }

@DynamoDbSortKey

public String title() { return title; }

@DynamoDbSecondaryPartitionKey(indexNames = "products_by_isbn")

public String isbn() { return isbn; }

public Set<String> authors() { return authors; }

public BigDecimal price() { return price; }

public static final class Builder {

private Integer id;

private String title;

private String isbn;

private Set<String> authors;

private BigDecimal price;

private Builder(){}

public Builder id(Integer id) { this.id = id; return this; }

public Builder title(String title) { this.title = title; return this; }

public Builder isbn(String ISBN) { this.isbn = ISBN; return this; }

public Builder authors(Set<String> authors) { this.authors = authors; return this; }

public Builder price(BigDecimal price) { this.price = price; return this; }

public ProductCatalog build() { return new ProductCatalog(this); }

}

@Override

public String toString() {

final StringBuffer sb = new StringBuffer("ProductCatalog{");

sb.append("id=").append(id);

sb.append(", title='").append(title).append('\'');

sb.append(", isbn='").append(isbn).append('\'');

sb.append(", authors=").append(authors);

sb.append(", price=").append(price);

sb.append('}');

return sb.toString();

}

@Override

public boolean equals(Object o) {

if (this == o) return true;

if (o == null || getClass() != o.getClass()) return false;

ProductCatalog that = (ProductCatalog) o;

return id.equals(that.id) && title.equals(that.title) && Objects.equals(isbn,

that.isbn) && Objects.equals(authors, that.authors) && Objects.equals(price, that.price);

}

@Override

public int hashCode() {

return Objects.hash(id, title, isbn, authors, price);

}

@Override

@DynamoDbIgnore

public int compareTo(ProductCatalog other) {

if (this.id.compareTo(other.id) != 0){

return this.id.compareTo(other.id);

} else {

return this.title.compareTo(other.title);

}

92

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

}

The following two code examples of a batch write illustrate the verboseness and lack of type safety

when using the standard client as opposed to the enhanced client.

Compare: Batch write using the standard DynamoDB client

public static void batchWriteStandard(DynamoDbClient dynamoDbClient, String tableName)

{

Map<String, AttributeValue> catalogItem = Map.of(

"authors", AttributeValue.builder().ss("a", "b").build(),

"id", AttributeValue.builder().n("1").build(),

"isbn", AttributeValue.builder().s("1-565-85698").build(),

"title", AttributeValue.builder().s("Title 1").build(),

"price", AttributeValue.builder().n("52.13").build());

Map<String, AttributeValue> catalogItem2 = Map.of(

"authors", AttributeValue.builder().ss("a", "b", "c").build(),

"id", AttributeValue.builder().n("2").build(),

"isbn", AttributeValue.builder().s("1-208-98073").build(),

"title", AttributeValue.builder().s("Title 2").build(),

"price", AttributeValue.builder().n("21.99").build());

Map<String, AttributeValue> catalogItem3 = Map.of(

"authors", AttributeValue.builder().ss("g", "k", "c").build(),

"id", AttributeValue.builder().n("3").build(),

"isbn", AttributeValue.builder().s("7-236-98618").build(),

"title", AttributeValue.builder().s("Title 3").build(),

"price", AttributeValue.builder().n("42.00").build());

Set<WriteRequest> writeRequests = Set.of(

WriteRequest.builder().putRequest(b -> b.item(catalogItem)).build(),

WriteRequest.builder().putRequest(b -> b.item(catalogItem2)).build(),

WriteRequest.builder().putRequest(b -> b.item(catalogItem3)).build());

Map<String, Set<WriteRequest>> productCatalogItems = Map.of(

"ProductCatalog", writeRequests);

BatchWriteItemResponse response = dynamoDbClient.batchWriteItem(b ->

b.requestItems(productCatalogItems));

logger.info("Unprocessed items: " + response.unprocessedItems().size());

}

Compare: Batch write using the DynamoDB Enhanced Client

public static void batchWriteEnhanced(DynamoDbTable<ProductCatalog> productCatalog) {

ProductCatalog prod = ProductCatalog.builder()

.id(1)

.isbn("1-565-85698")

.authors(new HashSet<>(Arrays.asList("a", "b")))

.price(BigDecimal.valueOf(52.13))

.title("Title 1")

.build();

ProductCatalog prod2 = ProductCatalog.builder()

.id(2)

.isbn("1-208-98073")

.authors(new HashSet<>(Arrays.asList("a", "b", "c")))

.price(BigDecimal.valueOf(21.99))

.title("Title 2")

.build();

93

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

ProductCatalog prod3 = ProductCatalog.builder()

.id(3)

.isbn("7-236-98618")

.authors(new HashSet<>(Arrays.asList("g", "k", "c")))

.price(BigDecimal.valueOf(42.00))

.title("Title 3")

.build();

BatchWriteResult batchWriteResult = DependencyFactory.enhancedClient()

.batchWriteItem(b -> b.writeBatches(

WriteBatch.builder(ProductCatalog.class)

.mappedTableResource(productCatalog)

.addPutItem(prod).addPutItem(prod2).addPutItem(prod3)

.build()

));

logger.info("Unprocessed items: " +

batchWriteResult.unprocessedPutItemsForTable(productCatalog).size());

}

Work with immutable data classes

The mapping feature of the DynamoDB Enhanced Client API works with immutable data classes. An

immutable class has only getters and requires a builder class that the SDK uses to create instances of

the class. Instead of using the @DynamoDbBean annotation as shown in the Customer class (p. 82),

immutable classes use the @DynamoDbImmutable annotation, which takes a parameter that indicates

the builder class to use.

The following class is an immutable version of Customer.

package org.example.tests.model.immutable;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbImmutable;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;

import

software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondaryPartitionKey;

import

software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondarySortKey;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSortKey;

import java.time.Instant;

@DynamoDbImmutable(builder = CustomerImmutable.Builder.class)

public class CustomerImmutable {

private final String id;

private final String name;

private final String email;

private final Instant regDate;

private CustomerImmutable(Builder b) {

this.id = b.id;

this.email = b.email;

this.name = b.name;

this.regDate = b.regDate;

}

// This method will be automatically discovered and used by the TableSchema.

public static Builder builder() { return new Builder(); }

@DynamoDbPartitionKey

public String id() { return this.id; }

@DynamoDbSortKey

public String email() { return this.email; }

94

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

@DynamoDbSecondaryPartitionKey(indexNames = "customers_by_name")

public String name() { return this.name; }

@DynamoDbSecondarySortKey(indexNames = {"customers_by_date", "customers_by_name"})

public Instant regDate() { return this.regDate; }

public static final class Builder {

private String id;

private String email;

private String name;

private Instant regDate;

// The private Builder constructor is visible to the enclosing Customer class.

private Builder() {}

public Builder id(String accountId) { this.id = id; return this; }

public Builder email(String email) { this.email = email; return this; }

public Builder name(String name) { this.name = name; return this; }

public Builder regDate(Instant regDate) { this.regDate = regDate; return this; }

// This method will be automatically discovered and used by the TableSchema.

public CustomerImmutable build() { return new CustomerImmutable(this); }

}

You must meet the following requirements when you annotate a data class with @DynamoDbImmutable.

1.

Every method that is both not an override of Object.class and has not been annotated with

@DynamoDbIgnore must be a getter for an attribute of the DynamoDB table.

2. Every getter must have a corresponding case-sensitive setter on the builder class.

3. Only one of the following construction conditions must be met.

• The builder class must have a public default constructor.

•

The data class must have a public static method named builder() that takes no parameters and

returns an instance of the builder class. This option is shown in the immutable Customer class.

4.

The builder class must have a public method named build() that takes no parameters and returns

an instance of the immutable class.

To create a TableSchema for your immutable class, use the fromImmutableClass() method on

TableSchema as shown in the following snippet.

static final TableSchema<CustomerImmutable> customerImmutableTableSchema =

TableSchema.fromImmutableClass(CustomerImmutable.class);

Just as you can create a DynamoDB table from a mutable class, you can create one from an immutable

class with a one-time call to createTable() of DynamoDbTable as shown in the following snippet

example.

static void createTableFromImmutable(DynamoDbEnhancedClient enhancedClient, String

tableName, DynamoDbWaiter waiter){

// First, create an in-memory representation of the table using the 'table()' method of

the DynamoDb Enhanced Client.

// 'table()' accepts a name for the table and a TableSchema instance that you created

previously.

DynamoDbTable<CustomerImmutable> customerDynamoDbTable = enhancedClient

.table(tableName, TableSchema.fromImmutableClass(CustomerImmutable.class));

// Second, call the 'createTable()' method on the DynamoDbTable instance.

customerDynamoDbTable.createTable();

95

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

waiter.waitUntilTableExists(b -> b.tableName(tableName));

}

Use third-party libraries, such as Lombok

Third-party libraries, such as Project Lombok, help generate boilerplate code associated with immutable

objects. The DynamoDB Enhanced Client API works with these libraries as long as the data classes follow

the conventions detailed in this section.

The following example shows the immutable CustomerImmutable class with Lombok annotations.

Note how Lombok's onMethod feature copies attribute-based DynamoDB annotations, such as

@DynamoDbPartitionKey, onto the generated code.

@Value

@Builder

@DynamoDbImmutable(builder = Customer.CustomerBuilder.class)

public class Customer {

@Getter(onMethod_=@DynamoDbPartitionKey)

private String id;

@Getter(onMethod_=@DynamoDbSortKey)

private String email;

@Getter(onMethod_=@DynamoDbSecondaryPartitionKey(indexNames = "customers_by_name"))

private String name;

@Getter(onMethod_=@DynamoDbSecondarySortKey(indexNames = {"customers_by_date",

"customers_by_name"}))

private Instant createdDate;

}

Expressions and conditions

Expressions in the DynamoDB Enhanced Client API are Java representations of DynamoDB expressions.

The DynamoDB Enhanced Client API uses three types of expressions:

Expression

The Expression class is used when you deﬁne conditions and ﬁlters.

QueryConditional

This type of expression represents key conditions for query operations.

UpdateExpression

This class helps you write DynamoDB update expressions and is currently used in the extension

framework when you update an item.

Expression anatomy

An expression is made up of the following:

• A string expression (required). The string contains a DynamoDB logic expression with placeholder

names for attribute names and attribute values.

• A map of expression values (usually required).

• A map of expression names (optional).

96

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

Use a builder to generate anExpression object that takes the following general form.

Expression expression = Expression.builder()

.expression(<String>)

.expressionNames(<Map>)

.expressionValues(<Map>)

.build()

Expressions usually require a map of expression values. The map provides the values for the

placeholders in the string expression. The map key consists of the placeholder name preceded with a

colon (:) and the map value is an instance of AttributeValue. The AttributeValues class has convenience

methods to generate an AttributeValue instance from a literal. Alternatively, you can use the

AttributeValue.Builder to generate an AttributeValue instance.

The following snippet shows a map with two entries after comment line 2. The string passed to the

expression() method, shown after comment line 1, contains the placeholders that DynamoDB

resolves before performing the operation. This snippet doesn't contain a map of expression names,

because price is a permissible attribute name.

public static void scanAsync(DynamoDbAsyncTable productCatalog) {

ScanEnhancedRequest request = ScanEnhancedRequest.builder()

.consistentRead(true)

.attributesToProject("id", "title", "authors", "price")

.filterExpression(Expression.builder()

// 1. :min_value and :max_value are placeholders for the values

provided by the map

.expression("price >= :min_value AND price <= :max_value")

// 2. Two values are needed for the expression and each is supplied

as a map entry.

.expressionValues(

Map.of( ":min_value", numberValue(8.00),

":max_value", numberValue(400_000.00)))

.build())

.build();

If an attribute name in the DynamoDB table is a reserved word, begins with a number, or contains a

space, a map of expression names is required for the Expression.

For example, if the attribute name was 1price instead of price in the previous code example, the

example would need to be modiﬁed as shown in the following example.

ScanEnhancedRequest request = ScanEnhancedRequest.builder()

.filterExpression(Expression.builder()

.expression("#price >= :min_value AND #price <= :max_value")

.expressionNames( Map.of("#price", "1price") )

.expressionValues(

Map.of(":min_value", numberValue(8.00),

":max_value", numberValue(400_000.00)))

.build())

.build();

A placeholder for an expression name begins with the pound sign (#). An entry for the map of expression

names uses the placeholder as the key and the attribute name as the value. The map is added to the

expression builder with the expressionNames() method. DynamoDB resolves the attribute name

before it performs the operation.

Expression values are not required if a function is used in the string expression. An example of an

expression function is attribute_exists(<attribute_name>).

97

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

The following example builds an Expression that uses a DynamoDB function. The expression string

in this example uses no placeholders. This expression could be used on a putItem operation to check if

an item already exists in the database with a movie attribute's value equal to the data object's movie

attribute.

Expression exp = Expression.builder().expression("attribute_not_exists (movie)").build();

The DynamoDB Developer Guide contains complete information on the low-level expressions that are

used with DynamoDB.

Condition expressions and conditionals

When you use the putItem(), updateItem(), and deleteItem() methods, and also when you use

transaction and batch operations, you use Expression objects to specify conditions that DynamoDB

must meet to proceed with the operation. These expressions are named condition expressions. For an

example, see the condition expression used in the addDeleteItem() method (after comment line 1) of

transaction example (p. 116) shown in this guide.

When you work with the query() methods, a condition is expressed as a QueryConditional. The

QueryConditional class has several static convenience methods that help you write the criteria that

determine which items to read from DynamoDB.

For examples of QueryConditionals, see the ﬁrst code example of the the section called “Query

method examples” (p. 103) section of this guide.

Filter expressions

Filter expressions are used in scan and query operations to ﬁlter the items that are returned.

A ﬁlter expression is applied after all the data is read from the database, so the read cost is the same as

if there were no ﬁlter. The Amazon DynamoDB Developer Guide has more information about using ﬁlter

expressions for both query and scan operations.

The following example shows a ﬁlter expression added to a scan request. The criteria restricts the items

returned to items with a price between 8.00 and 80.00 inclusive.

Map<String, AttributeValue> expressionValues = Map.of(

":min_value", numberValue(8.00),

":max_value", numberValue(80.00));

ScanEnhancedRequest request = ScanEnhancedRequest.builder()

.consistentRead(true)

// 1. the 'attributesToProject()' method allows you to specify which values

you want returned.

.attributesToProject("id", "title", "authors", "price")

// 2. Filter expression limits the items returned that match the provided

criteria.

.filterExpression(Expression.builder()

.expression("price >= :min_value AND price <= :max_value")

.expressionValues(expressionValues)

.build())

.build();

Update expressions

The DynamoDB Enhanced Client's updateItem() method provides a standard way to update items

in DynamoDB. However, when you require more functionality, UpdateExpressions provide a type-safe

representation of DynamoDB update expression syntax. For example, you can use UpdateExpressions

98

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

to increase values without ﬁrst reading items from DynamoDB, or add individual members to a list.

Update expressions are currently available in custom extensions for the updateItem() method.

For an example that uses update expressions, see the custom extension example (p. 125) in this guide.

More information about update expressions is available in the Amazon DynamoDB Developer Guide.

Work with multiple items

The scan, query and batch methods of the DynamoDB Enhanced Client API return responses with one

or more pages. A page contains one or more items. Your code can process the response on per-page basis

or it can process individual items.

A paginated response returned by the synchronous DynamoDbEnhancedClient

client returns a PageIterable object, whereas a response returned by the asynchronous

DynamoDbEnhancedAsyncClient returns a PagePublisher object.

This section looks at processing paginated results and provides examples that use the scan and query

APIs.

Topics

• Scan a table (p. 99)

• Query a table (p. 102)

Scan a table

The SDK's scan method corresponds to the DynamoDB operation of the same name. The DynamoDB

Enhanced Client API oﬀers the same options but it uses a familiar object model and handles the

pagination for you.

First, we explore the PageIterable interface by looking at the scan method of the synchronous

mapping class, DynamoDbTable.

Use the synchronous API

The following example shows the scan method that uses an expression to ﬁlter the items that are

returned. The ProductCatalog (p. 91) is the model object that was shown earlier.

The ﬁltering expression shown after comment line 1 limits the ProductCatalog items that are returned

to those with a price value between 8.00 and 80.00 inclusively.

This example also excludes the isbn values by using the attributesToProject method shown after

comment line 2.

On comment line 3, the PageIterable object, pagedResult, is returned by the scan method. The

stream method of PageIterable returns a java.util.Stream object, which you can use to process

the pages. In this example, the number of pages is counted and logged.

Starting with comment line 4, the example shows two variations of accessing the ProductCatalog

items. The version after comment line 2a streams through each page and sorts and logs the items on

each page. The version after comment line 2b skips the page iteration and accesses the items directly.

The PageIterable interface oﬀers multiple ways to process results because of its two parent

interfaces—java.lang.Iterable and SdkIterable. Iterable brings the forEach, iterator and

spliterator methods, and SdkIterable brings the stream method.

public static void scanSync(DynamoDbTable<ProductCatalog> productCatalog) {

99

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

Map<String, AttributeValue> expressionValues = Map.of(

":min_value", numberValue(8.00),

":max_value", numberValue(80.00));

ScanEnhancedRequest request = ScanEnhancedRequest.builder()

.consistentRead(true)

// 1. the 'attributesToProject()' method allows you to specify which values

you want returned.

.attributesToProject("id", "title", "authors", "price")

// 2. Filter expression limits the items returned that match the provided

criteria.

.filterExpression(Expression.builder()

.expression("price >= :min_value AND price <= :max_value")

.expressionValues(expressionValues)

.build())

.build();

// 3. A PageIterable object is returned by the scan method.

PageIterable<ProductCatalog> pagedResults = productCatalog.scan(request);

logger.info("page count: {}", pagedResults.stream().count());

// 4. Log the returned ProductCatalog items using two variations.

// 4a. This version sorts and logs the items of each page.

pagedResults.stream().forEach(p -> p.items().stream()

.sorted(Comparator.comparing(ProductCatalog::price))

.forEach(

item -> logger.info(item.toString())

));

// 4b. This version sorts and logs all items for all pages.

pagedResults.items().stream()

.sorted(Comparator.comparing(ProductCatalog::price))

.forEach(

item -> logger.info(item.toString())

);

}

Use the asynchronous API

The asynchronous scan method returns results as a PagePublisher object. The PagePublisher

interface has two subscribe methods that you can use to process response pages. One subscribe

method comes from the org.reactivestreams.Publisher parent interface. To process pages using

this ﬁrst option, pass a Subscriber instance to the subscribe method. The ﬁrst example that follows

shows the use of subscribe method.

The second subscribe method comes from the SdkPublisher interface. This version of subscribe

accepts a Consumer rather than a Subscriber. This subscribe method variation is shown in the

second example that follows.

The following example shows the asynchronous version of the scan method that uses the same ﬁlter

expression shown in the previous example.

After comment line 3, DynamoDbAsyncTable.scan returns a PagePublisher object. On the

next line, the code creates an instance of the org.reactivestreams.Subscriber interface,

ProductCatalogSubscriber, which subscribes to the PagePublisher after comment line 4.

The Subscriber object collects the ProductCatalog items from each page in the onNext

method after comment line 8 in the ProductCatalogSubscriber class example. The

items are stored in the private List variable and are accessed in the calling code with the

ProductCatalogSubscriber.getSubscribedItems() method. This is called after comment line 5.

After the list is retrieved, the code sorts all ProductCatalog items by price and logs each item.

100

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

The CountDownLatch in the ProductCatalogSubscriber class blocks the calling thread until all items

have been added to the list before continuing after comment line 5.

public static void scanAsync(DynamoDbAsyncTable productCatalog) {

ScanEnhancedRequest request = ScanEnhancedRequest.builder()

.consistentRead(true)

.attributesToProject("id", "title", "authors", "price")

.filterExpression(Expression.builder()

// 1. :min_value and :max_value are placeholders for the values

provided by the map

.expression("price >= :min_value AND price <= :max_value")

// 2. Two values are needed for the expression and each is supplied

as a map entry.

.expressionValues(

Map.of( ":min_value", numberValue(8.00),

":max_value", numberValue(400_000.00)))

.build())

.build();

// 3. A PagePublisher object is returned by the scan method.

PagePublisher<ProductCatalog> pagePublisher = productCatalog.scan(request);

ProductCatalogSubscriber subscriber = new ProductCatalogSubscriber();

// 4. Subscribe the ProductCatalogSubscriber to the PagePublisher.

pagePublisher.subscribe(subscriber);

// 5. Retrieve all collected ProductCatalog items accumulated by the subscriber.

subscriber.getSubscribedItems().stream()

.sorted(Comparator.comparing(ProductCatalog::price))

.forEach(item ->

logger.info(item.toString()));

// 6. Use a Consumer to work through each page.

pagePublisher.subscribe(page -> page

.items().stream()

.sorted(Comparator.comparing(ProductCatalog::price))

.forEach(item ->

logger.info(item.toString())))

.join(); // If needed, blocks the subscribe() method thread until it is

finished processing.

// 7. Use a Consumer to work through each ProductCatalog item.

pagePublisher.items()

.subscribe(product -> logger.info(product.toString()))

.exceptionally(failure -> {

logger.error("ERROR - ", failure);

return null;

})

.join(); // If needed, blocks the subscribe() method thread until it is

finished processing.

}

private static class ProductCatalogSubscriber implements

Subscriber<Page<ProductCatalog>> {

private CountDownLatch latch = new CountDownLatch(1);

private Subscription subscription;

private List<ProductCatalog> itemsFromAllPages = new ArrayList<>();

@Override

public void onSubscribe(Subscription sub) {

subscription = sub;

subscription.request(1L);

try {

latch.await(); // Called by main thread blocking it until latch is

released.

} catch (InterruptedException e) {

throw new RuntimeException(e);

}

101

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

}

@Override

public void onNext(Page<ProductCatalog> productCatalogPage) {

// 8. Collect all the ProductCatalog instances in the page, then ask the

publisher for one more page.

itemsFromAllPages.addAll(productCatalogPage.items());

subscription.request(1L);

}

@Override

public void onError(Throwable throwable) {

}

@Override

public void onComplete() {

latch.countDown(); // Call by subscription thread; latch releases.

}

List<ProductCatalog> getSubscribedItems() {

return this.itemsFromAllPages;

}

The following snippet example uses the version of the PagePublisher.subscribe method that

accepts a Consumer after comment line 6. The Java lambda parameter consumes pages, which further

process each item. In this example, each page is processed and the items on each page are sorted and

then logged.

// 6. Use a Consumer to work through each page.

pagePublisher.subscribe(page -> page

.items().stream()

.sorted(Comparator.comparing(ProductCatalog::price))

.forEach(item ->

logger.info(item.toString())))

.join(); // If needed, blocks the subscribe() method thread until it is

finished processing.

The items method of PagePublisher unwraps the model instances so that your code can process the

items directly. This approach is shown in the following snippet.

// 7. Use a Consumer to work through each ProductCatalog item.

pagePublisher.items()

.subscribe(product -> logger.info(product.toString()))

.exceptionally(failure -> {

logger.error("ERROR - ", failure);

return null;

})

.join(); // If needed, blocks the subscribe() method thread until it is

finished processing.

Query a table

The query() method of the DynamoDbTable class ﬁnds items based on primary key values. The

@DynamoDbPartitionKey annotation and the optional @DynamoDbSortKey annotation are used to

deﬁne the primary key on your data class.

The query() method requires a partition key value that ﬁnds items that match the supplied value. If

your table also deﬁnes a sort key, you can add a value for it to your query as an additional comparison

condition to ﬁne tune the results.

102

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

Except for processing the results, the synchronous and asynchronous versions of query() work the

same. As with the scan API, the query API returns a PageIterable for a synchronous call and a

PagePublisher for asynchronous call. We discussed the use of PageIterable and PagePublisher

previously in the scan section.

Query method examples

The query() method code example that follows uses the MovieActor class. The data class deﬁnes

a composite primary key that is made up of the movie attribute for the partition key and the actor

attribute for the sort key.

The class also signals that it uses a global secondary index named acting_award_year. The index's

composite primary key is composed of the actingaward attribute for the partition key and the

actingyear for the sort key. Later in this topic, when we show how to create and use indexes, we'll

refer to the acting_award_year index.

MovieActor class

package org.example.tests.model;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbAttribute;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;

import

software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondaryPartitionKey;

import

software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondarySortKey;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSortKey;

import java.util.Objects;

@DynamoDbBean

public class MovieActor implements Comparable<MovieActor> {

private String movieName;

private String actorName;

private String actingAward;

private Integer actingYear;

private String actingSchoolName;

@DynamoDbPartitionKey

@DynamoDbAttribute("movie")

public String getMovieName() {

return movieName;

}

public void setMovieName(String movieName) {

this.movieName = movieName;

}

@DynamoDbSortKey

@DynamoDbAttribute("actor")

public String getActorName() {

return actorName;

}

public void setActorName(String actorName) {

this.actorName = actorName;

}

@DynamoDbSecondaryPartitionKey(indexNames = "acting_award_year")

@DynamoDbAttribute("actingaward")

public String getActingAward() {

return actingAward;

103

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

}

public void setActingAward(String actingAward) {

this.actingAward = actingAward;

}

@DynamoDbSecondarySortKey(indexNames = {"acting_award_year", "movie_year"})

@DynamoDbAttribute("actingyear")

public Integer getActingYear() {

return actingYear;

}

public void setActingYear(Integer actingYear) {

this.actingYear = actingYear;

}

@DynamoDbAttribute("actingschoolname")

public String getActingSchoolName() {

return actingSchoolName;

}

public void setActingSchoolName(String actingSchoolName) {

this.actingSchoolName = actingSchoolName;

}

@Override

public String toString() {

final StringBuffer sb = new StringBuffer("MovieActor{");

sb.append("movieName='").append(movieName).append('\'');

sb.append(", actorName='").append(actorName).append('\'');

sb.append(", actingAward='").append(actingAward).append('\'');

sb.append(", actingYear=").append(actingYear);

sb.append(", actingSchoolName='").append(actingSchoolName).append('\'');

sb.append('}');

return sb.toString();

}

@Override

public boolean equals(Object o) {

if (this == o) return true;

if (o == null || getClass() != o.getClass()) return false;

MovieActor that = (MovieActor) o;

return Objects.equals(movieName, that.movieName) && Objects.equals(actorName,

that.actorName) && Objects.equals(actingAward, that.actingAward) &&

Objects.equals(actingYear, that.actingYear) && Objects.equals(actingSchoolName,

that.actingSchoolName);

}

@Override

public int hashCode() {

return Objects.hash(movieName, actorName, actingAward, actingYear,

actingSchoolName);

}

@Override

public int compareTo(MovieActor o) {

if (this.movieName.compareTo(o.movieName) != 0){

return this.movieName.compareTo(o.movieName);

} else {

return this.actorName.compareTo(o.actorName);

}

The code examples that follow query against the following items.

104

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

Items in the MovieActor table

MovieActor{movieName='movie01', actorName='actor0', actingAward='actingaward0',

actingYear=2001, actingSchoolName='null'}

MovieActor{movieName='movie01', actorName='actor1', actingAward='actingaward1',

actingYear=2001, actingSchoolName='actingschool1'}

MovieActor{movieName='movie01', actorName='actor2', actingAward='actingaward2',

actingYear=2001, actingSchoolName='actingschool2'}

MovieActor{movieName='movie01', actorName='actor3', actingAward='actingaward3',

actingYear=2001, actingSchoolName='null'}

MovieActor{movieName='movie01', actorName='actor4', actingAward='actingaward4',

actingYear=2001, actingSchoolName='actingschool4'}

MovieActor{movieName='movie02', actorName='actor0', actingAward='actingaward0',

actingYear=2002, actingSchoolName='null'}

MovieActor{movieName='movie02', actorName='actor1', actingAward='actingaward1',

actingYear=2002, actingSchoolName='actingschool1'}

MovieActor{movieName='movie02', actorName='actor2', actingAward='actingaward2',

actingYear=2002, actingSchoolName='actingschool2'}

MovieActor{movieName='movie02', actorName='actor3', actingAward='actingaward3',

actingYear=2002, actingSchoolName='null'}

MovieActor{movieName='movie02', actorName='actor4', actingAward='actingaward4',

actingYear=2002, actingSchoolName='actingschool4'}

MovieActor{movieName='movie03', actorName='actor0', actingAward='actingaward0',

actingYear=2003, actingSchoolName='null'}

MovieActor{movieName='movie03', actorName='actor1', actingAward='actingaward1',

actingYear=2003, actingSchoolName='actingschool1'}

MovieActor{movieName='movie03', actorName='actor2', actingAward='actingaward2',

actingYear=2003, actingSchoolName='actingschool2'}

MovieActor{movieName='movie03', actorName='actor3', actingAward='actingaward3',

actingYear=2003, actingSchoolName='null'}

MovieActor{movieName='movie03', actorName='actor4', actingAward='actingaward4',

actingYear=2003, actingSchoolName='actingschool4'}

The following code deﬁnes two QueryConditional instances. QueryConditionals work with key

values—either the partition key alone or in combination with the sort key—and correspond to the key

conditional expressions of the DynamoDB service API. After comment line 1, the example deﬁnes the

keyEqual instance that matches items with a partition value of movie01.

This example also deﬁnes a ﬁlter expression that ﬁlters oﬀ any item that has no actingschoolname on

after comment line 2.

After comment line 3, the example shows the QueryEnhancedRequest instance that the code passes to

the DynamoDbTable.query() method. This object combines the key condition and ﬁlter that the SDK

uses to generate the request to the DynamoDB service.

public static void query(DynamoDbTable movieActorTable) {

// 1. Define a QueryConditional instance to return items matching a partition

value.

QueryConditional keyEqual = QueryConditional.keyEqualTo(b ->

b.partitionValue("movie01"));

// 1a. Define a QueryConditional that adds a sort key criteria to the partition

value criteria.

QueryConditional sortGreaterThanOrEqualTo =

QueryConditional.sortGreaterThanOrEqualTo(b ->

b.partitionValue("movie01").sortValue("actor2"));

// 2. Define a filter expression that filters out items whose attribute value is

null.

final Expression filterOutNoActingschoolname =

Expression.builder().expression("attribute_exists(actingschoolname)").build();

// 3. Build the query request.

105

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder()

.queryConditional(keyEqual)

.filterExpression(filterOutNoActingschoolname)

.build();

// 4. Perform the query.

PageIterable<MovieActor> pagedResults = movieActorTable.query(tableQuery);

logger.info("page count: {}", pagedResults.stream().count()); // Log number of

pages.

pagedResults.items().stream()

.sorted()

.forEach(

item -> logger.info(item.toString()) // Log the sorted list of

items.

);

The following is the output from running the method. The output displays items with a movieName

value of movie01 and displays no items with actingSchoolName equal to null.

2023-03-05 13:11:05 [main] INFO org.example.tests.QueryDemo:46 - page count: 1

2023-03-05 13:11:05 [main] INFO org.example.tests.QueryDemo:51 -

MovieActor{movieName='movie01', actorName='actor1', actingAward='actingaward1',

actingYear=2001, actingSchoolName='actingschool1'}

2023-03-05 13:11:05 [main] INFO org.example.tests.QueryDemo:51 -

MovieActor{movieName='movie01', actorName='actor2', actingAward='actingaward2',

actingYear=2001, actingSchoolName='actingschool2'}

2023-03-05 13:11:05 [main] INFO org.example.tests.QueryDemo:51 -

MovieActor{movieName='movie01', actorName='actor4', actingAward='actingaward4',

actingYear=2001, actingSchoolName='actingschool4'}

In the following query request variation shown previously after comment line 3, the code replaces the

keyEqual QueryConditional with the sortGreaterThanOrEqualTo QueryConditional that was

deﬁned after comment line 1a. The following code also removes the ﬁlter expression.

QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder()

.queryConditional(sortGreaterThanOrEqualTo)

Because this table has a composite primary key, all QueryConditional instances require a partition key

value. QueryConditional methods that begin with sort... indicate that a sort key is required. The

results are not sorted.

The following output displays the results from the query. The query returns items that have a

movieName value equal to movie01 and only items that have an actorName value that is greater than

or equal to actor2. Because the ﬁlter was removed, the query returns items that have no value for the

actingSchoolName attribute.

2023-03-05 13:15:00 [main] INFO org.example.tests.QueryDemo:46 - page count: 1

2023-03-05 13:15:00 [main] INFO org.example.tests.QueryDemo:51 -

MovieActor{movieName='movie01', actorName='actor2', actingAward='actingaward2',

actingYear=2001, actingSchoolName='actingschool2'}

2023-03-05 13:15:00 [main] INFO org.example.tests.QueryDemo:51 -

MovieActor{movieName='movie01', actorName='actor3', actingAward='actingaward3',

actingYear=2001, actingSchoolName='null'}

2023-03-05 13:15:00 [main] INFO org.example.tests.QueryDemo:51 -

MovieActor{movieName='movie01', actorName='actor4', actingAward='actingaward4',

actingYear=2001, actingSchoolName='actingschool4'}

106

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

Multiple operations

The DynamoDB Enhanced Client API supports multiple options per request with batches and

transactions. The diﬀerence between them is that a transaction fails if one or more individual operations

fail, but a batch request lets individual operations fail while processing the others.

Contents

• Batch operations (p. 107)

• batchGetItem() example (p. 107)

• batchWriteItem() example (p. 109)

• Transaction operations (p. 111)

• transactGetItems() example (p. 111)

• transactWriteItems() examples (p. 112)

• Basic example (p. 112)

• Condition check example (p. 114)

• Single operation condition example (p. 116)

Batch operations

The DynamoDB Enhanced Client API oﬀers two batch methods, batchGetItem() and

batchWriteItem().

batchGetItem() example

With the DynamoDbTable.batchGetItem() method, you can retrieve up to 100 individual items

across multiple tables in one overall request. The following example uses the Customer (p. 82) and

MovieActor (p. 103) data classes shown previously.

In the example after lines 1 and 2, you build ReadBatch objects that you later add as parameters

to the batchGetItem() method after comment line 3. The code after comment line 1 builds

the batch to read from the Customer table. The code after comment line 1a shows the use of a

GetItemEnhancedRequest builder that takes primary key values to specify the item to read. In

contrast to specifying key values to request an item, you can use a data class to request an item as shown

after comment line 1b. The SDK extracts the key values behind the scenes before submitting the request.

When you specify the item using the key-based approach as shown in the two statements after

2a, you can also specify that DynamoDB should perform a strongly consistent read. When the

consistentRead() method is used, it must be used on all requested items for the same table.

To retrieve the items that DynamoDB found, use the resultsForTable() method that is shown after

comment line 4. Call the method for each table that was read in the request. resultsForTable()

returns a list of found items that you can process using any java.util.List method. This example

logs each item.

To discover items that DynamoDB did not process, use the approach after comment line 5. The

BatchGetResultPage class has the unproccessKeysForTable() method that gives you access to

each key that was unprocessed. The BatchGetItem API reference has more information about situations

that result in unprocessed items.

public static void batchGetItemExample(DynamoDbEnhancedClient enhancedClient,

DynamoDbTable<Customer> customerTable,

DynamoDbTable<MovieActor> movieActorTable) {

Customer customer2 = new Customer();

107

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

customer2.setId("2");

customer2.setEmail("[email protected]");

// 1. Build a batch to read from the Customer table.

ReadBatch customerBatch = ReadBatch.builder(Customer.class)

.mappedTableResource(customerTable)

// 1a. Specify the primary key values for the item.

.addGetItem(b -> b.key(k ->

k.partitionValue("1").sortValue("[email protected]")))

// 1b. Alternatively, supply a data class instances to provide the primary

key values.

.addGetItem(customer2)

.build();

// 2. Build a batch to read from the MovieActor table.

ReadBatch moveActorBatch = ReadBatch.builder(MovieActor.class)

.mappedTableResource(movieActorTable)

// 2a. Call consistentRead(Boolean.TRUE) for each item for the same table.

.addGetItem(b -> b.key(k ->

k.partitionValue("movie01").sortValue("actor1")).consistentRead(Boolean.TRUE))

.addGetItem(b -> b.key(k ->

k.partitionValue("movie01").sortValue("actor4")).consistentRead(Boolean.TRUE))

.build();

// 3. Add ReadBatch objects to the request.

BatchGetResultPageIterable resultPages = enhancedClient.batchGetItem(b ->

b.readBatches(customerBatch, moveActorBatch));

// 4. Retrieve the successfully requested items from each table.

resultPages.resultsForTable(customerTable).forEach(item ->

logger.info(item.toString()));

resultPages.resultsForTable(movieActorTable).forEach(item ->

logger.info(item.toString()));

// 5. Retrieve the keys of the items requested but not processed by the service.

resultPages.forEach((BatchGetResultPage pageResult) -> {

pageResult.unprocessedKeysForTable(customerTable).forEach(key ->

logger.info("Unprocessed item key: " + key.toString()));

pageResult.unprocessedKeysForTable(customerTable).forEach(key ->

logger.info("Unprocessed item key: " + key.toString()));

});

}

Assume that the following items are in the two tables before running the example code.

Items in tables

Customer [id=1, name=CustName1, [email protected], regDate=2023-03-31T15:46:27.688Z]

Customer [id=2, name=CustName2, [email protected], regDate=2023-03-31T15:46:28.688Z]

Customer [id=3, name=CustName3, [email protected], regDate=2023-03-31T15:46:29.688Z]

Customer [id=4, name=CustName4, [email protected], regDate=2023-03-31T15:46:30.688Z]

Customer [id=5, name=CustName5, [email protected], regDate=2023-03-31T15:46:31.689Z]

MovieActor{movieName='movie01', actorName='actor0', actingAward='actingaward0',

actingYear=2001, actingSchoolName='null'}

MovieActor{movieName='movie01', actorName='actor1', actingAward='actingaward1',

actingYear=2001, actingSchoolName='actingschool1'}

MovieActor{movieName='movie01', actorName='actor2', actingAward='actingaward2',

actingYear=2001, actingSchoolName='actingschool2'}

MovieActor{movieName='movie01', actorName='actor3', actingAward='actingaward3',

actingYear=2001, actingSchoolName='null'}

MovieActor{movieName='movie01', actorName='actor4', actingAward='actingaward4',

actingYear=2001, actingSchoolName='actingschool4'}

The following output shows the items returned and logged after comment line 4.

108

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

Customer [id=1, name=CustName1, [email protected], regDate=2023-03-31T15:46:27.688Z]

Customer [id=2, name=CustName2, [email protected], regDate=2023-03-31T15:46:28.688Z]

MovieActor{movieName='movie01', actorName='actor4', actingAward='actingaward4',

actingYear=2001, actingSchoolName='actingschool4'}

MovieActor{movieName='movie01', actorName='actor1', actingAward='actingaward1',

actingYear=2001, actingSchoolName='actingschool1'}

batchWriteItem() example

The batchWriteItem() method puts or deletes multiple items in one or more tables. You can

specify up to 25 individual put or delete operations in the request. The following example uses the

ProductCatalog (p. 91) and MovieActor (p. 103) model classes shown previously.

WriteBatch objects are built after comment lines 1 and 2. For the ProductCatalog table, the code

puts one item and deletes one item. For the MovieActor table after comment line 2, the code puts two

items and deletes one.

The batchWriteItem method is called after comment line 3. The builder parameter provides the

batch requests for each table.

The returned BatchWriteResult object provides separate methods for each operation to view

unprocessed requests. The code after comment line 4a provides the keys for unprocessed delete requests

and the code after comment line 4b provides the unprocessed put items.

public static void batchWriteItemExample(DynamoDbEnhancedClient enhancedClient,

DynamoDbTable<ProductCatalog> catalogTable,

DynamoDbTable<MovieActor> movieActorTable) {

// 1. Build a batch to write to the ProductCatalog table.

WriteBatch products = WriteBatch.builder(ProductCatalog.class)

.mappedTableResource(catalogTable)

.addPutItem(b -> b.item(getProductCatItem1()))

.addDeleteItem(b -> b.key(k -> k

.partitionValue(getProductCatItem2().id())

.sortValue(getProductCatItem2().title())))

.build();

// 2. Build a batch to write to the MovieActor table.

WriteBatch movies = WriteBatch.builder(MovieActor.class)

.mappedTableResource(movieActorTable)

.addPutItem(getMovieActorYeoh())

.addPutItem(getMovieActorBlanchettPartial())

.addDeleteItem(b -> b.key(k -> k

.partitionValue(getMovieActorStreep().getMovieName())

.sortValue(getMovieActorStreep().getActorName())))

.build();

// 3. Add WriteBatch objects to the request.

BatchWriteResult batchWriteResult = enhancedClient.batchWriteItem(b ->

b.writeBatches(products, movies));

// 4. Retrieve keys for items the service did not process.

// 4a. 'unprocessedDeleteItemsForTable()' returns keys for delete requests that did

not process.

if (batchWriteResult.unprocessedDeleteItemsForTable(movieActorTable).size() > 0) {

batchWriteResult.unprocessedDeleteItemsForTable(movieActorTable).forEach(key ->

logger.info(key.toString()));

}

// 4b. 'unprocessedPutItemsForTable()' returns keys for put requests that did not

process.

if (batchWriteResult.unprocessedPutItemsForTable(catalogTable).size() > 0) {

batchWriteResult.unprocessedPutItemsForTable(catalogTable).forEach(key ->

logger.info(key.toString()));

109

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

}

The following helper methods provide the model objects for the put and delete operations.

Helper methods

public static ProductCatalog getProductCatItem1() {

return ProductCatalog.builder()

.id(2)

.isbn("1-565-85698")

.authors(new HashSet<>(Arrays.asList("a", "b")))

.price(BigDecimal.valueOf(30.22))

.title("Title 55")

.build();

}

public static ProductCatalog getProductCatItem2() {

return ProductCatalog.builder()

.id(4)

.price(BigDecimal.valueOf(40.00))

.title("Title 1")

.build();

}

public static MovieActor getMovieActorBlanchettPartial() {

MovieActor movieActor = new MovieActor();

movieActor.setActorName("Cate Blanchett");

movieActor.setMovieName("Blue Jasmine");

movieActor.setActingYear(2023);

movieActor.setActingAward("Best Actress");

return movieActor;

}

public static MovieActor getMovieActorStreep() {

MovieActor movieActor = new MovieActor();

movieActor.setActorName("Meryl Streep");

movieActor.setMovieName("Sophie's Choice");

movieActor.setActingYear(1982);

movieActor.setActingAward("Best Actress");

movieActor.setActingSchoolName("Yale School of Drama");

return movieActor;

}

public static MovieActor getMovieActorYeoh(){

MovieActor movieActor = new MovieActor();

movieActor.setActorName("Michelle Yeoh");

movieActor.setMovieName("Everything Everywhere All at Once");

movieActor.setActingYear(2023);

movieActor.setActingAward("Best Actress");

movieActor.setActingSchoolName("Royal Academy of Dance");

return movieActor;

}

Assume that the tables contain the following items before you run the example code.

MovieActor{movieName='Blue Jasmine', actorName='Cate Blanchett', actingAward='Best

Actress', actingYear=2013, actingSchoolName='National Institute of Dramatic Art'}

MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best

Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}

ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}

After the example code ﬁnishes, the tables contain the following items.

110

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

MovieActor{movieName='Blue Jasmine', actorName='Cate Blanchett', actingAward='Best

Actress', actingYear=2013, actingSchoolName='null'}

MovieActor{movieName='Everything Everywhere All at Once', actorName='Michelle Yeoh',

actingAward='Best Actress', actingYear=2023, actingSchoolName='Royal Academy of Dance'}

ProductCatalog{id=2, title='Title 55', isbn='1-565-85698', authors=[a, b], price=30.22}

Notice in the MovieActor table that the Blue Jasmine movie item has been replaced with the item

used in the put request acquired through the getMovieActorBlanchettPartial() helper method.

If a data bean attribute value was not provided, the value in the database is removed. This is why the

resulting actingSchoolName is null for the Blue Jasmine movie item.

Note

Although the API documentation suggests that condition expressions can be used and that

consumed capacity and collection metrics can be returned with individual put and delete

requests, this is not the case in a batch write scenario. To improve performance for batch

operations, these individual options are ignored.

Transaction operations

The DynamoDB Enhanced Client API provides the transactGetItems() and the

transactWriteItems() methods. The transaction methods of the SDK for Java provide atomicity,

consistency, isolation, and durability (ACID) in DynamoDB tables, helping you to maintain data

correctness in your applications.

Contents

• transactGetItems() example (p. 111)

• transactWriteItems() examples (p. 112)

• Basic example (p. 112)

• Condition check example (p. 114)

• Single operation condition example (p. 116)

transactGetItems() example

The transactGetItems() method accepts up to 100 individual requests for items. All items are read

in a single atomic transaction. The Amazon DynamoDB Developer Guide has information about the

conditions that cause a transactGetItems() method to fail, and also about the isolation level used

when you call transactGetItem().

After comment line 1 in the following example, the code calls the transactGetItems() method

with a builder parameter. The builder's addGetItem() is invoked three times with a data object that

contains the key values that the SDK will use to generate the ﬁnal request.

The request returns a list of Document objects after comment line 2. The list of documents that is

returned contains non-null Document instances of item data in the same order as requested. The

Document.getItem(MappedTableResource<T> mappedTableResource) method converts an

untyped Document object into a typed Java object if item data was returned, otherwise the method

returns null.

public static void transactGetItemsExample(DynamoDbEnhancedClient enhancedClient,

DynamoDbTable<ProductCatalog> catalogTable,

DynamoDbTable<MovieActor> movieActorTable) {

// 1. Request three items from two tables using a builder.

final List<Document> documents = enhancedClient.transactGetItems(b -> b

.addGetItem(catalogTable, Key.builder().partitionValue(2).sortValue("Title

55").build())

111

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

.addGetItem(movieActorTable, Key.builder().partitionValue("Sophie's

Choice").sortValue("Meryl Streep").build())

.addGetItem(movieActorTable, Key.builder().partitionValue("Blue

Jasmine").sortValue("Cate Blanchett").build())

.build());

// 2. A list of Document objects is returned in the same order as requested.

ProductCatalog title55 = documents.get(0).getItem(catalogTable);

if (title55 != null) {

logger.info(title55.toString());

}

MovieActor sophiesChoice = documents.get(1).getItem(movieActorTable);

if (sophiesChoice != null) {

logger.info(sophiesChoice.toString());

}

// 3. The getItem() method returns null if the Document object contains no item

from DynamoDB.

MovieActor blueJasmine = documents.get(2).getItem(movieActorTable);

if (blueJasmine != null) {

logger.info(blueJasmine.toString());

}

The DynamoDB tables contain the following items before the code example runs.

ProductCatalog{id=2, title='Title 55', isbn='orig_isbn', authors=[b, g], price=10}

MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best

Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}

The following output is logged. If an item is requested but not found, it not returned as is the case for

the request for the movie named Blue Jasmine.

ProductCatalog{id=2, title='Title 55', isbn='orig_isbn', authors=[b, g], price=10}

MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best

Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}

transactWriteItems() examples

The transactWriteItems() accepts up to 100 put, update, or delete actions in a single atomic

transaction across multiple tables. The Amazon DynamoDB Developer Guide contains details about

restrictions and failure conditions of the underlying DynamoDB service operation.

Basic example

In the following example, four operations are requested for two tables. The corresponding model classes

ProductCatalog (p. 91) and MovieActor (p. 103) were shown previously.

Each of the three possible operations—put, update, and delete—uses a dedicated request parameter to

specify the details.

The code after comment line 1 shows the simple variation of the addPutItem() method. The method

accepts a MappedTableResource object and the data object instance to put. The statement after

comment line 2 shows the variation that accepts a TransactPutItemEnhancedRequest instance.

This variation lets you add more options in the request, such as a condition expression. A subsequent

example (p. 116) shows a condition expression for an individual operation.

An update operation is requested after comment line 3. TransactUpdateItemEnhancedRequest

has an ignoreNulls() method that lets you conﬁgure what the SDK does with null values on the

112

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

model object. If the ignoreNulls() method returns true, the SDK does not remove the table's attribute

values for data object attributes that are null. If the ignoreNulls() method returns false, the SDK

requests the DynamoDB service to remove the attributes from the item in the table. The default value

for ignoreNulls is false.

The statement after comment line 4 shows the variation of a delete request that takes a data object. The

enhanced client extracts the key values before dispatching the ﬁnal request.

public static void transactWriteItems(DynamoDbEnhancedClient enhancedClient,

DynamoDbTable<ProductCatalog> catalogTable,

DynamoDbTable<MovieActor> movieActorTable) {

enhancedClient.transactWriteItems(b -> b

// 1. Simplest variation of put item request.

.addPutItem(catalogTable, getProductCatId2())

// 2. Put item request variation that accommodates condition expressions.

.addPutItem(movieActorTable,

TransactPutItemEnhancedRequest.builder(MovieActor.class)

.item(getMovieActorStreep())

.conditionExpression(Expression.builder().expression("attribute_not_exists

(movie)").build())

.build())

// 3. Update request that does not remove attribute values on the table if

the data object's value is null.

.addUpdateItem(catalogTable,

TransactUpdateItemEnhancedRequest.builder(ProductCatalog.class)

.item(getProductCatId4ForUpdate())

.ignoreNulls(Boolean.TRUE)

.build())

// 4. Variation of delete request that accepts a data object. The key

values are extracted for the request.

.addDeleteItem(movieActorTable, getMovieActorBlanchett())

);

}

The following helper methods provide the data objects for the add*Item parameters.

Helper methods

public static ProductCatalog getProductCatId2() {

return ProductCatalog.builder()

.id(2)

.isbn("1-565-85698")

.authors(new HashSet<>(Arrays.asList("a", "b")))

.price(BigDecimal.valueOf(30.22))

.title("Title 55")

.build();

}

public static ProductCatalog getProductCatId4ForUpdate() {

return ProductCatalog.builder()

.id(4)

.price(BigDecimal.valueOf(40.00))

.title("Title 1")

.build();

}

public static MovieActor getMovieActorBlanchett() {

MovieActor movieActor = new MovieActor();

movieActor.setActorName("Cate Blanchett");

movieActor.setMovieName("Tar");

movieActor.setActingYear(2022);

113

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

movieActor.setActingAward("Best Actress");

movieActor.setActingSchoolName("National Institute of Dramatic Art");

return movieActor;

}

public static MovieActor getMovieActorStreep() {

MovieActor movieActor = new MovieActor();

movieActor.setActorName("Meryl Streep");

movieActor.setMovieName("Sophie's Choice");

movieActor.setActingYear(1982);

movieActor.setActingAward("Best Actress");

movieActor.setActingSchoolName("Yale School of Drama");

return movieActor;

}

The DynamoDB tables contain the following items before the code example runs.

1 | ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}

2 | MovieActor{movieName='Tar', actorName='Cate Blanchett', actingAward='Best Actress',

actingYear=2022, actingSchoolName='National Institute of Dramatic Art'}

The following items are in the tables after the code ﬁnishes running.

3 | ProductCatalog{id=2, title='Title 55', isbn='1-565-85698', authors=[a, b], price=30.22}

4 | ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=40.0}

5 | MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best

Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}

The item on line 2 has been deleted and lines 3 and 5 show the items that were put. Line 4 shows the

update of line 1. The price value is the only value that changed on the item. If ignoreNulls() had

returned false, line 4 would look like the following line.

ProductCatalog{id=4, title='Title 1', isbn='null', authors=null, price=40.0}

Condition check example

The following example shows the use of a condition check. A condition check is used to check that an

item exists or to check the condition of speciﬁc attributes of an item in the database. The item checked

in the condition check cannot be used in another operation in the transaction.

Note

You can't target the same item with multiple operations within the same transaction. For

example, you can't perform a condition check and also attempt to update the same item in the

same transaction.

The example shows one of each type of operation in a transactional write items request. After comment

line 2, the addConditionCheck() method supplies the condition that fails the transaction if the

conditionExpression parameter evaluates to false. The condition expression that is returned

from the method shown in the Helper methods block checks if the award year for the movie Sophie's

Choice is not equal to 1982. If it is, the expression evaluates to false and the transaction fails.

This guide discusses expressions (p. 96) in depth in another topic.

public static void conditionCheckFailExample(DynamoDbEnhancedClient enhancedClient,

DynamoDbTable<ProductCatalog>

catalogTable,

DynamoDbTable<MovieActor> movieActorTable)

{

try {

114

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

enhancedClient.transactWriteItems(b -> b

// 1. Perform one of each type of operation with the next three

methods.

.addPutItem(catalogTable,

TransactPutItemEnhancedRequest.builder(ProductCatalog.class)

.item(getProductCatId2()).build())

.addUpdateItem(catalogTable,

TransactUpdateItemEnhancedRequest.builder(ProductCatalog.class)

.item(getProductCatId4ForUpdate())

.ignoreNulls(Boolean.TRUE).build())

.addDeleteItem(movieActorTable,

TransactDeleteItemEnhancedRequest.builder()

.key(b1 -> b1

.partitionValue(getMovieActorBlanchett().getMovieName())

.sortValue(getMovieActorBlanchett().getActorName())).build())

// 2. Add a condition check on a table item that is not involved in

another operation in this request.

.addConditionCheck(movieActorTable, ConditionCheck.builder()

.conditionExpression(buildConditionCheckExpression())

.key(k -> k

.partitionValue("Sophie's Choice")

.sortValue("Meryl Streep"))

// 3. Specify the request to return existing values from the

item if the condition evaluates to true.

.returnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)

.build())

.build());

// 4. Catch the exception if the transaction fails and log the information.

} catch (TransactionCanceledException ex) {

ex.cancellationReasons().stream().forEach(cancellationReason -> {

logger.info(cancellationReason.toString());

});

}

The following helper methods are used in the previous code example.

Helper methods

private static Expression buildConditionCheckExpression() {

Map<String, AttributeValue> expressionValue = Map.of(

":year", numberValue(1982));

return Expression.builder()

.expression("actingyear <> :year")

.expressionValues(expressionValue)

.build();

}

public static ProductCatalog getProductCatId2() {

return ProductCatalog.builder()

.id(2)

.isbn("1-565-85698")

.authors(new HashSet<>(Arrays.asList("a", "b")))

.price(BigDecimal.valueOf(30.22))

.title("Title 55")

.build();

}

public static ProductCatalog getProductCatId4ForUpdate() {

return ProductCatalog.builder()

115

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

.id(4)

.price(BigDecimal.valueOf(40.00))

.title("Title 1")

.build();

}

public static MovieActor getMovieActorBlanchett() {

MovieActor movieActor = new MovieActor();

movieActor.setActorName("Cate Blanchett");

movieActor.setMovieName("Blue Jasmine");

movieActor.setActingYear(2013);

movieActor.setActingAward("Best Actress");

movieActor.setActingSchoolName("National Institute of Dramatic Art");

return movieActor;

}

The DynamoDB tables contain the following items before the code example runs.

1 | ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}

2 | MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best

Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}

3 | MovieActor{movieName='Tar', actorName='Cate Blanchett', actingAward='Best Actress',

actingYear=2022, actingSchoolName='National Institute of Dramatic Art'}

The following items are in the tables after the code ﬁnishes running.

ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}

MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best

Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}

MovieActor{movieName='Tar', actorName='Cate Blanchett', actingAward='Best Actress',

actingYear=2022, actingSchoolName='National Institute of Dramatic Art'}

Items remain unchanged in the tables because the transaction failed. The actingYear value for

the movie Sophie's Choice is 1982, as shown on line 2 of the items in the table before the

transactWriteItem() method is called.

To capture the cancellation information for the transaction, enclose the transactWriteItems()

method call in a try block and catch the TransactionCanceledException. After comment line 4

of the example, the code logs each CancellationReason object. Because the code following comment

line 3 of the example speciﬁes that values should be returned for the item that caused the transaction to

fail, the log displays the raw database values for the Sophie's Choice movie item.

CancellationReason(Code=None)

CancellationReason(Item={actor=AttributeValue(S=Meryl Streep),

movie=AttributeValue(S=Sophie's Choice), actingaward=AttributeValue(S=Best Actress),

actingyear=AttributeValue(N=1982), actingschoolname=AttributeValue(S=Yale School of

Drama)}, ¬

Code=ConditionalCheckFailed, Message=The conditional request failed.)

Single operation condition example

The following example shows the use of a condition on a single operation in a transaction request. The

delete operation after comment line 1 contains a condition that checks the value of the target item of

the operation against the database. In this example, the condition expression created with the helper

method after comment line 2 speciﬁes that the item should be deleted from the database if the acting

year of the movie is not equal to 2013.

Expressions (p. 96) are discussed later in this guide.

116

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

public static void singleOperationConditionFailExample(DynamoDbEnhancedClient

enhancedClient,

DynamoDbTable<ProductCatalog>

catalogTable,

DynamoDbTable<MovieActor>

movieActorTable) {

try {

enhancedClient.transactWriteItems(b -> b

.addPutItem(catalogTable,

TransactPutItemEnhancedRequest.builder(ProductCatalog.class)

.item(getProductCatId2())

.build())

.addUpdateItem(catalogTable,

TransactUpdateItemEnhancedRequest.builder(ProductCatalog.class)

.item(getProductCatId4ForUpdate())

.ignoreNulls(Boolean.TRUE).build())

// 1. Delete operation that contains a condition expression

.addDeleteItem(movieActorTable,

TransactDeleteItemEnhancedRequest.builder()

.key((Key.Builder k) -> {

MovieActor blanchett = getMovieActorBlanchett();

k.partitionValue(blanchett.getMovieName())

.sortValue(blanchett.getActorName());

})

.conditionExpression(buildDeleteItemExpression())

.returnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)

.build())

.build());

} catch (TransactionCanceledException ex) {

ex.cancellationReasons().forEach(cancellationReason ->

logger.info(cancellationReason.toString()));

}

// 2. Provide condition expression to check if 'actingyear' is not equal to 2013.

private static Expression buildDeleteItemExpression() {

Map<String, AttributeValue> expressionValue = Map.of(

":year", numberValue(2013));

return Expression.builder()

.expression("actingyear <> :year")

.expressionValues(expressionValue)

.build();

}

The following helper methods are used in the previous code example.

Helper methods

public static ProductCatalog getProductCatId2() {

return ProductCatalog.builder()

.id(2)

.isbn("1-565-85698")

.authors(new HashSet<>(Arrays.asList("a", "b")))

.price(BigDecimal.valueOf(30.22))

.title("Title 55")

.build();

}

public static ProductCatalog getProductCatId4ForUpdate() {

return ProductCatalog.builder()

.id(4)

.price(BigDecimal.valueOf(40.00))

117

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

.title("Title 1")

.build();

}

public static MovieActor getMovieActorBlanchett() {

MovieActor movieActor = new MovieActor();

movieActor.setActorName("Cate Blanchett");

movieActor.setMovieName("Blue Jasmine");

movieActor.setActingYear(2013);

movieActor.setActingAward("Best Actress");

movieActor.setActingSchoolName("National Institute of Dramatic Art");

return movieActor;

}

The DynamoDB tables contain the following items before the code example runs.

1 | ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}

2 | MovieActor{movieName='Blue Jasmine', actorName='Cate Blanchett', actingAward='Best

Actress', actingYear=2013, actingSchoolName='National Institute of Dramatic Art'}

The following items are in the tables after the code ﬁnishes running.

ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}

2023-03-15 11:29:07 [main] INFO org.example.tests.TransactDemoTest:168 -

MovieActor{movieName='Blue Jasmine', actorName='Cate Blanchett', actingAward='Best

Actress', actingYear=2013, actingSchoolName='National Institute of Dramatic Art'}

Items remain unchanged in the tables because the transaction failed. The actingYear value for the

movie Blue Jasmine is 2013 as shown on line 2 in the list of items before the code example runs.

The following lines are logged to the console.

CancellationReason(Code=None)

CancellationReason(Item={actor=AttributeValue(S=Cate Blanchett),

movie=AttributeValue(S=Blue Jasmine), actingaward=AttributeValue(S=Best Actress),

actingyear=AttributeValue(N=2013), actingschoolname=AttributeValue(S=National Institute of

Dramatic Art)},

Code=ConditionalCheckFailed, Message=The conditional request failed)

Secondary indices

Secondary indices improve data access by deﬁning alternative keys that you use in query and scan

operations. Global secondary indices (GSI) have a partition key and a sort key that can be diﬀerent from

those on the base table. In contrast, local secondary indices (LSI) use the partition key of the primary

index.

Annotate data class with secondary index annotations

Attributes that participate in secondary indices require either the @DynamoDbSecondaryPartitionKey

or @DynamoDbSecondarySortKey annotation.

The following class shows annotations for two indices. The GSI named SubjectLastPostedDateIndex uses

the Subject attribute for the partition key and the LastPostedDateTime for the sort key. The LSI

named ForumLastPostedDateIndex uses the ForumName as its partition key and LastPostedDateTime

as its sort key.

Note that the Subject attribute serves a dual role. It is the primary key's sort key and the partition key

of the GSI named SubjectLastPostedDateIndex.

118

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

MessageThread class

The MessageThread class is suitable to use as a data class for the example Thread table in the Amazon

DynamoDB Developer Guide.

Imports

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;

import

software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondaryPartitionKey;

import

software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondarySortKey;

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSortKey;

import java.util.List;

@DynamoDbBean

public class MessageThread {

private String ForumName;

private String Subject;

private String Message;

private String LastPostedBy;

private String LastPostedDateTime;

private Integer Views;

private Integer Replies;

private Integer Answered;

private List<String> Tags;

@DynamoDbPartitionKey

public String getForumName() {

return ForumName;

}

public void setForumName(String forumName) {

ForumName = forumName;

}

// Sort key for primary index and partition key for GSI "SubjectLastPostedDateIndex".

@DynamoDbSortKey

@DynamoDbSecondaryPartitionKey(indexNames = "SubjectLastPostedDateIndex")

public String getSubject() {

return Subject;

}

public void setSubject(String subject) {

Subject = subject;

}

// Sort key for GSI "SubjectLastPostedDateIndex" and sort key for LSI

"ForumLastPostedDateIndex".

@DynamoDbSecondarySortKey(indexNames = {"SubjectLastPostedDateIndex",

"ForumLastPostedDateIndex"})

public String getLastPostedDateTime() {

return LastPostedDateTime;

}

public void setLastPostedDateTime(String lastPostedDateTime) {

LastPostedDateTime = lastPostedDateTime;

}

public String getMessage() {

return Message;

}

119

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

public void setMessage(String message) {

Message = message;

}

public String getLastPostedBy() {

return LastPostedBy;

}

public void setLastPostedBy(String lastPostedBy) {

LastPostedBy = lastPostedBy;

}

public Integer getViews() {

return Views;

}

public void setViews(Integer views) {

Views = views;

}

@DynamoDbSecondaryPartitionKey(indexNames = "ForumRepliesIndex")

public Integer getReplies() {

return Replies;

}

public void setReplies(Integer replies) {

Replies = replies;

}

public Integer getAnswered() {

return Answered;

}

public void setAnswered(Integer answered) {

Answered = answered;

}

public List<String> getTags() {

return Tags;

}

public void setTags(List<String> tags) {

Tags = tags;

}

public MessageThread() {

this.Answered = 0;

this.LastPostedBy = "";

this.ForumName = "";

this.Message = "";

this.LastPostedDateTime = "";

this.Replies = 0;

this.Views = 0;

this.Subject = "";

}

@Override

public String toString() {

return "MessageThread{" +

"ForumName='" + ForumName + '\'' +

", Subject='" + Subject + '\'' +

", Message='" + Message + '\'' +

", LastPostedBy='" + LastPostedBy + '\'' +

", LastPostedDateTime='" + LastPostedDateTime + '\'' +

", Views=" + Views +

", Replies=" + Replies +

120

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

", Answered=" + Answered +

", Tags=" + Tags +

'}';

}

Create the index

Beginning with version 2.20.86 of the SDK for Java, the createTable() method automatically

generates secondary indexes from data class annotations. By default, all attributes from the base table

are copied to an index and the provisioned throughput values are 20 read capacity units and 20 write

capacity units.

However, if you use an SDK version prior to 2.20.86, you need to build the index along with the table as

shown in the following example. This example builds the two indexes for the Thread table. The builder

parameter has methods to conﬁgure both types of indexes as shown after comment lines 1 and 2. You

use the index builder's indexName() method to associate the index names speciﬁed in the data class

annotations with the intended type of index.

This code conﬁgures all of the table attributes to end up in both indexes after comment lines 3 and 4.

More information about attribute projections is available in the Amazon DynamoDB Developer Guide.

public static void createMessageThreadTable(DynamoDbTable<MessageThread>

messageThreadDynamoDbTable, DynamoDbClient dynamoDbClient) {

messageThreadDynamoDbTable.createTable(b -> b

// 1. Generate the GSI.

.globalSecondaryIndices(gsi -> gsi.indexName("SubjectLastPostedDateIndex")

// 3. Populate the GSI with all attributes.

.projection(p -> p

.projectionType(ProjectionType.ALL))

)

// 2. Generate the LSI.

.localSecondaryIndices(lsi -> lsi.indexName("ForumLastPostedDateIndex")

// 4. Populate the LSI with all attributes.

.projection(p -> p

.projectionType(ProjectionType.ALL))

)

);

Query by using an index

The following example queries the local secondary index ForumLastPostedDateIndex.

Following comment line 2, you create a QueryConditional object that is required when calling the

DynamoDbIndex.query() method.

You get a reference to the index you want to query after comment line 3 by passing in the name

of the index. Following comment line 4, you call the query() method on the index passing in the

QueryConditional object.

You also conﬁgure the query to return three attribute values as shown after comment line 5. If

attributesToProject() is not called, the query returns all attribute values. Notice that the speciﬁed

attribute names begin with lowercase letters. These attribute names match those used in the table, not

necessarily the attribute names of the data class.

Following comment line 6, iterate through the results and log each item returned by the query and also

store it in the list to return to the caller.

public static List<MessageThread> queryUsingSecondaryIndices(DynamoDbEnhancedClient

enhancedClient,

121

AWS SDK for Java 2.x Developer Guide for version 2.x

Basics

String lastPostedDate,

DynamoDbTable<MessageThread> threadTable) {

// 1. Log the parameter value.

logger.info("lastPostedDate value: {}", lastPostedDate);

// 2. Create a QueryConditional whose sort key value must be greater than or equal

to the parameter value.

QueryConditional queryConditional = QueryConditional.sortGreaterThanOrEqualTo(qc ->

qc.partitionValue("Forum02").sortValue(lastPostedDate));

// 3. Specify the index name to query the DynamoDbIndex instance.

final DynamoDbIndex<MessageThread> forumLastPostedDateIndex =

threadTable.index("ForumLastPostedDateIndex");

// 4. Perform the query by using the QueryConditional object.

final SdkIterable<Page<MessageThread>> pagedResult =

forumLastPostedDateIndex.query(q -> q

.queryConditional(queryConditional)

// 5. Request three attribute in the results.

.attributesToProject("forumName", "subject", "lastPostedDateTime"));

List<MessageThread> collectedItems = new ArrayList<>();

// 6. Iterate through the pages response and sort the items.

pagedResult.stream().forEach(page -> page.items().stream()

.sorted(Comparator.comparing(MessageThread::getLastPostedDateTime))

.forEach(mt -> {

// 7. Log the returned items and add the collection to return

to the caller.

logger.info(mt.toString());

collectedItems.add(mt);

}));

return collectedItems;

}

The following items exist in the database before the query is run.

MessageThread{ForumName='Forum01', Subject='Subject01', Message='Message01',

LastPostedBy='', LastPostedDateTime='2023.03.28', Views=0, Replies=0, Answered=0,

Tags=null}

MessageThread{ForumName='Forum02', Subject='Subject02', Message='Message02',

LastPostedBy='', LastPostedDateTime='2023.03.29', Views=0, Replies=0, Answered=0,

Tags=null}

MessageThread{ForumName='Forum02', Subject='Subject04', Message='Message04',

LastPostedBy='', LastPostedDateTime='2023.03.31', Views=0, Replies=0, Answered=0,

Tags=null}

MessageThread{ForumName='Forum02', Subject='Subject08', Message='Message08',

LastPostedBy='', LastPostedDateTime='2023.04.04', Views=0, Replies=0, Answered=0,

Tags=null}

MessageThread{ForumName='Forum02', Subject='Subject10', Message='Message10',

LastPostedBy='', LastPostedDateTime='2023.04.06', Views=0, Replies=0, Answered=0,

Tags=null}

MessageThread{ForumName='Forum03', Subject='Subject03', Message='Message03',

LastPostedBy='', LastPostedDateTime='2023.03.30', Views=0, Replies=0, Answered=0,

Tags=null}

MessageThread{ForumName='Forum03', Subject='Subject06', Message='Message06',

LastPostedBy='', LastPostedDateTime='2023.04.02', Views=0, Replies=0, Answered=0,

Tags=null}

MessageThread{ForumName='Forum03', Subject='Subject09', Message='Message09',

LastPostedBy='', LastPostedDateTime='2023.04.05', Views=0, Replies=0, Answered=0,

Tags=null}

MessageThread{ForumName='Forum05', Subject='Subject05', Message='Message05',

LastPostedBy='', LastPostedDateTime='2023.04.01', Views=0, Replies=0, Answered=0,

Tags=null}

122

AWS SDK for Java 2.x Developer Guide for version 2.x

Extensions

MessageThread{ForumName='Forum07', Subject='Subject07', Message='Message07',

LastPostedBy='', LastPostedDateTime='2023.04.03', Views=0, Replies=0, Answered=0,

Tags=null}

The logging statements at lines 1 and 6 result in the following console output.

lastPostedDate value: 2023.03.31

MessageThread{ForumName='Forum02', Subject='Subject04', Message='', LastPostedBy='',

LastPostedDateTime='2023.03.31', Views=0, Replies=0, Answered=0, Tags=null}

MessageThread{ForumName='Forum02', Subject='Subject08', Message='', LastPostedBy='',

LastPostedDateTime='2023.04.04', Views=0, Replies=0, Answered=0, Tags=null}

MessageThread{ForumName='Forum02', Subject='Subject10', Message='', LastPostedBy='',

LastPostedDateTime='2023.04.06', Views=0, Replies=0, Answered=0, Tags=null}

The query returned items with a forumName value of Forum02 and a lastPostedDateTime value

greater than or equal to 2023.03.31. The results show message values with an empty string although

the message attributes have values in the index. This is because the message attribute was not projected

after comment line 5.

Extensions

The DynamoDB Enhanced Client API supports plugin extensions that provide functionality beyond

mapping operations. Extensions have two hook methods, beforeWrite() and afterRead().

beforeWrite() modiﬁes a write operation before it happens, and the afterRead() method modiﬁes

the results of a read operation after it happens. Because some operations (such as item updates) perform

both a write and then a read, both hook methods are called.

Extensions are loaded in the order that they are speciﬁed in the enhanced client builder. The load order

can be important because one extension can act on values that have been transformed by a previous

extension.

The enhanced client API comes with a set of plugin extensions that are located in the extensions

package. By default, the enhanced client loads the VersionedRecordExtension and the

AtomicCounterExtension. You can override the default behavior with the enhance client builder and

load any extension. You can also specify none if you don't want the default extensions.

If you load your own extensions, the enhanced client doesn't load any default extensions. If you want the

behavior provided by either default extension, you need to explicitly add it to the list of extensions.

In the following example, a custom extension named verifyChecksumExtension is loaded

after the VersionedRecordExtension, which is usually loaded by default by itself. The

AtomicCounterExtension is not loaded in this example.

DynamoDbEnhancedClientExtension versionedRecordExtension =

VersionedRecordExtension.builder().build();

DynamoDbEnhancedClient enhancedClient =

DynamoDbEnhancedClient.builder()

.dynamoDbClient(dynamoDbClient)

.extensions(versionedRecordExtension, verifyChecksumExtension)

.build();

VersionedRecordExtension

The VersionedRecordExtension is loaded by default and will increment and track an item version

number as items are written to the database. A condition will be added to every write that causes

123

AWS SDK for Java 2.x Developer Guide for version 2.x

Extensions

the write to fail if the version number of the actual persisted item doesn't match the value that the

application last read. This behavior eﬀectively provides optimistic locking for item updates. If another

process updates an item between the time the ﬁrst process has read the item and is writing an update to

it, the write will fail.

To specify which attribute to use to track the item version number, tag a numeric attribute in the table

schema.

The following snippet speciﬁes that the version attribute should hold the item version number.

@DynamoDbVersionAttribute

public Integer getVersion() {...};

public void setVersion(Integer version) {...};

The equivalent static table schema approach is shown in the following snippet.

.addAttribute(Integer.class, a -> a.name("version")

.getter(Customer::getVersion)

.setter(Customer::setVersion)

// Apply the 'version' tag to the attribute.

.tags(VersionedRecordExtension.AttributeTags.versionAttribute())

AtomicCounterExtension

The AtomicCounterExtension is loaded by default and increments a tagged numerical attribute each

time a record is written to the database. Start and increment values can be speciﬁed. If no values are

speciﬁed, the start value is set to 0 and the attribute's value increments by 1.

To specify which attribute is a counter, tag an attribute of type Long in the table schema.

The following snippet shows the use of the default start and increment values for the counter

attribute.

@DynamoDbAtomicCounter

public Long getCounter() {...};

public void setCounter(Long counter) {...};

The static table schema approach is shown in the following snippet. The atomic counter extension uses a

start value of 10 and increments the value by 5 each time the record is written.

.addAttribute(Integer.class, a -> a.name("counter")

.getter(Customer::getCounter)

.setter(Customer::setCounter)

// Apply the 'atomicCounter' tag to the attribute

with start and increment values.

.tags(StaticAttributeTags.atomicCounter(10L, 5L))

AutoGeneratedTimestampRecordExtension

The AutoGeneratedTimestampRecordExtension automatically updates tagged attributes of type

Instant with a current timestamp every time the item is successfully written to the database.

This extension is not loaded by default. Therefore, you need to specify it as a custom extension when you

build the enhanced client as shown in the ﬁrst example in this topic.

124

AWS SDK for Java 2.x Developer Guide for version 2.x

Extensions

To specify which attribute to update with the current timestamp, tag the Instant attribute in the table

schema.

The lastUpdate attribute is the target of the extensions behavior in the following snippet. Note the

requirement that the attribute must be an Instant type.

@DynamoDbAutoGeneratedTimestampAttribute

public Instant getLastUpdate() {...}

public void setLastUpdate(Instant lastUpdate) {...}

The equivalent static table schema approach is shown in the following snippet.

.addAttribute(Instant.class, a -> a.name("lastUpdate")

.getter(Customer::getLastUpdate)

.setter(Customer::setLastUpdate)

// Applying the 'autoGeneratedTimestamp' tag to the

attribute.

.tags(AutoGeneratedTimestampRecordExtension.AttributeTags.autoGeneratedTimestampAttribute())

Custom extensions

The following custom extension class shows a beforeWrite() method that uses an update expression.

After comment line 2, we create a SetAction to set the registrationDate attribute if the item in

the database doesn't already have a registrationDate attribute. Whenever a Customer object is

updated, the extension makes sure that a registrationDate is set.

public final class CustomExtension implements DynamoDbEnhancedClientExtension {

// 1. In a custom extension, use an UpdateExpression to define what action to take

before

// an item is updated.

@Override

public WriteModification beforeWrite(DynamoDbExtensionContext.BeforeWrite context) {

if ( context.operationContext().tableName().equals("Customer")

&& context.operationName().equals(OperationName.UPDATE_ITEM)) {

return WriteModification.builder()

.updateExpression(createUpdateExpression())

.build();

}

return WriteModification.builder().build(); // Return an "empty" WriteModification

instance if the extension should not be applied.

// In this case, if the code is not

updating an item on the Customer table.

}

private static UpdateExpression createUpdateExpression() {

// 2. Use a SetAction, a subclass of UpdateAction, to provide the values in the

update.

SetAction setAction =

SetAction.builder()

.path("registrationDate")

.value("if_not_exists(registrationDate, :regValue)")

.putExpressionValue(":regValue",

AttributeValue.fromS(Instant.now().toString()))

.build();

// 3. Build the UpdateExpression with one or more UpdateAction.

return UpdateExpression.builder()

.addAction(setAction)

.build();

125

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

}

Advanced table schema features

Learn about advanced table schema features in the DynamoDB Enhanced Client API.

Schema overview

TableSchema is the interface to the mapping functionality of the DynamoDB Enhanced Client API. It

can map a data object to and from a map of AttributeValues. A TableSchema object needs to know

about the structure of the table it is mapping. This structure information is stored in a TableMetadata

object.

The enhanced client API has several implementations of TableSchema, which follow.

Table schema generated from annotated classes

It is a moderately expensive operation to build a TableSchema from annotated classes, so we

recommend doing this once, at application startup.

BeanTableSchema

This implementation is built based on attributes and annotations of a bean class. An example of this

approach is demonstrated in the Get started section (p. 82).

Note

If a BeanTableSchema is not behaving as you expect, enable debug logging for

software.amazon.awssdk.enhanced.dynamodb.beans.

ImmutableTableSchema

This implementation is built from an immutable data class. This approach is described in the

??? (p. 94) section.

Table schema generated with a builder

The following TableSchemas are built from code by using a builder. This approach is less costly than

the approach that uses annotated data classes. The builder approach avoids the use of annotations and

doesn't require JavaBean naming standards.

StaticTableSchema

This implementation is built for mutable data classes. The getting started section of this guide

demonstrated how to generate a StaticTableSchema using a builder (p. 83).

StaticImmutableTableSchema

Similarly to how you build a StaticTableSchema, you generate an implementation of this type of

TableSchema using a builder for use with immutable data classes.

Table schema for data without a ﬁxed schema

DocumentTableSchema

Unlike other implementations of TableSchema, you don't deﬁne attributes for a

DocumentTableSchema instance. Usually, you specify only primary keys and attribute converter

126

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

providers. An EnhancedDocument instance provides the attributes that you build from individual

elements or from a JSON string.

Explicitly include or exclude attributes

The DynamoDB Enhanced Client API oﬀers annotations to exclude data class attributes from becoming

attributes on a table. With the API, you can also use an attribute name that's diﬀerent from the data

class attribute name.

Exclude attributes

To ignore attributes that should not be mapped to a DynamoDB table, mark the attribute with the

@DynamoDbIgnore annotation.

private String internalKey;

@DynamoDbIgnore

public String getInternalKey() { return this.internalKey; }

public void setInternalKey(String internalKey) { return this.internalKey = internalKey;}

Include attributes

To change the name of an attribute used in the DynamoDB table, mark it with the

@DynamoDbAttribute annotation and supply a diﬀerent name.

private String internalKey;

@DynamoDbAttribute("renamedInternalKey")

public String getInternalKey() { return this.internalKey; }

public void setInternalKey(String internalKey) { return this.internalKey = internalKey;}

Control attribute conversion

By default, a table schema provides converters for all primitive types and many common Java types

through a default implementation of the AttributeConverterProvider interface. You can change

the overall default behavior with a custom AttributeConverterProvider implementation. You can

also change the converter for a single attribute.

For a list of available converters, see the AttributeConverter interface Java doc.

Provide custom attribute converter providers

You can provide a single AttributeConverterProvider or a chain of ordered

AttributeConverterProviders through the @DynamoDbBean (converterProviders

= {…}) annotation. Any custom AttributeConverterProvider must extend the

AttributeConverterProvider interface.

Note that if you supply your own chain of attribute converter providers, you will override the default

converter provider, DefaultAttributeConverterProvider. If you want to use the functionality of

the DefaultAttributeConverterProvider, you must include it in the chain.

It's also possible to annotate the bean with an empty array {}. This disables the use of any attribute

converter providers, including the default. In this case all attributes that are to be mapped must have

their own attribute converter.

The following snippet shows a single converter provider.

127

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

@DynamoDbBean(converterProviders = ConverterProvider1.class)

public class Customer {

}

The following snippet shows the use of a chain of converter providers. Since the SDK default is provided

last, it has the lowest priority.

@DynamoDbBean(converterProviders = {

ConverterProvider1.class,

ConverterProvider2.class,

DefaultAttributeConverterProvider.class})

public class Customer {

}

The static table schema builders have an attributeConverterProviders() method that works the

same way. This is shown in the following snippet.

private static final StaticTableSchema<Customer> CUSTOMER_TABLE_SCHEMA =

StaticTableSchema.builder(Customer.class)

.newItemSupplier(Customer::new)

.addAttribute(String.class, a -> a.name("name")

a.getter(Customer::getName)

a.setter(Customer::setName))

.attributeConverterProviders(converterProvider1, converterProvider2)

.build();

Override the mapping of a single attribute

To override the way a single attribute is mapped, supply an AttributeConverter for the attribute.

This addition overrides any converters provided by AttributeConverterProviders in the table

schema. This adds a custom converter for only that attribute. Other attributes, even those of the same

type, won't use that converter unless it is explicitly speciﬁed for those other attributes.

The @DynamoDbConvertedBy annotation is used to specify the custom AttributeConverter class as

shown in the following snippet.

@DynamoDbBean

public class Customer {

private String name;

@DynamoDbConvertedBy(CustomAttributeConverter.class)

public String getName() { return this.name; }

public void setName(String name) { this.name = name;}

}

The builders for static schemas have an equivalent attribute builder attributeConverter() method.

This method takes an instance of an AttributeConverter as the following shows.

private static final StaticTableSchema<Customer> CUSTOMER_TABLE_SCHEMA =

StaticTableSchema.builder(Customer.class)

.newItemSupplier(Customer::new)

.addAttribute(String.class, a -> a.name("name")

a.getter(Customer::getName)

a.setter(Customer::setName)

a.attributeConverter(customAttributeConverter))

128

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

.build();

Example

This example shows an AttributeConverterProvider implementation that provides an attribute

converter for java.net.HttpCookie objects.

The following SimpleUser class contains an attribute named lastUsedCookie that is an instance of

HttpCookie.

The parameter to the @DynamoDbBean annotations lists the two AttributeConverterProvider

classes that provide converters.

Class with annotations

@DynamoDbBean(converterProviders = {CookieConverterProvider.class,

DefaultAttributeConverterProvider.class})

public static final class SimpleUser {

private String name;

private HttpCookie lastUsedCookie;

@DynamoDbPartitionKey

public String getName() {

return name;

}

public void setName(String name) {

this.name = name;

}

public HttpCookie getLastUsedCookie() {

return lastUsedCookie;

}

public void setLastUsedCookie(HttpCookie lastUsedCookie) {

this.lastUsedCookie = lastUsedCookie;

}

Static table schema

private static final TableSchema<SimpleUser> SIMPLE_USER_TABLE_SCHEMA =

TableSchema.builder(SimpleUser.class)

.newItemSupplier(SimpleUser::new)

.attributeConverterProviders(CookieConverterProvider.create(),

AttributeConverterProvider.defaultProvider())

.addAttribute(String.class, a -> a.name("name")

.setter(SimpleUser::setName)

.getter(SimpleUser::getName)

.tags(StaticAttributeTags.primaryPartitionKey()))

.addAttribute(HttpCookie.class, a -> a.name("lastUsedCookie")

.setter(SimpleUser::setLastUsedCookie)

.getter(SimpleUser::getLastUsedCookie))

.build();

The CookieConverterProvider in the following example provides an instance of an

HttpCookeConverter.

public static final class CookieConverterProvider implements AttributeConverterProvider

{

129

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

private final Map<EnhancedType<?>, AttributeConverter<?>> converterCache =

ImmutableMap.of(

// 1. Add HttpCookieConverter to the internal cache.

EnhancedType.of(HttpCookie.class), new HttpCookieConverter());

public static CookieConverterProvider create() {

return new CookieConverterProvider();

}

// The SDK calls this method to find out if the provider contains a

AttributeConverter instance

// for the EnhancedType<T> argument.

@SuppressWarnings("unchecked")

@Override

public <T> AttributeConverter<T> converterFor(EnhancedType<T> enhancedType) {

return (AttributeConverter<T>) converterCache.get(enhancedType);

}

Conversion code

In the transformFrom() method of the following HttpCookieConverter class, the code receives an

HttpCookie instance and transforms it into a DynamoDB map that is stored as an attribute.

The transformTo() method receives a DynamoDB map parameter, then invokes the HttpCookie

constructor that requires a name and a value.

public static final class HttpCookieConverter implements AttributeConverter<HttpCookie>

{

@Override

public AttributeValue transformFrom(HttpCookie httpCookie) {

return AttributeValue.fromM(

Map.of ("cookieName", AttributeValue.fromS(httpCookie.getName()),

"cookieValue", AttributeValue.fromS(httpCookie.getValue()))

);

}

@Override

public HttpCookie transformTo(AttributeValue attributeValue) {

Map<String, AttributeValue> map = attributeValue.m();

return new HttpCookie(

map.get("cookieName").s(),

map.get("cookieValue").s());

}

@Override

public EnhancedType<HttpCookie> type() {

return EnhancedType.of(HttpCookie.class);

}

@Override

public AttributeValueType attributeValueType() {

return AttributeValueType.M;

}

Change update behavior of attributes

You can customize the update behavior of individual attributes when you perform an update operation.

Some examples of update operations in the DynamoDB Enhanced Client API are updateItem() and

transactWriteItems().

130

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

For example, imagine that you want to store a created on timestamp on your record. However, you want

its value to be written only if there's no existing value for the attribute already in the database. In this

case, you use the WRITE_IF_NOT_EXISTS update behavior.

The following example shows the annotation that adds the behavior to the createdOn attribute.

@DynamoDbBean

public class Customer extends GenericRecord {

private String id;

private Instant createdOn;

@DynamoDbPartitionKey

public String getId() { return this.id; }

public void setId(String id) { this.name = id; }

@DynamoDbUpdateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS)

public Instant getCreatedOn() { return this.createdOn; }

public void setCreatedOn(Instant createdOn) { this.createdOn = createdOn; }

}

You can declare the same update behavior when you build a static table schema as shown in the

following example after comment line 1.

static final TableSchema<Customer> CUSTOMER_TABLE_SCHEMA =

TableSchema.builder(Customer.class)

.newItemSupplier(Customer::new)

.addAttribute(String.class, a -> a.name("id")

.getter(Customer::getId)

.setter(Customer::setId)

.tags(StaticAttributeTags.primaryPartitionKey()))

.addAttribute(Instant.class, a -> a.name("createdOn")

.getter(Customer::getCreatedOn)

.setter(Customer::setCreatedOn)

// 1. Add an UpdateBehavior.

.tags(StaticAttributeTags.updateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS)))

.build();

Flatten attributes from other classes

If the attributes for your table are spread across several diﬀerent Java classes, either through inheritance

or composition, the DynamoDB Enhanced Client API provides support to ﬂatten the attributes into one

class.

Use inheritance

If your classes use inheritance, use the following approaches to ﬂatten the hierarchy.

Use annotated beans

For the annotation approach, both classes must carry the @DynamoDbBean annotation and a class must

carry one or more primary key annotations.

The following shows examples of data classes that have an inheritance relationship.

Standard data class

@DynamoDbBean

public class Customer extends GenericRecord {

private String name;

131

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

public String getName() { return name; }

public void setName(String name) { this.name = name; }

}

@DynamoDbBean

public abstract class GenericRecord {

private String id;

private String createdDate;

@DynamoDbPartitionKey

public String getId() { return id; }

public void setId(String id) { this.id = id; }

public String getCreatedDate() { return createdDate; }

public void setCreatedDate(String createdDate) { this.createdDate = createdDate; }

}

Lombok

Lombok's onMethod option copies attribute-based DynamoDB annotations, such as

@DynamoDbPartitionKey, onto the generated code.

@DynamoDbBean

@Data

@ToString(callSuper = true)

public class Customer extends GenericRecord {

private String name;

}

@Data

@DynamoDbBean

public abstract class GenericRecord {

@Getter(onMethod_=@DynamoDbPartitionKey)

private String id;

private String createdDate;

}

Use static schemas

For the static schema approach, use the extend() method of the builder to collapse the attributes of

the parent class onto the child class. This is shown after comment line 1 in the following example.

StaticTableSchema<org.example.tests.model.inheritance.stat.GenericRecord>

GENERIC_RECORD_SCHEMA =

StaticTableSchema.builder(org.example.tests.model.inheritance.stat.GenericRecord.class)

// The partition key will be inherited by the top level mapper.

.addAttribute(String.class, a -> a.name("id")

.getter(org.example.tests.model.inheritance.stat.GenericRecord::getId)

.setter(org.example.tests.model.inheritance.stat.GenericRecord::setId)

.tags(primaryPartitionKey()))

.addAttribute(String.class, a -> a.name("created_date")

.getter(org.example.tests.model.inheritance.stat.GenericRecord::getCreatedDate)

.setter(org.example.tests.model.inheritance.stat.GenericRecord::setCreatedDate))

.build();

StaticTableSchema<org.example.tests.model.inheritance.stat.Customer>

CUSTOMER_SCHEMA =

132

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

StaticTableSchema.builder(org.example.tests.model.inheritance.stat.Customer.class)

.newItemSupplier(org.example.tests.model.inheritance.stat.Customer::new)

.addAttribute(String.class, a -> a.name("name")

.getter(org.example.tests.model.inheritance.stat.Customer::getName)

.setter(org.example.tests.model.inheritance.stat.Customer::setName))

// 1. Use the extend() method to collapse the parent attributes

onto the child class.

.extend(GENERIC_RECORD_SCHEMA) // All the attributes of the

GenericRecord schema are added to Customer.

.build();

The previous static schema example uses the following data classes. Because the mapping is deﬁned

when you build the static table schema, the data classes don't require annotations.

Data classes

Standard data class

public class Customer extends GenericRecord {

private String name;

public String getName() { return name; }

public void setName(String name) { this.name = name; }

}

public abstract class GenericRecord {

private String id;

private String createdDate;

public String getId() { return id; }

public void setId(String id) { this.id = id; }

public String getCreatedDate() { return createdDate; }

public void setCreatedDate(String createdDate) { this.createdDate = createdDate; }

Lombok

@Data

@ToString(callSuper = true)

public class Customer extends GenericRecord{

private String name;

}

@Data

public abstract class GenericRecord {

private String id;

private String createdDate;

}

Use composition

If your classes use composition, use the following approaches to ﬂatten the hierarchy.

Use annotated beans

The @DynamoDbFlatten annotation ﬂattens the contained class.

133

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

The following data class examples use the @DynamoDbFlatten annotation to eﬀectively add all

attributes of the contained GenericRecord class to the Customer class.

Standard data class

@DynamoDbBean

public class Customer {

private String name;

private GenericRecord record;

public String getName() { return this.name; }

public void setName(String name) { this.name = name; }

@DynamoDbFlatten

public GenericRecord getRecord() { return this.record; }

public void setRecord(GenericRecord record) { this.record = record; }

@DynamoDbBean

public class GenericRecord {

private String id;

private String createdDate;

@DynamoDbPartitionKey

public String getId() { return this.id; }

public void setId(String id) { this.id = id; }

public String getCreatedDate() { return this.createdDate; }

public void setCreatedDate(String createdDate) { this.createdDate = createdDate; }

}

Lombok

@Data

@DynamoDbBean

public class Customer {

private String name;

@Getter(onMethod_=@DynamoDbFlatten)

private GenericRecord record;

}

@Data

@DynamoDbBean

public class GenericRecord {

@Getter(onMethod_=@DynamoDbPartitionKey)

private String id;

private String createdDate;

}

You can use the ﬂatten annotation to ﬂatten as many diﬀerent eligible classes as you need to. The

following constraints apply:

• All attribute names must be unique after they are ﬂattened.

• There must never be more than one partition key, sort key, or table name.

Use static schemas

When you build a static table schema, use the flatten() method of the builder. You also supply the

getter and setter methods that identify the contained class.

StaticTableSchema<GenericRecord> GENERIC_RECORD_SCHEMA =

134

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

StaticTableSchema.builder(GenericRecord.class)

.newItemSupplier(GenericRecord::new)

.addAttribute(String.class, a -> a.name("id")

.getter(GenericRecord::getId)

.setter(GenericRecord::setId)

.tags(primaryPartitionKey()))

.addAttribute(String.class, a -> a.name("created_date")

.getter(GenericRecord::getCreatedDate)

.setter(GenericRecord::setCreatedDate))

.build();

StaticTableSchema<Customer> CUSTOMER_SCHEMA =

StaticTableSchema.builder(Customer.class)

.newItemSupplier(Customer::new)

.addAttribute(String.class, a -> a.name("name")

.getter(Customer::getName)

.setter(Customer::setName))

// Because we are flattening a component object, we supply a getter

and setter so the

// mapper knows how to access it.

.flatten(GENERIC_RECORD_SCHEMA, Customer::getRecord,

Customer::setRecord)

.build();

The previous static schema example uses the following data classes.

Data classes

Standard data class

public class Customer {

private String name;

private GenericRecord record;

public String getName() { return this.name; }

public void setName(String name) { this.name = name; }

public GenericRecord getRecord() { return this.record; }

public void setRecord(GenericRecord record) { this.record = record; }

public class GenericRecord {

private String id;

private String createdDate;

public String getId() { return this.id; }

public void setId(String id) { this.id = id; }

public String getCreatedDate() { return this.createdDate; }

public void setCreatedDate(String createdDate) { this.createdDate = createdDate; }

}

Lombok

@Data

public class Customer {

private String name;

private GenericRecord record;

}

@Data

public class GenericRecord {

private String id;

private String createdDate;

135

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

}

You can use the builder pattern to ﬂatten as many diﬀerent eligible classes as you need to.

Implications for other code

When you use the @DynamoDbFlatten attribute (or flatten() builder method), the item in

DynamoDB contains an attribute for each attribute of the composed object. It also includes the

attributes of the composing object.

In contrast, if you annotate a data class with a composed class and don't use @DynamoDbFlatten, the

item is saved with the composed object as a single attribute.

For example, compare the Customer class shown in the ﬂattening with composition example (p. 133)

with and without ﬂattening of the record attribute. You can visualize the diﬀerence with JSON as

shown in the following table.

With ﬂattening Without ﬂattening

3 attributes 2 attributes

{

"id": "1",

"createdDate": "today",

"name": "my name"

}

{

"id": "1",

"record": {

"createdDate": "today",

"name": "my name"

}

The diﬀerence becomes important if you have other code accessing the DynamoDB table that expects to

ﬁnd certain attributes.

Work with nested attributes

A nested attribute in DynamoDB is embedded in another attribute. Examples are list elements and map

entries.

In Java, a DynamoDB nested attribute corresponds to a member of a class that is a List or Map. It

also corresponds to an instance of a complex type, such as Address or PhoneNumber, as used in the

following Person class.

Person class

@DynamoDbBean

public class Person {

Integer id;

String firstName;

String lastName;

Integer age;

Map<String, Address> addresses;

List<PhoneNumber> phoneNumbers;

List<String> hobbies;

@DynamoDbPartitionKey

public Integer getId() {

136

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

return id;

}

public void setId(Integer id) {

this.id = id;

}

public String getFirstName() {

return firstName;

}

public void setFirstName(String firstName) {

this.firstName = firstName;

}

public String getLastName() {

return lastName;

}

public void setLastName(String lastName) {

this.lastName = lastName;

}

public Integer getAge() {

return age;

}

public void setAge(Integer age) {

this.age = age;

}

public Map<String, Address> getAddresses() {

return addresses;

}

public void setAddresses(Map<String, Address> addresses) {

this.addresses = addresses;

}

public List<PhoneNumber> getPhoneNumbers() {

return phoneNumbers;

}

public void setPhoneNumbers(List<PhoneNumber> phoneNumbers) {

this.phoneNumbers = phoneNumbers;

}

public List<String> getHobbies() {

return hobbies;

}

public void setHobbies(List<String> hobbies) {

this.hobbies = hobbies;

}

@Override

public String toString() {

return "Person{" +

"id=" + id +

", firstName='" + firstName + '\'' +

", lastName='" + lastName + '\'' +

", age=" + age +

", addresses=" + addresses +

", phoneNumbers=" + phoneNumbers +

", hobbies=" + hobbies +

'}';

137

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

}

Address class

@DynamoDbBean

public class Address {

private String street;

private String city;

private String state;

private String zipCode;

public Address() {

}

public String getStreet() {

return this.street;

}

public String getCity() {

return this.city;

}

public String getState() {

return this.state;

}

public String getZipCode() {

return this.zipCode;

}

public void setStreet(String street) {

this.street = street;

}

public void setCity(String city) {

this.city = city;

}

public void setState(String state) {

this.state = state;

}

public void setZipCode(String zipCode) {

this.zipCode = zipCode;

}

@Override

public boolean equals(Object o) {

if (this == o) return true;

if (o == null || getClass() != o.getClass()) return false;

Address address = (Address) o;

return Objects.equals(street, address.street) && Objects.equals(city, address.city)

&& Objects.equals(state, address.state) && Objects.equals(zipCode, address.zipCode);

}

@Override

public int hashCode() {

return Objects.hash(street, city, state, zipCode);

}

@Override

public String toString() {

return "Address{" +

138

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

"street='" + street + '\'' +

", city='" + city + '\'' +

", state='" + state + '\'' +

", zipCode='" + zipCode + '\'' +

'}';

}

PhoneNumber class

@DynamoDbBean

public class PhoneNumber {

String type;

String number;

public String getType() {

return type;

}

public void setType(String type) {

this.type = type;

}

public String getNumber() {

return number;

}

public void setNumber(String number) {

this.number = number;

}

@Override

public String toString() {

return "PhoneNumber{" +

"type='" + type + '\'' +

", number='" + number + '\'' +

'}';

}

Map nested attributes

Use annotated classes

You can save nested attributes for custom classes by annotating them. The Address class and

PhoneNumber class shown previously are annotated with only the @DynamoDbBean annotation.

When the DynamoDB Enhanced Client API builds the table schema for the Person class with the

following snippet, the API discovers the use of the Address and PhoneNumber classes and builds the

corresponding mappings to work with DynamoDB.

TableSchema<Person> personTableSchema = TableSchema.fromBean(Person.class);

Use nested schemas

The alternative approach is to use static table schema builders for each of the classes as shown in the

following code.

The table schemas for the Address and PhoneNumber classes are abstract in the sense that they cannot

be used with a DynamoDB table. This is because they lack deﬁnitions for the primary key. They are used,

however, as nested schemas in the table schema for the Person class.

139

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

After comment lines 1 and 2 in the deﬁnition of PERSON_TABLE_SCHEMA, you see the code that uses the

abstract table schemas. The use of documentOf in the EnhanceType.documentOf(...) method does

not indicate that the method returns an EnhancedDocument type of the Enhanced Document API. The

documentOf(...) method in this context returns an object that knows how to map its class argument

to and from DynamoDB table attributes by using the table schema argument.

Static schema code

// Abstract table schema that cannot be used to work with a DynamoDB table,

// but can be used as a nested schema.

public static final TableSchema<Address> TABLE_SCHEMA_ADDRESS =

TableSchema.builder(Address.class)

.newItemSupplier(Address::new)

.addAttribute(String.class, a -> a.name("street")

.getter(Address::getStreet)

.setter(Address::setStreet))

.addAttribute(String.class, a -> a.name("city")

.getter(Address::getCity)

.setter(Address::setCity))

.addAttribute(String.class, a -> a.name("zipcode")

.getter(Address::getZipCode)

.setter(Address::setZipCode))

.addAttribute(String.class, a -> a.name("state")

.getter(Address::getState)

.setter(Address::setState))

.build();

// Abstract table schema that cannot be used to work with a DynamoDB table,

// but can be used as a nested schema.

public static final TableSchema<PhoneNumber> TABLE_SCHEMA_PHONENUMBER =

TableSchema.builder(PhoneNumber.class)

.newItemSupplier(PhoneNumber::new)

.addAttribute(String.class, a -> a.name("type")

.getter(PhoneNumber::getType)

.setter(PhoneNumber::setType))

.addAttribute(String.class, a -> a.name("number")

.getter(PhoneNumber::getNumber)

.setter(PhoneNumber::setNumber))

.build();

// A static table schema that can be used with a DynamoDB table.

// The table schema contains two nested schemas that are used to perform mapping to/

from DynamoDB.

public static final TableSchema<Person> PERSON_TABLE_SCHEMA =

TableSchema.builder(Person.class)

.newItemSupplier(Person::new)

.addAttribute(Integer.class, a -> a.name("id")

.getter(Person::getId)

.setter(Person::setId)

.addTag(StaticAttributeTags.primaryPartitionKey()))

.addAttribute(String.class, a -> a.name("firstName")

.getter(Person::getFirstName)

.setter(Person::setFirstName))

.addAttribute(String.class, a -> a.name("lastName")

.getter(Person::getLastName)

.setter(Person::setLastName))

.addAttribute(Integer.class, a -> a.name("age")

.getter(Person::getAge)

.setter(Person::setAge))

.addAttribute(EnhancedType.listOf(String.class), a -> a.name("hobbies")

.getter(Person::getHobbies)

.setter(Person::setHobbies))

.addAttribute(EnhancedType.mapOf(

EnhancedType.of(String.class),

140

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

// 1. Use mapping functionality of the Address table schema.

EnhancedType.documentOf(Address.class, TABLE_SCHEMA_ADDRESS)),

a -> a.name("addresses")

.getter(Person::getAddresses)

.setter(Person::setAddresses))

.addAttribute(EnhancedType.listOf(

// 2. Use mapping functionality of the PhoneNumber table

schema.

EnhancedType.documentOf(PhoneNumber.class,

TABLE_SCHEMA_PHONENUMBER)), a -> a.name("phoneNumbers")

.getter(Person::getPhoneNumbers)

.setter(Person::setPhoneNumbers))

.build();

Project nested attributes

For query() and scan() methods, you can specify which attributes you want to be returned

in the results by using method calls such as addNestedAttributeToProject() and

attributesToProject(). The DynamoDB Enhanced Client API converts the Java method call

parameters into projection expressions before the request is sent.

The following example populates the Person table with two items, then performs three scan operations.

The ﬁrst scan accesses all items in the table in order to compare the results to the other scan operations.

The second scan uses the addNestedAttributeToProject() builder method to return only the

street attribute value.

The third scan operation uses the attributesToProject() builder method to return the data for

the ﬁrst-level attribute, hobbies. The attribute type of hobbies is a list. To access individual list items,

perform a get() operation on the list.

personDynamoDbTable = getDynamoDbEnhancedClient().table("Person",

PERSON_TABLE_SCHEMA);

PersonUtils.createPersonTable(personDynamoDbTable, getDynamoDbClient());

// Use a utility class to add items to the Person table.

List<Person> personList = PersonUtils.getItemsForCount(2);

// This utility method performs a put against DynamoDB to save the instances in the

list argument.

PersonUtils.putCollection(getDynamoDbEnhancedClient(), personList,

personDynamoDbTable);

// The first scan logs all items in the table to compare to the results of the

subsequent scans.

final PageIterable<Person> allItems = personDynamoDbTable.scan();

allItems.items().forEach(p ->

// 1. Log what is in the table.

logger.info(p.toString()));

// Scan for nested attributes.

PageIterable<Person> streetScanResult = personDynamoDbTable.scan(b -> b

// Use the 'addNestedAttributeToProject()' or

'addNestedAttributesToProject()' to access data nested in maps in DynamoDB.

.addNestedAttributeToProject(

NestedAttributeName.create("addresses", "work", "street")

));

streetScanResult.items().forEach(p ->

//2. Log the results of requesting nested attributes.

logger.info(p.toString()));

// Scan for a top-level list attribute.

141

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

PageIterable<Person> phoneNumbersScanResult = personDynamoDbTable.scan(b -> b

// Use the 'attributesToProject()' method to access first-level attributes.

.attributesToProject("hobbies"));

phoneNumbersScanResult.items().forEach((p) -> {

// 3. Log the results of the request for the 'hobbies' attribute.

logger.info(p.toString());

// To access an item in a list, first get the parent attribute, 'hobbies', then

access items in the list.

String hobby = p.getHobbies().get(1);

// 4. Log an item in the list.

logger.info(hobby);

});

// Logged results from comment line 1.

Person{id=2, firstName='first name 2', lastName='last name 2', age=11,

addresses={work=Address{street='street 21', city='city 21', state='state 21',

zipCode='33333'}, home=Address{street='street 2', city='city 2', state='state 2',

zipCode='22222'}}, phoneNumbers=[PhoneNumber{type='home', number='222-222-2222'},

PhoneNumber{type='work', number='333-333-3333'}], hobbies=[hobby 2, hobby 21]}

Person{id=1, firstName='first name 1', lastName='last name 1', age=11,

addresses={work=Address{street='street 11', city='city 11', state='state 11',

zipCode='22222'}, home=Address{street='street 1', city='city 1', state='state 1',

zipCode='11111'}}, phoneNumbers=[PhoneNumber{type='home', number='111-111-1111'},

PhoneNumber{type='work', number='222-222-2222'}], hobbies=[hobby 1, hobby 11]}

// Logged results from comment line 2.

Person{id=null, firstName='null', lastName='null', age=null,

addresses={work=Address{street='street 21', city='null', state='null', zipCode='null'}},

phoneNumbers=null, hobbies=null}

Person{id=null, firstName='null', lastName='null', age=null,

addresses={work=Address{street='street 11', city='null', state='null', zipCode='null'}},

phoneNumbers=null, hobbies=null}

// Logged results from comment lines 3 and 4.

Person{id=null, firstName='null', lastName='null', age=null, addresses=null,

phoneNumbers=null, hobbies=[hobby 2, hobby 21]}

hobby 21

Person{id=null, firstName='null', lastName='null', age=null, addresses=null,

phoneNumbers=null, hobbies=[hobby 1, hobby 11]}

hobby 11

Note

If the attributesToProject() method follows any other builder method that

adds attributes that you want to project, the list of attribute names supplied to the

attributesToProject() replaces all other attribute names.

A scan performed with the ScanEnhancedRequest instance in the following snippet returns

only hobby data.

ScanEnhancedRequest lastOverwrites = ScanEnhancedRequest.builder()

.addNestedAttributeToProject(

NestedAttributeName.create("addresses", "work", "street"))

.addAttributeToProject("firstName")

// If the 'attributesToProject()' method follows other builder methods that

add attributes for projection,

// its list of attributes replace all previous attributes.

.attributesToProject("hobbies")

.build();

PageIterable<Person> hobbiesOnlyResult = personDynamoDbTable.scan(lastOverwrites);

hobbiesOnlyResult.items().forEach(p ->

logger.info(p.toString()));

// Logged results.

142

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

Person{id=null, firstName='null', lastName='null', age=null, addresses=null,

phoneNumbers=null, hobbies=[hobby 2, hobby 21]}

Person{id=null, firstName='null', lastName='null', age=null, addresses=null,

phoneNumbers=null, hobbies=[hobby 1, hobby 11]}

The following code snippet uses the attributesToProject() method ﬁrst. This ordering

preserves all other requested attributes.

ScanEnhancedRequest attributesPreserved = ScanEnhancedRequest.builder()

// Use 'attributesToProject()' first so that the method call does not

replace all other attributes

// that you want to project.

.attributesToProject("firstName")

.addNestedAttributeToProject(

NestedAttributeName.create("addresses", "work", "street"))

.addAttributeToProject("hobbies")

.build();

PageIterable<Person> allAttributesResult =

personDynamoDbTable.scan(attributesPreserved);

allAttributesResult.items().forEach(p ->

logger.info(p.toString()));

// Logged results.

Person{id=null, firstName='first name 2', lastName='null', age=null,

addresses={work=Address{street='street 21', city='null', state='null',

zipCode='null'}}, phoneNumbers=null, hobbies=[hobby 2, hobby 21]}

Person{id=null, firstName='first name 1', lastName='null', age=null,

addresses={work=Address{street='street 11', city='null', state='null',

zipCode='null'}}, phoneNumbers=null, hobbies=[hobby 1, hobby 11]}

Preserve empty objects with

@DynamoDbPreserveEmptyObject

If you save a bean to Amazon DynamoDB with empty objects and you want the SDK to

recreate the empty objects upon retrieval, annotate the getter of the inner bean with

@DynamoDbPreserveEmptyObject.

To illustrate how the annotation works, the code example uses the following two beans.

Example beans

The following data class contains two InnerBean ﬁelds. The getter method,

getInnerBeanWithoutAnno(), is not annotated with @DynamoDbPreserveEmptyObject. The

getInnerBeanWithAnno() method is annotated.

@DynamoDbBean

public class MyBean {

private String id;

private String name;

private InnerBean innerBeanWithoutAnno;

private InnerBean innerBeanWithAnno;

@DynamoDbPartitionKey

public String getId() { return id; }

public void setId(String id) { this.id = id; }

public String getName() { return name; }

public void setName(String name) { this.name = name; }

143

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

public InnerBean getInnerBeanWithoutAnno() { return innerBeanWithoutAnno; }

public void setInnerBeanWithoutAnno(InnerBean innerBeanWithoutAnno)

{ this.innerBeanWithoutAnno = innerBeanWithoutAnno; }

@DynamoDbPreserveEmptyObject

public InnerBean getInnerBeanWithAnno() { return innerBeanWithAnno; }

public void setInnerBeanWithAnno(InnerBean innerBeanWithAnno) { this.innerBeanWithAnno

= innerBeanWithAnno; }

@Override

public String toString() {

return new StringJoiner(", ", MyBean.class.getSimpleName() + "[", "]")

.add("innerBeanWithoutAnno=" + innerBeanWithoutAnno)

.add("innerBeanWithAnno=" + innerBeanWithAnno)

.add("id='" + id + "'")

.add("name='" + name + "'")

.toString();

}

Instances of the following InnerBean class are ﬁelds of MyBean and are initialized as empty objects in

the example code.

@DynamoDbBean

public class InnerBean {

private String innerBeanField;

public String getInnerBeanField() {

return innerBeanField;

}

public void setInnerBeanField(String innerBeanField) {

this.innerBeanField = innerBeanField;

}

@Override

public String toString() {

return "InnerBean{" +

"innerBeanField='" + innerBeanField + '\'' +

'}';

}

The following code example saves a MyBean object with initialized inner beans to DynamoDB and then

retrieves the item. The logged output shows that the innerBeanWithoutAnno is not initialized, but

innerBeanWithAnno has been created.

public MyBean preserveEmptyObjectAnnoUsingGetItemExample(DynamoDbTable<MyBean>

myBeanTable) {

// Save an item to DynamoDB.

MyBean bean = new MyBean();

bean.setId("1");

bean.setInnerBeanWithoutAnno(new InnerBean()); // Instantiate the inner bean.

bean.setInnerBeanWithAnno(new InnerBean()); // Instantiate the inner bean.

myBeanTable.putItem(bean);

GetItemEnhancedRequest request = GetItemEnhancedRequest.builder()

.key(Key.builder().partitionValue("1").build())

.build();

MyBean myBean = myBeanTable.getItem(request);

logger.info(myBean.toString());

144

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

// Output 'MyBean[innerBeanWithoutAnno=null,

innerBeanWithAnno=InnerBean{innerBeanField='null'}, id='1', name='null']'.

return myBean;

}

Alternative static schema

You can use the following StaticTableSchema version of the table schemas in place of the

annotations on the beans.

public static TableSchema<MyBean> buildStaticSchemas() {

StaticTableSchema<InnerBean> innerBeanStaticTableSchema =

StaticTableSchema.builder(InnerBean.class)

.newItemSupplier(InnerBean::new)

.addAttribute(String.class, a -> a.name("innerBeanField")

.getter(InnerBean::getInnerBeanField)

.setter(InnerBean::setInnerBeanField))

.build();

return StaticTableSchema.builder(MyBean.class)

.newItemSupplier(MyBean::new)

.addAttribute(String.class, a -> a.name("id")

.getter(MyBean::getId)

.setter(MyBean::setId)

.addTag(primaryPartitionKey()))

.addAttribute(String.class, a -> a.name("name")

.getter(MyBean::getName)

.setter(MyBean::setName))

.addAttribute(EnhancedType.documentOf(InnerBean.class,

innerBeanStaticTableSchema),

a -> a.name("innerBean1")

.getter(MyBean::getInnerBeanWithoutAnno)

.setter(MyBean::setInnerBeanWithoutAnno))

.addAttribute(EnhancedType.documentOf(InnerBean.class,

innerBeanStaticTableSchema,

b -> b.preserveEmptyObject(true)),

a -> a.name("innerBean2")

.getter(MyBean::getInnerBeanWithAnno)

.setter(MyBean::setInnerBeanWithAnno))

.build();

}

Avoid saving null attributes of nested objects

You can skip null attributes of nested objects when saving a data class object to DynamoDB by applying

the @DynamoDbIgnoreNulls annotation. By contrast, top-level attributes with null values are never

saved to the database.

To illustrate how the annotation works, the code example uses the following two beans.

Example beans

The following data class contains two InnerBean ﬁelds. The getter method,

getInnerBeanWithoutAnno(), is not annotated. The getInnerBeanWithIgnoreNullsAnno()

method is annotated with @DynamoDbIgnoreNulls.

@DynamoDbBean

public class MyBean {

private String id;

145

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

private String name;

private InnerBean innerBeanWithoutAnno;

private InnerBean innerBeanWithIgnoreNullsAnno;

@DynamoDbPartitionKey

public String getId() { return id; }

public void setId(String id) { this.id = id; }

public String getName() { return name; }

public void setName(String name) { this.name = name; }

public InnerBean getInnerBeanWithoutAnno() { return innerBeanWithoutAnno; }

public void setInnerBeanWithoutAnno(InnerBean innerBeanWithoutAnno)

{ this.innerBeanWithoutAnno = innerBeanWithoutAnno; }

@DynamoDbIgnoreNulls

public InnerBean getInnerBeanWithIgnoreNullsAnno() { return

innerBeanWithIgnoreNullsAnno; }

public void setInnerBeanWithIgnoreNullsAnno(InnerBean innerBeanWithAnno)

{ this.innerBeanWithIgnoreNullsAnno = innerBeanWithAnno; }

@Override

public String toString() {

return new StringJoiner(", ", MyBean.class.getSimpleName() + "[", "]")

.add("innerBeanWithoutAnno=" + innerBeanWithoutAnno)

.add("innerBeanWithIgnoreNullsAnno=" + innerBeanWithIgnoreNullsAnno)

.add("id='" + id + "'")

.add("name='" + name + "'")

.toString();

}

Instances of the following InnerBean class are ﬁelds of MyBean and are used in the following example

code.

@DynamoDbBean

public class InnerBean {

private String innerBeanFieldString;

private Integer innerBeanFieldInteger;

public String getInnerBeanFieldString() { return innerBeanFieldString; }

public void setInnerBeanFieldString(String innerBeanFieldString)

{ this.innerBeanFieldString = innerBeanFieldString; }

public Integer getInnerBeanFieldInteger() { return innerBeanFieldInteger; }

public void setInnerBeanFieldInteger(Integer innerBeanFieldInteger)

{ this.innerBeanFieldInteger = innerBeanFieldInteger; }

@Override

public String toString() {

return new StringJoiner(", ", InnerBean.class.getSimpleName() + "[", "]")

.add("innerBeanFieldString='" + innerBeanFieldString + "'")

.add("innerBeanFieldInteger=" + innerBeanFieldInteger)

.toString();

}

The following code example creates an InnerBean object and sets only one of its two attributes with a

value.

public void ignoreNullsAnnoUsingPutItemExample(DynamoDbTable<MyBean> myBeanTable) {

// Create an InnerBean object and give only one attribute a value.

146

AWS SDK for Java 2.x Developer Guide for version 2.x

Advanced table schema features

InnerBean innerBeanOneAttributeSet = new InnerBean();

innerBeanOneAttributeSet.setInnerBeanFieldInteger(200);

// Create a MyBean instance and use the same InnerBean instance both for

attributes.

MyBean bean = new MyBean();

bean.setId("1");

bean.setInnerBeanWithoutAnno(innerBeanOneAttributeSet);

bean.setInnerBeanWithIgnoreNullsAnno(innerBeanOneAttributeSet);

Map<String, AttributeValue> itemMap = myBeanTable.tableSchema().itemToMap(bean,

true);

logger.info(itemMap.toString());

// Log the map that is sent to the database.

//

{innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)}),

id=AttributeValue(S=1),

innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200),

innerBeanFieldString=AttributeValue(NUL=true)})}

// Save the MyBean object to the table.

myBeanTable.putItem(bean);

}

To visualize the low-level data that is sent to DynamoDB, the code logs the attribute map before saving

the MyBean object.

The logged output shows that the innerBeanWithIgnoreNullsAnno outputs one attribute,

innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)})

The innerBeanWithoutAnno instance outputs two attributes. One attribute has a value of 200 and the

other is a null-valued attribute.

innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200),

innerBeanFieldString=AttributeValue(NUL=true)})

JSON representation of the attribute map

The following JSON representation makes it easier to see the data that is saved to DynamoDB.

{

"id": {

"S": "1"

},

"innerBeanWithIgnoreNullsAnno": {

"M": {

"innerBeanFieldInteger": {

"N": "200"

}

},

"innerBeanWithoutAnno": {

"M": {

"innerBeanFieldInteger": {

"N": "200"

},

"innerBeanFieldString": {

"NULL": true

}

147

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

}

Alternative static schema

You can use the following StaticTableSchema version of the table schemas in place data class

annotations.

public static TableSchema<MyBean> buildStaticSchemas() {

StaticTableSchema<InnerBean> innerBeanStaticTableSchema =

StaticTableSchema.builder(InnerBean.class)

.newItemSupplier(InnerBean::new)

.addAttribute(String.class, a -> a.name("innerBeanFieldString")

.getter(InnerBean::getInnerBeanFieldString)

.setter(InnerBean::setInnerBeanFieldString))

.addAttribute(Integer.class, a -> a.name("innerBeanFieldInteger")

.getter(InnerBean::getInnerBeanFieldInteger)

.setter(InnerBean::setInnerBeanFieldInteger))

.build();

return StaticTableSchema.builder(MyBean.class)

.newItemSupplier(MyBean::new)

.addAttribute(String.class, a -> a.name("id")

.getter(MyBean::getId)

.setter(MyBean::setId)

.addTag(primaryPartitionKey()))

.addAttribute(String.class, a -> a.name("name")

.getter(MyBean::getName)

.setter(MyBean::setName))

.addAttribute(EnhancedType.documentOf(InnerBean.class,

innerBeanStaticTableSchema),

a -> a.name("innerBeanWithoutAnno")

.getter(MyBean::getInnerBeanWithoutAnno)

.setter(MyBean::setInnerBeanWithoutAnno))

.addAttribute(EnhancedType.documentOf(InnerBean.class,

innerBeanStaticTableSchema,

b -> b.ignoreNulls(true)),

a -> a.name("innerBeanWithIgnoreNullsAnno")

.getter(MyBean::getInnerBeanWithIgnoreNullsAnno)

.setter(MyBean::setInnerBeanWithIgnoreNullsAnno))

.build();

}

Enhanced Document API for DynamoDB

The Enhanced Document API for AWS SDK for Java 2.x is designed to work with document-oriented data

that has no ﬁxed schema. However, it also lets you use custom classes to map individual attributes.

The Enhanced Document API is the successor to the Document API of the AWS SDK for Java v1.x.

Contents

• Preliminary steps to work with the Enhanced Document API (p. 149)

• Create a DocumentTableSchema and a DynamoDbTable (p. 149)

• Build enhanced documents (p. 150)

• Build from a JSON string (p. 150)

• Build from individual elements (p. 150)

• Perform CRUD operations (p. 151)

• Access enhanced document attributes as custom objects (p. 152)

• Use an EnhancedDocument without DynamoDB (p. 156)

148

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

Preliminary steps to work with the Enhanced Document API

The Enhanced Document API requires the same dependencies (p. 81) that are needed for the

DynamoDB Enhanced Client API. It also requires a DynamoDbEnhancedClient instance (p. 84) as

shown at the start of this topic.

Because the Enhanced Document API was released with version 2.20.3 of the AWS SDK for Java 2.x, you

need that version or greater.

Create a DocumentTableSchema and a DynamoDbTable

To invoke commands against a DynamoDB table using the Enhanced Document API, associate the table

with a client-side DynamoDbTable<EnhancedDocument> resource object.

The enhanced client's table() method creates a DynamoDbTable<EnhancedDocument> instance and

requires parameters for the DynamoDB table name and a DocumentTableSchema.

The builder for a DocumentTableSchema requires a primary index key and one or more attribute

converter providers. The AttributeConverterProvider.defaultProvider() method provides

converters for default types. It should be speciﬁed even if you provide a custom attribute converter

provider. You can add an optional secondary index key to the builder.

The following code snippet shows the code that generates the client-side representation of a DynamoDB

person table that stores schemaless EnhancedDocument objects.

DynamoDbTable<EnhancedDocument> documentDynamoDbTable =

enhancedClient.table("person",

TableSchema.documentSchemaBuilder()

// Specify the primary key attributes.

.addIndexPartitionKey(TableMetadata.primaryIndexName(),"id",

AttributeValueType.S)

.addIndexSortKey(TableMetadata.primaryIndexName(), "lastName",

AttributeValueType.S)

// Specify attribute converter providers. Minimally add the

default one.

.attributeConverterProviders(AttributeConverterProvider.defaultProvider())

.build());

// Call documentTable.createTable() if "person" does not exist in DynamoDB.

// createTable() should be called only one time.

The following shows the JSON representation of a person object that is used throughout this section.

JSON person object

{

"id": 1,

"firstName": "Richard",

"lastName": "Roe",

"age": 25,

"addresses":

{

"home": {

"zipCode": "00000",

"city": "Any Town",

"state": "FL",

"street": "123 Any Street"

},

"work": {

"zipCode": "00001",

"city": "Anywhere",

149

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

"state": "FL",

"street": "100 Main Street"

}

},

"hobbies": [

"Hobby 1",

"Hobby 2"

],

"phoneNumbers": [

{

"type": "Home",

"number": "555-0100"

},

{

"type": "Work",

"number": "555-0119"

}

]

}

Build enhanced documents

An EnhancedDocument represents a document-type object that has complex structure with nested

attributes. An EnhancedDocument requires top-level attributes that match the primary key attributes

speciﬁed for the DocumentTableSchema. The remaining content is arbitrary and can consist of top-

level attributes and also deeply nested attributes.

You create an EnhancedDocument instance by using a builder that provides several ways to add

elements.

Build from a JSON string

With a JSON string, you can build an EnhancedDocument in one method call. The following snippet

creates an EnhancedDocument from a JSON string returned by the jsonPerson() helper method.

The jsonPerson() method returns the JSON string version of the person object (p. 149) shown

previously.

EnhancedDocument document =

EnhancedDocument.builder()

.json( jsonPerson() )

.build());

Build from individual elements

Alternatively, you can build an EnhancedDocument instance from individual components using type-

safe methods of the builder.

The following example builds a person enhanced document similar to the enhanced document that is

built from the JSON string in the previous example.

/* Define the shape of an address map whose JSON representation looks like the

following.

Use 'addressMapEnhancedType' in the following EnhancedDocument.builder() to

simplify the code.

"home": {

"zipCode": "00000",

"city": "Any Town",

"state": "FL",

"street": "123 Any Street"

}*/

EnhancedType<Map<String, String>> addressMapEnhancedType =

150

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

EnhancedType.mapOf(EnhancedType.of(String.class),

EnhancedType.of(String.class));

// Use the builder's typesafe methods to add elements to the enhanced document.

EnhancedDocument personDocument = EnhancedDocument.builder()

.putNumber("id", 50)

.putString("firstName", "Shirley")

.putString("lastName", "Rodriguez")

.putNumber("age", 53)

.putNull("nullAttribute")

.putJson("phoneNumbers", phoneNumbersJSONString())

/* Add the map of addresses whose JSON representation looks like the

following.

{

"home": {

"zipCode": "00000",

"city": "Any Town",

"state": "FL",

"street": "123 Any Street"

}

} */

.putMap("addresses", getAddresses(), EnhancedType.of(String.class),

addressMapEnhancedType)

.putList("hobbies", List.of("Theater", "Golf"),

EnhancedType.of(String.class))

.build();

Helper methods

private static String phoneNumbersJSONString() {

return " [" +

" {" +

" \"type\": \"Home\"," +

" \"number\": \"555-0140\"" +

" }," +

" {" +

" \"type\": \"Work\"," +

" \"number\": \"555-0155\"" +

" }" +

" ]";

}

private static Map<String, Map<String, String>> getAddresses() {

return Map.of(

"home", Map.of(

"zipCode", "00002",

"city", "Any Town",

"state", "ME",

"street", "123 Any Street"));

}

Perform CRUD operations

After you deﬁne an EnhancedDocument instance, you can save it to a DynamoDB table. The following

code snippet uses the personDocument (p. 150) that was created from individual elements.

documentDynamoDbTable.putItem(personDocument);

After you read an enhanced document instance from DynamoDB, you can extract the individual attribute

values using getters as shown in the following code snippet that access the data saved from the

151

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

personDocument. Alternatively, you can extract the complete content to a JSON string as shown in the

last part of the example code.

// Read the item.

EnhancedDocument personDocFromDb =

documentDynamoDbTable.getItem(Key.builder().partitionValue(50).build());

// Access top-level attributes.

logger.info("Name: {} {}", personDocFromDb.getString("firstName"),

personDocFromDb.getString("lastName"));

// Name: Shirley Rodriguez

// Typesafe access of a deeply nested attribute. The addressMapEnhancedType shown

previously defines the shape of an addresses map.

Map<String, Map<String, String>> addresses = personDocFromDb.getMap("addresses",

EnhancedType.of(String.class), addressMapEnhancedType);

addresses.keySet().forEach(k -> logger.info(addresses.get(k).toString()));

// {zipCode=00002, city=Any Town, street=123 Any Street, state=ME}

// Alternatively, work with AttributeValue types checking along the way for deeply

nested attributes.

Map<String, AttributeValue> addressesMap =

personDocFromDb.getMapOfUnknownType("addresses");

addressesMap.keySet().forEach((String k) -> {

logger.info("Looking at data for [{}] address", k);

// Looking at data for [home] address

AttributeValue value = addressesMap.get(k);

AttributeValue cityValue = value.m().get("city");

if (cityValue != null) {

logger.info(cityValue.s());

// Any Town

}

});

List<AttributeValue> phoneNumbers =

personDocFromDb.getListOfUnknownType("phoneNumbers");

phoneNumbers.forEach((AttributeValue av) -> {

if (av.hasM()) {

AttributeValue type = av.m().get("type");

if (type.s() != null) {

logger.info("Type of phone: {}", type.s());

// Type of phone: Home

// Type of phone: Work

}

});

String jsonPerson = personDocFromDb.toJson();

logger.info(jsonPerson);

// {"firstName":"Shirley","lastName":"Rodriguez","addresses":{"home":

{"zipCode":"00002","city":"Any Town","street":"123 Any Street","state":"ME"}},"hobbies":

["Theater","Golf"],

// "id":50,"nullAttribute":null,"age":53,"phoneNumbers":

[{"number":"555-0140","type":"Home"},{"number":"555-0155","type":"Work"}]}

EnhancedDocument instances can be used with any method of DynamoDbTable or

DynamoDbEnhancedClient in place of mapped data classes.

Access enhanced document attributes as custom objects

In addition to providing an API to read and write attributes with schemaless structures, the Enhanced

Document API lets you convert attributes to and from instances of custom classes.

152

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

The Enhanced Document API uses AttributeConverterProviders and AttributeConverters that

were shown in the control attribute conversion (p. 127) section as part of the DynamoDB Enhanced

Client API.

In the following example, we use a CustomAttributeConverterProvider with its nested

AddressConverter class to convert Address objects.

This example shows that you can mix data from classes and also data from structures that are built as

needed. This example also shows that custom classes can be used at any level of a nested structure. The

Address objects in this example are values used in a map.

public static void attributeToAddressClassMappingExample(DynamoDbEnhancedClient

enhancedClient, DynamoDbClient standardClient) {

String tableName = "customer";

// Define the DynamoDbTable for an enhanced document.

// The schema builder provides methods for attribute converter providers and keys.

DynamoDbTable<EnhancedDocument> documentDynamoDbTable =

enhancedClient.table(tableName,

DocumentTableSchema.builder()

// Add the CustomAttributeConverterProvider along with the default

when you build the table schema.

.attributeConverterProviders(

List.of(

new CustomAttributeConverterProvider(),

AttributeConverterProvider.defaultProvider()))

.addIndexPartitionKey(TableMetadata.primaryIndexName(), "id",

AttributeValueType.N)

.addIndexSortKey(TableMetadata.primaryIndexName(), "lastName",

AttributeValueType.S)

.build());

// Create the DynamoDB table if needed.

documentDynamoDbTable.createTable();

waitForTableCreation(tableName, standardClient);

// The getAddressesForCustomMappingExample() helper method that provides

'addresses' shows the use of a custom Address class

// rather than using a Map<String, Map<String, String> to hold the address data.

Map<String, Address> addresses = getAddressesForCustomMappingExample();

// Build an EnhancedDocument instance to save an item with a mix of structures

defined as needed and static classes.

EnhancedDocument personDocument = EnhancedDocument.builder()

.putNumber("id", 50)

.putString("firstName", "Shirley")

.putString("lastName", "Rodriguez")

.putNumber("age", 53)

.putNull("nullAttribute")

.putJson("phoneNumbers", phoneNumbersJSONString())

// Note the use of 'EnhancedType.of(Address.class)' instead of the more

generic

// 'EnhancedType.mapOf(EnhancedType.of(String.class),

EnhancedType.of(String.class))' that was used in a previous example.

.putMap("addresses", addresses, EnhancedType.of(String.class),

EnhancedType.of(Address.class))

.putList("hobbies", List.of("Hobby 1", "Hobby 2"),

EnhancedType.of(String.class))

.build();

// Save the item to DynamoDB.

documentDynamoDbTable.putItem(personDocument);

// Retrieve the item just saved.

153

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

EnhancedDocument srPerson =

documentDynamoDbTable.getItem(Key.builder().partitionValue(50).sortValue("Rodriguez").build());

// Access the addresses attribute.

Map<String, Address> srAddresses = srPerson.get("addresses",

EnhancedType.mapOf(EnhancedType.of(String.class),

EnhancedType.of(Address.class)));

srAddresses.keySet().forEach(k -> logger.info(addresses.get(k).toString()));

documentDynamoDbTable.deleteTable();

// The content logged to the console shows that the saved maps were converted to Address

instances.

Address{street='123 Main Street', city='Any Town', state='NC', zipCode='00000'}

Address{street='100 Any Street', city='Any Town', state='NC', zipCode='00000'}

CustomAttributeConverterProvider code

public class CustomAttributeConverterProvider implements AttributeConverterProvider {

private final Map<EnhancedType<?>, AttributeConverter<?>> converterCache =

ImmutableMap.of(

// 1. Add AddressConverter to the internal cache.

EnhancedType.of(Address.class), new AddressConverter());

public static CustomAttributeConverterProvider create() {

return new CustomAttributeConverterProvider();

}

// 2. The enhanced client queries the provider for attribute converters if it

// encounters a type that it does not know how to convert.

@SuppressWarnings("unchecked")

@Override

public <T> AttributeConverter<T> converterFor(EnhancedType<T> enhancedType) {

return (AttributeConverter<T>) converterCache.get(enhancedType);

}

// 3. Custom attribute converter

private class AddressConverter implements AttributeConverter<Address> {

// 4. Transform an Address object into a DynamoDB map.

@Override

public AttributeValue transformFrom(Address address) {

Map<String, AttributeValue> attributeValueMap = Map.of(

"street", AttributeValue.fromS(address.getStreet()),

"city", AttributeValue.fromS(address.getCity()),

"state", AttributeValue.fromS(address.getState()),

"zipCode", AttributeValue.fromS(address.getZipCode()));

return AttributeValue.fromM(attributeValueMap);

}

// 5. Transform the DynamoDB map attribute to an Address oject.

@Override

public Address transformTo(AttributeValue attributeValue) {

Map<String, AttributeValue> m = attributeValue.m();

Address address = new Address();

address.setStreet(m.get("street").s());

address.setCity(m.get("city").s());

address.setState(m.get("state").s());

address.setZipCode(m.get("zipCode").s());

return address;

154

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

}

@Override

public EnhancedType<Address> type() {

return EnhancedType.of(Address.class);

}

@Override

public AttributeValueType attributeValueType() {

return AttributeValueType.M;

}

Address class

public class Address {

private String street;

private String city;

private String state;

private String zipCode;

public Address() {

}

public String getStreet() {

return this.street;

}

public String getCity() {

return this.city;

}

public String getState() {

return this.state;

}

public String getZipCode() {

return this.zipCode;

}

public void setStreet(String street) {

this.street = street;

}

public void setCity(String city) {

this.city = city;

}

public void setState(String state) {

this.state = state;

}

public void setZipCode(String zipCode) {

this.zipCode = zipCode;

}

Helper method that provides addresses

The following helper method provides the map that use custom Address instances for values rather

than generic Map<String, String> instances for values.

155

AWS SDK for Java 2.x Developer Guide for version 2.x

Enhanced Document API

private static Map<String, Address> getAddressesForCustomMappingExample() {

Address homeAddress = new Address();

homeAddress.setStreet("100 Any Street");

homeAddress.setCity("Any Town");

homeAddress.setState("NC");

homeAddress.setZipCode("00000");

Address workAddress = new Address();

workAddress.setStreet("123 Main Street");

workAddress.setCity("Any Town");

workAddress.setState("NC");

workAddress.setZipCode("00000");

return Map.of("home", homeAddress,

"work", workAddress);

}

Use an EnhancedDocument without DynamoDB

Although you usually use an instance of an EnhancedDocument to read and write document-type

DynamoDB items, it can also be used independently of DynamoDB.

You can use EnhancedDocuments for their ability to convert between JSON strings or custom objects to

low-level maps of AttributeValues as shown in the following example.

public static void conversionWithoutDynamoDbExample() {

Address address = new Address();

address.setCity("my city");

address.setState("my state");

address.setStreet("my street");

address.setZipCode("00000");

// Build an EnhancedDocument instance for its conversion functionality alone.

EnhancedDocument addressEnhancedDoc = EnhancedDocument.builder()

// Important: You must specify attribute converter providers when you build

an EnhancedDocument instance not used with a DynamoDB table.

.attributeConverterProviders(new CustomAttributeConverterProvider(),

DefaultAttributeConverterProvider.create())

.put("addressDoc", address, Address.class)

.build();

// Convert address to a low-level item representation.

final Map<String, AttributeValue> addressAsAttributeMap =

addressEnhancedDoc.getMapOfUnknownType("addressDoc");

logger.info("addressAsAttributeMap: {}", addressAsAttributeMap.toString());

// Convert address to a JSON string.

String addressAsJsonString = addressEnhancedDoc.getJson("addressDoc");

logger.info("addressAsJsonString: {}", addressAsJsonString);

// Convert addressEnhancedDoc back to an Address instance.

Address addressConverted = addressEnhancedDoc.get("addressDoc", Address.class);

logger.info("addressConverted: {}", addressConverted.toString());

}

/* Console output:

addressAsAttributeMap: {zipCode=AttributeValue(S=00000),

state=AttributeValue(S=my state), street=AttributeValue(S=my street),

city=AttributeValue(S=my city)}

addressAsJsonString: {"zipCode":"00000","state":"my state","street":"my

street","city":"my city"}

addressConverted: Address{street='my street', city='my city', state='my state',

zipCode='00000'}

156

AWS SDK for Java 2.x Developer Guide for version 2.x

Non-blocking asynchronous operations

*/

Note

When you use an enhanced document independent of a DynamoDB table, make sure you

explicitly set attribute converter providers on the builder.

In contrast, the document table schema supplies the converter providers when an enhanced

document is used with a DynamoDB table.

Non-blocking asynchronous operations

If your application requires non-blocking, asynchronous calls to DynamoDB, you can use the

DynamoDbEnhancedAsyncClient. It's similar to the synchronous implementation but with the following

key diﬀerences:

1.

When you build the DynamoDbEnhancedAsyncClient, you must use the asynchronous version of

the standard client, DynamoDbAsyncClient, as shown in the following snippet.

DynamoDbEnhancedAsyncClient enhancedClient =

DynamoDbEnhancedAsyncClient.builder()

.dynamoDbClient(dynamoDbAsyncClient)

.build();

2.

Methods that return a single data object return a CompletableFuture of the result instead of

only the result. Your application can then do other work without having to block on the result. The

following snippet shows the asynchronous getItem() method.

CompletableFuture<Customer> result = customerDynamoDbTable.getItem(customer);

// Perform other work here.

return result.join(); // Now block and wait for the result.

3.

Methods that return paginated lists of results return an SdkPublisher instead of an SdkIterable

that the synchronous DynamoDbEnhanceClient returns for the same methods. Your application can

then subscribe a handler to that publisher to deal with the results asynchronously without having to

block.

PagePublisher<Customer> results = customerDynamoDbTable.query(r ->

r.queryConditional(keyEqualTo(k -> k.partitionValue("Smith"))));

results.subscribe(myCustomerResultsProcessor);

// Perform other work and let the processor handle the results asynchronously.

For a more complete example of working with the SdkPublisher API, see the example (p. 100) in

the section that discusses the asynchronous scan() method of this guide.

Data class annotations

The following table lists the annotations that can be used on data classes and provides links to

information and examples in this guide.

Data class annotations used in this guide

Annotation What it does Where it is shown in this guide

DynamoDbAttribute Deﬁnes or renames a bean

property that is mapped to a

DynamoDB table attribute.

• Initial discussion. (p. 127)

• Get started section—see

Note. (p. 85)

157

AWS SDK for Java 2.x Developer Guide for version 2.x

Annotations

Annotation What it does Where it is shown in this guide

• In MovieActor class In Query

method examples. (p. 103)

DynamoDbBean Marks a data class as mappable

to a table schema.

First use on the Customer

class (p. 82) in the Get started

section. Several usages appear

throughout the guide.

DynamoDbConvertedBy Associates a custom

AttributeConverter with the

annotated attribute.

Initial discussion and

example. (p. 128)

DynamoDbFlatten Flattens all the attributes of

a separate DynamoDB data

class and adds them as top-

level attributes to the record

that is read and written to the

database.

• Initial discussion. (p. 133)

• Implications for other

code. (p. 136)

DynamoDbIgnore Results in the attribute

remaining unmapped.

• Initial discussion. (p. 127)

• Use in the ProductCatalog

class. (p. 91)

DynamoDbIgnoreNulls Prevents saving null attributes

of nested DynamoDb objects.

Discussion and

examples. (p. 145)

DynamoDbImmutable Marks an immutable data class

as mappable to a table schema.

• Introduction to the

annotation. (p. 94)

• Use in the ProductCatalog

class. (p. 91)

• Use with Lombok. (p. 96)

DynamoDbPartitionKey Marks an attribute as the

primary partition key (hash key)

of the DynamoDb table.

• Initial usage on the Customer

class in the Get started

section. (p. 82)

• With Lombok. (p. 96)

DynamoDbPreserveEmptyObject Speciﬁes that if no data is

present for the object mapped

to the annotated attribute, the

object should be initialized with

all null ﬁelds.

Discussion and

examples. (p. 143)

DynamoDbSecondaryPartitionKey Marks an attribute as a partition

key for a global secondary index.

• Use in secondary indices and

example. (p. 118)

• In Query method

examples. (p. 103)

• In Lombok example (p. 96)

• With immutable

classes. (p. 94)

158

AWS SDK for Java 2.x Developer Guide for version 2.x

HTTP/2

Annotation What it does Where it is shown in this guide

DynamoDbSecondarySortKey Marks an attribute as an

optional sort key for a global or

local secondary index.

• Use in secondary indices and

example. (p. 118)

• In Query method

examples. (p. 103)

• In Lombok example. (p. 96)

• With immutable

classes. (p. 94)

DynamoDbSortKey Marks an attribute as the

optional primary sort key (range

key).

• Get started section on

Customer class. (p. 82)

• With immutable

classes. (p. 94)

• In Lombok example. (p. 96)

• In Query method

examples. (p. 103)

DynamoDbUpdateBehavior Speciﬁes the behavior when this

attribute is updated as part of

an 'update' operation such as

UpdateItem.

Introduction and

example. (p. 130)

Working with HTTP/2 in the AWS SDK for Java

HTTP/2 is a major revision of the HTTP protocol. This new version has several enhancements to improve

performance:

• Binary data encoding provides more eﬃcient data transfer.

• Header compression reduces the overhead bytes downloaded by the client, helping get the content to

the client sooner. This is especially useful for mobile clients that are already constrained on bandwidth.

• Bidirectional asynchronous communication (multiplexing) allows multiple requests and response

messages between the client and AWS to be in ﬂight at the same time over a single connection,

instead of over multiple connections, which improves performance.

Developers upgrading to the latest SDKs will automatically use HTTP/2 when it’s supported by the

service they’re working with. New programming interfaces seamlessly take advantage of HTTP/2

features and provide new ways to build applications.

The AWS SDK for Java 2.x features new APIs for event streaming that implement the HTTP/2 protocol.

For examples of how to use these new APIs, see Working with Kinesis (p. 249).

Enable SDK metrics for the AWS SDK for Java

With the AWS SDK for Java 2.x, you can collect metrics about the service clients in your application,

analyze the output in Amazon CloudWatch, and then act on it.

By default, metrics collection is disabled in the SDK. This topic helps you to enable and conﬁgure it.

Prerequisites

Before you can enable and use metrics, you must complete the following steps:

159

AWS SDK for Java 2.x Developer Guide for version 2.x

How to enable metrics collection

• Complete the steps in Setup (p. 11).

•

Conﬁgure your project dependencies (for example, in your pom.xml or build.gradle ﬁle) to use

version 2.14.0 or later of the AWS SDK for Java.

To enabling publishing of metrics to CloudWatch, also include the artifactId cloudwatch-metric-

publisher with the version number 2.14.0 or later in your project’s dependencies.

For example:

<groupId>software.amazon.awssdk</groupId>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>cloudwatch-metric-publisher</artifactId>

</dependency>

</dependencies>

</project>

How to enable metrics collection

You can enable metrics in your application for a service client or on individual requests.

Enable metrics for a speciﬁc request

The following code snippet shows how to enable the CloudWatch metrics publisher for a request to

Amazon DynamoDB. It uses the default metrics publisher conﬁguration.

MetricPublisher metricsPub = CloudWatchMetricPublisher.create();

DynamoDbClient ddb = DynamoDbClient.create();

ddb.listTables(ListTablesRequest.builder()

.overrideConfiguration(c -> c.addMetricPublisher(metricsPub))

.build());

Enable metrics for a speciﬁc service client

The following code snippet shows how to enable a CloudWatch metrics publisher with default settings

for a service client.

MetricPublisher metricsPub = CloudWatchMetricPublisher.create();

DynamoDbClient ddb = DynamoDbClient.builder()

.overrideConfiguration(c -> c.addMetricPublisher(metricsPub))

.build();

The following snippet demonstrates how to use a custom conﬁguration for the metrics publisher for

a speciﬁc service client. The customizations include loading a speciﬁc credentials proﬁle, specifying

160

AWS SDK for Java 2.x Developer Guide for version 2.x

What information is collected?

a diﬀerent region than the service client, and customizing how often the publisher sends metrics to

CloudWatch.

MetricPublisher metricsPub = CloudWatchMetricPublisher.builder()

.cloudWatchClient(CloudWatchAsyncClient.builder()

.region(Region.US_WEST_2)

.credentialsProvider(ProfileCredentialsProvider.create("cloudwatch"))

.build())

.uploadFrequency(Duration.ofMinutes(5))

.build();

DynamoDbClient ddb = DynamoDbClient.builder()

.overrideConfiguration(c -> c.addMetricPublisher(metricsPub))

.build();

What information is collected?

Metrics collection includes the following:

• Number of API requests, including whether they succeed or fail

• Information about the AWS services you call in your API requests, including exceptions returned

• The duration for various operations such as Marshalling, Signing, and HTTP requests

• HTTP client metrics, such as the number of open connections, the number of pending requests, and

the name of the HTTP client used

Note

The metrics available vary by HTTP client.

For a complete list, see Service client metrics (p. 161).

How can I use this information?

You can use the metrics the SDK collects to monitor the service clients in your application. You can look

at overall usage trends, identify anomalies, review service client exceptions returned, or to dig in to

understand a particular issue. Using Amazon CloudWatch, you can also create alarms to notify you as

soon as your application reaches a condition that you deﬁne.

For more information, see Using Amazon CloudWatch Metrics and Using Amazon CloudWatch Alarms in

the Amazon CloudWatch User Guide.

Service client metrics

With the AWS SDK for Java 2.x, you can collect metrics from the service clients in your application and

then publish (output) those metrics to Amazon CloudWatch.

These tables list the metrics that you can collect and any HTTP client usage requirement.

For more information about enabling and conﬁguring metrics for the SDK, see Enabling SDK

metrics (p. 159).

The terms used in the tables mean:

•

Apache: the Apache-based HTTP client (ApacheHttpClient)

•

Netty: the Netty-based HTTP client (NettyNioAsyncHttpClient)

161

AWS SDK for Java 2.x Developer Guide for version 2.x

Service client metrics

•

CRT: the AWS CRT-based HTTP client (AwsCrtAsyncHttpClient)

• Any: the collection of metric data does not depend on the HTTP client; this includes use of the

URLConnection-based HTTP client (UrlConnectionHttpClient)

Metrics collected with each request

Metric name Description Type HTTP client required

ApiCallDuration The total time taken

to ﬁnish a request

(inclusive of all retries)

Duration Any

ApiCallSuccessful True if the API call was

successful; false if not

Boolean Any

CredentialsFetchDuration The time taken to fetch

AWS signing credentials

for the request

Duration Any

MarshallingDuration The time taken to

marshall the request

Duration Any

OperationName The name of the AWS

API the request is made

to

String Any

RetryCount Number of times the

SDK retried the API call

Integer Any

ServiceId Service ID of the AWS

service that the API

request is made against

String Any

TokenFetchDuration The time taken to

fetch token signing

credentials for the

request

Duration Any

Metrics collected for each request attempt

Each API call might require multiple attempts before a response is received. These metrics are collected

for each attempt.

Metric name Description Type HTTP client required

AvailableConcurrency The number of

remaining concurrent

requests that can be

supported by the HTTP

client without needing

to establish another

connection

Integer Apache, Netty, CRT

AwsExtendedRequestId The extended request

ID of the service request

String Any

162

AWS SDK for Java 2.x Developer Guide for version 2.x

Service client metrics

Metric name Description Type HTTP client required

AwsRequestId The request ID of the

service request

String Any

BackoﬀDelayDuration The duration of time

the SDK waited before

this API call attempt

Duration Any

ConcurrencyAcquireDurationThe time taken to

acquire a channel from

the connection pool

Duration Apache, Netty, CRT

HttpClientName The name of the HTTP

being use for the

request

String Apache, Netty, CRT

HttpStatusCode The status code

returned with the HTTP

response

Integer Any

LeasedConcurrency The number of request

currently being

executed by the HTTP

client

Integer Apache, Netty, CRT

LocalStreamWindowSize The local HTTP/2

window size in bytes

for the stream that this

request was executed

on

Integer Netty

MarshallingDuration The time it takes

to marshall an SDK

request to an HTTP

request

Duration Any

MaxConcurrency The max number of

concurrent requests

supported by the HTTP

client

Integer Apache, Netty, CRT

PendingConcurrencyAcquiresThe number of requests

that are blocked,

waiting for another TCP

connection or a new

stream to be available

from the connection

pool

Integer Apache, Netty, CRT

RemoteStreamWindowSizeThe remote HTTP/2

window size in bytes

for the stream that this

request was executed

on

Integer Netty

163

AWS SDK for Java 2.x Developer Guide for version 2.x

Pagination

Metric name Description Type HTTP client required

ServiceCallDuration The time it takes to

connect to the service,

send the request, and

receive the HTTP status

code and header from

the response

Duration Any

SigningDuration The time it takes to sign

the HTTP request

Duration Any

UnmarshallingDuration The time it takes to

unmarshall an HTTP

response to an SDK

response

Duration Any

Retrieving paginated results using the AWS SDK

for Java 2.x

Many AWS operations return paginated results when the response object is too large to return in a single

response. In the AWS SDK for Java 1.0, the response contains a token you use to retrieve the next page

of results. In contrast, the AWS SDK for Java 2.x has autopagination methods that make multiple service

calls to get the next page of results for you automatically. You only have to write code that processes the

results. Autopagination is available for both synchronous and asynchronous clients.

Note

These code snippets assume that you understand the basics of using the SDK (p. 24), and have

conﬁgured your environment with single sign-on access (p. 12).

Synchronous pagination

The following examples demonstrate synchronous pagination methods to list objects in an Amazon S3

bucket.

Iterate over pages

The ﬁrst example demonstrates the use of a listRes paginator object, a ListObjectsV2Iterable instance,

to iterate through all the response pages with the stream method. The code streams over the response

pages, converts the response stream to a stream of S3Object content, and then processes the content of

the Amazon S3 object.

The following imports apply to all examples in this synchronous pagination section.

Imports

import java.io.IOException;

import java.nio.ByteBuffer;

import java.util.Random;

import software.amazon.awssdk.core.waiters.WaiterResponse;

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.s3.S3Client;

import software.amazon.awssdk.services.s3.paginators.ListObjectsV2Iterable;

import software.amazon.awssdk.core.sync.RequestBody;

import software.amazon.awssdk.services.s3.model.S3Exception;

import software.amazon.awssdk.services.s3.model.PutObjectRequest;

164

AWS SDK for Java 2.x Developer Guide for version 2.x

Synchronous pagination

import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;

import software.amazon.awssdk.services.s3.model.ListObjectsV2Response;

import software.amazon.awssdk.services.s3.model.S3Object;

import software.amazon.awssdk.services.s3.model.GetObjectRequest;

import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;

import software.amazon.awssdk.services.s3.model.DeleteBucketRequest;

import software.amazon.awssdk.services.s3.model.CreateMultipartUploadRequest;

import software.amazon.awssdk.services.s3.model.CreateMultipartUploadResponse;

import software.amazon.awssdk.services.s3.model.CompletedMultipartUpload;

import software.amazon.awssdk.services.s3.model.CreateBucketRequest;

import software.amazon.awssdk.services.s3.model.CompletedPart;

import software.amazon.awssdk.services.s3.model.CreateBucketConfiguration;

import software.amazon.awssdk.services.s3.model.UploadPartRequest;

import software.amazon.awssdk.services.s3.model.CompleteMultipartUploadRequest;

import software.amazon.awssdk.services.s3.waiters.S3Waiter;

import software.amazon.awssdk.services.s3.model.HeadBucketRequest;

import software.amazon.awssdk.services.s3.model.HeadBucketResponse;

ListObjectsV2Request listReq = ListObjectsV2Request.builder()

.bucket(bucketName)

.maxKeys(1)

.build();

ListObjectsV2Iterable listRes = s3.listObjectsV2Paginator(listReq);

// Process response pages

listRes.stream()

.flatMap(r -> r.contents().stream())

.forEach(content -> System.out.println(" Key: " + content.key() + " size =

" + content.size()));

See the complete example on GitHub.

Iterate over objects

The following examples show ways to iterate over the objects returned in the response instead of

the pages of the response. The contents method of ListObjectsV2Iterable class returns an

SdkIterable that provides several methods to process the underlying content elements.

Use a stream

The following snippet uses the stream method on the response content to iterate over the paginated

item collection.

// Helper method to work with paginated collection of items directly.

listRes.contents().stream()

.forEach(content -> System.out.println(" Key: " + content.key() + " size =

" + content.size()));

See the complete example on GitHub.

Use a for-each loop

Since SdkIterable extends the Iterable interface, you can process the contents like any Iterable.

The following snippet uses standard for-each loop to iterate through the contents of the response.

for (S3Object content : listRes.contents()) {

System.out.println(" Key: " + content.key() + " size = " + content.size());

}

165

AWS SDK for Java 2.x Developer Guide for version 2.x

Asynchronous pagination

See the complete example on GitHub.

Manual pagination

If your use case requires it, manual pagination is still available. Use the next token in the response object

for the subsequent requests. The following example uses a while loop.

ListObjectsV2Request listObjectsReqManual = ListObjectsV2Request.builder()

.bucket(bucketName)

.maxKeys(1)

.build();

boolean done = false;

while (!done) {

ListObjectsV2Response listObjResponse = s3.listObjectsV2(listObjectsReqManual);

for (S3Object content : listObjResponse.contents()) {

System.out.println(content.key());

}

if (listObjResponse.nextContinuationToken() == null) {

done = true;

}

listObjectsReqManual = listObjectsReqManual.toBuilder()

.continuationToken(listObjResponse.nextContinuationToken())

.build();

}

See the complete example on GitHub.

Asynchronous pagination

The following examples demonstrate asynchronous pagination methods to list DynamoDB tables.

Iterate over pages of table names

The following two examples use an asynchronous DynamoDB client that call the

listTablesPaginator method with a request to get a ListTablesPublisher. ListTablesPublisher

implements two interfaces, which provides many options to process responses. We'll look at methods of

each interface.

Use a Subscriber

The following code example demonstrates how to process paginated results by using the

org.reactivestreams.Publisher interface implemented by ListTablesPublisher. To learn

more about the reactive streams model, see the Reactive Streams GitHub repo.

The following imports apply to all examples in this asynchronous pagination section.

Imports

import io.reactivex.rxjava3.core.Flowable;

import org.reactivestreams.Subscriber;

import org.reactivestreams.Subscription;

import reactor.core.publisher.Flux;

import software.amazon.awssdk.core.async.SdkPublisher;

import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;

import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest;

import software.amazon.awssdk.services.dynamodb.model.ListTablesResponse;

import software.amazon.awssdk.services.dynamodb.paginators.ListTablesPublisher;

166

AWS SDK for Java 2.x Developer Guide for version 2.x

Asynchronous pagination

import java.util.List;

import java.util.concurrent.CompletableFuture;

import java.util.concurrent.ExecutionException;

The following code acquires a ListTablesPublisher instance.

// Creates a default client with credentials and region loaded from the

environment.

final DynamoDbAsyncClient asyncClient = DynamoDbAsyncClient.create();

ListTablesRequest listTablesRequest = ListTablesRequest.builder().limit(3).build();

ListTablesPublisher publisher = asyncClient.listTablesPaginator(listTablesRequest);

The following code uses an anonymous implementation of org.reactivestreams.Subscriber to

process the results for each page.

The onSubscribe method calls the Subscription.request method to initiate requests for data from

the publisher. This method must be called to start getting data from the publisher.

The subscriber's onNext method processes a response page by accessing all the table names and

printing out each one. After the page is processed, another page is requested from the publisher. This

method that is called repeatedly until all pages are retrieved.

The onError method is triggered if an error occurs while retrieving data. Finally, the onComplete

method is called when all pages have been requested.

// A Subscription represents a one-to-one life-cycle of a Subscriber subscribing to

a Publisher.

publisher.subscribe(new Subscriber<ListTablesResponse>() {

// Maintain a reference to the subscription object, which is required to

request data from the publisher.

private Subscription subscription;

@Override

public void onSubscribe(Subscription s) {

subscription = s;

// Request method should be called to demand data. Here we request a single

page.

subscription.request(1);

}

@Override

public void onNext(ListTablesResponse response) {

response.tableNames().forEach(System.out::println);

// After you process the current page, call the request method to signal

that you are ready for next page.

subscription.request(1);

}

@Override

public void onError(Throwable t) {

// Called when an error has occurred while processing the requests.

}

@Override

public void onComplete() {

// This indicates all the results are delivered and there are no more pages

left.

}

});

See the complete example on GitHub.

167

AWS SDK for Java 2.x Developer Guide for version 2.x

Asynchronous pagination

Use a Consumer

The SdkPublisher interface that ListTablesPublisher implements has a subscribe method that

takes a Consumer and returns a CompletableFuture<Void>.

The subscribe method from this interface can be used for simple use cases when an

org.reactivestreams.Subscriber might be too much overhead. As the code below consumes each

page, it calls the tableNames method on each. The tableNames method returns a java.util.List

of DynamoDB table names that are processed with the forEach method.

// Use a Consumer for simple use cases.

CompletableFuture<Void> future = publisher.subscribe(

response -> response.tableNames()

.forEach(System.out::println));

See the complete example on GitHub.

Iterate over table names

The following examples show ways to iterate over the objects returned in the response instead of

the pages of the response. Similar to the synchronous Amazon S3 example previously shown with

its contents method, the DynamoDB asynchronous result class, ListTablesPublisher has the

tableNames convenience method to interact with the underlying item collection. The return type of the

tableNames method is an SdkPublisher that can be used to request items across all pages.

Use a Subscriber

The following code acquires an SdkPublisher of the underlying collection of table names.

// Create a default client with credentials and region loaded from the environment.

final DynamoDbAsyncClient asyncClient = DynamoDbAsyncClient.create();

ListTablesRequest listTablesRequest = ListTablesRequest.builder().limit(3).build();

ListTablesPublisher listTablesPublisher =

asyncClient.listTablesPaginator(listTablesRequest);

SdkPublisher<String> publisher = listTablesPublisher.tableNames();

The following code uses an anonymous implementation of org.reactivestreams.Subscriber to

process the results for each page.

The subscriber's onNext method processes an individual element of the collection. In this case, it's a

table name. After the table name is processed, another table name is requested from the publisher. This

method that is called repeatedly until all table names are retrieved.

// Use a Subscriber.

publisher.subscribe(new Subscriber<String>() {

private Subscription subscription;

@Override

public void onSubscribe(Subscription s) {

subscription = s;

subscription.request(1);

}

@Override

public void onNext(String tableName) {

System.out.println(tableName);

subscription.request(1);

}

168

AWS SDK for Java 2.x Developer Guide for version 2.x

AWS CRT-based S3 client

@Override

public void onError(Throwable t) {

}

@Override

public void onComplete() {

}

});

See the complete example on GitHub.

Use a Consumer

The following example uses the subscribe method of SdkPublisher that takes a Consumer to

process each item.

// Use a Consumer.

CompletableFuture<Void> future = publisher.subscribe(System.out::println);

future.get();

See the complete example on GitHub.

Use third-party library

You can use other third party libraries instead of implementing a custom subscriber. This example

demonstrates the use of RxJava, but any library that implements the reactive stream interfaces can be

used. See the RxJava wiki page on GitHub for more information on that library.

To use the library, add it as a dependency. If using Maven, the example shows the POM snippet to use.

POM Entry

<groupId>io.reactivex.rxjava3</groupId>

<artifactId>rxjava</artifactId>

</dependency>

Code

DynamoDbAsyncClient asyncClient = DynamoDbAsyncClient.create();

ListTablesPublisher publisher =

asyncClient.listTablesPaginator(ListTablesRequest.builder()

.build());

// The Flowable class has many helper methods that work with

// an implementation of an org.reactivestreams.Publisher.

List<String> tables = Flowable.fromPublisher(publisher)

.flatMapIterable(ListTablesResponse::tableNames)

.toList()

.blockingGet();

System.out.println(tables);

AWS CRT-based S3 client

The AWS CRT-based S3 client—built on top of the AWS Common Runtime (CRT)—is an alternative S3

asynchronous client. It transfers objects to and from Amazon Simple Storage Service (Amazon S3) with

169

AWS SDK for Java 2.x Developer Guide for version 2.x

Add dependencies

enhanced performance and reliability by automatically using Amazon S3's multipart upload API and

byte-range fetches.

The AWS CRT-based S3 client improves transfer reliability in case there is a network failure. Reliability

is improved by retrying individual failed parts of a ﬁle transfer without restarting the transfer from the

beginning.

In addition, the AWS CRT-based S3 client oﬀers enhanced connection pooling and Domain Name System

(DNS) load balancing, which also improves throughput.

You can use the AWS CRT-based S3 client in place of the SDK's standard S3 asynchronous client and take

advantage of its improved throughput right away.

AWS CRT-based components in the SDK

The AWS CRT-based S3 client, described in this topic, and the AWS CRT-based HTTP client are diﬀerent

components in the SDK.

The AWS CRT-based S3 client is an implementation of the S3AsyncClient interface and is used for

working with the Amazon S3 service. It is an alternative to the Java-based implementation of the

S3AsyncClient interface and oﬀers several beneﬁts.

The AWS CRT-based HTTP client (p. 60) is an implementation of the SdkAsyncHttpClient interface

and is used for general HTTP communication. It is an alternative to the Netty implementation of the

SdkAsyncHttpClient interface and oﬀers several advantages.

Although both components use libraries from the AWS Common Runtime, the AWS CRT-based S3 client

uses the aws-c-s3 library and supports the S3 multipart upload API features. Since the AWS CRT-based

HTTP client is meant for general purpose use, it does not support the S3 multipart upload API features.

Add dependencies to use the AWS CRT-based S3

client

To use the AWS CRT-based S3 client, add the following two dependencies to your Maven project ﬁle. The

example shows the minimum versions to use. Search the Maven central repository for the most recent

versions of the s3 and aws-crt artifacts.

<groupId>software.amazon.awssdk</groupId>

</dependency>

<groupId>software.amazon.awssdk.crt</groupId>

</dependency>

Create an instance of the AWS CRT-based S3 client

Create an instance of the AWS CRT-based S3 client with default settings as shown in the following code

snippet.

S3AsyncClient s3AsyncClient = S3AsyncClient.crtCreate();

170

AWS SDK for Java 2.x Developer Guide for version 2.x

Use the AWS CRT-based S3 client

To conﬁgure the client, use the AWS CRT client builder. You can switch from the standard S3

asynchronous client to AWS CRT-based client by changing the builder method.

import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.s3.S3AsyncClient;

S3AsyncClient s3AsyncClient =

S3AsyncClient.crtBuilder()

.credentialsProvider(DefaultCredentialsProvider.create())

.region(Region.US_WEST_2)

.targetThroughputInGbps(20.0)

.minimumPartSizeInBytes(8 * 1025 * 1024L)

.build();

Note

Some of the settings in the standard builder might not be currently supported in the AWS CRT

client builder. Get the standard builder by calling S3AsyncClient#builder().

Use the AWS CRT-based S3 client

Use the AWS CRT-based S3 client to call Amazon S3 API operations. The following example

demonstrates the PutObject and GetObject operations available through the AWS SDK for Java.

import software.amazon.awssdk.core.async.AsyncRequestBody;

import software.amazon.awssdk.core.async.AsyncResponseTransformer;

import software.amazon.awssdk.services.s3.S3AsyncClient;

import software.amazon.awssdk.services.s3.model.GetObjectResponse;

import software.amazon.awssdk.services.s3.model.PutObjectResponse;

S3AsyncClient s3Client = S3AsyncClient.crtCreate();

// Upload a local file to Amazon S3.

PutObjectResponse putObjectResponse =

s3Client.putObject(req -> req.bucket(<BUCKET_NAME>)

.key(<KEY_NAME>),

AsyncRequestBody.fromFile(Paths.get(<FILE_NAME>)))

.join();

// Download an object from Amazon S3 to a local file.

GetObjectResponse getObjectResponse =

s3Client.getObject(req -> req.bucket(<BUCKET_NAME>)

.key(<KEY_NAME>),

AsyncResponseTransformer.toFile(Paths.get(<FILE_NAME>)))

.join();

Amazon S3 Transfer Manager

The Amazon S3 Transfer Manager is an open source, high level ﬁle transfer utility for the AWS SDK for

Java 2.x. Use it to transfer ﬁles and directories to and from Amazon Simple Storage Service (Amazon S3).

When built on top of the the section called “AWS CRT-based S3 client” (p. 169), the S3 Transfer

Manager can take advantage of performance improvements such as multipart upload API and byte-

range fetches.

171

AWS SDK for Java 2.x Developer Guide for version 2.x

Get started

With the S3 Transfer Manager, you can also monitor a transfer's progress in real time and pause the

transfer for later execution.

Get started

Add dependencies to your build ﬁle

To use the S3 Transfer Manager with enhanced performance based on the AWS CRT-based S3 client,

conﬁgure your build ﬁle with the following dependencies.

•

Use version 2.19.1 or higher of the SDK for Java 2.x.

•

Add the s3-transfer-manager artifact as a dependency.

•

Add the aws-crt artifact as a dependency at version 0.20.3 or higher.

The following code example shows how to conﬁgure your project dependencies for Maven.

<aws.sdk.version>2.19.1</aws.sdk.version>

</properties>

<groupId>software.amazon.awssdk</groupId>

<version>${aws.sdk.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<groupId>software.amazon.awssdk</groupId>

<artifactId>s3-transfer-manager</artifactId>

</dependency>

<groupId>software.amazon.awssdk.crt</groupId>

</dependency>

</dependencies>

</project>

Search the Maven central repository for the most recent versions of the s3-transfer-manager and aws-crt

artifacts.

Create an instance of the S3 Transfer Manager

The following snippet shows how to create a S3TransferManager instance with default settings.

S3TransferManager transferManager = S3TransferManager.create();

The following example shows how to conﬁgure a S3 Transfer Manager with custom settings. In this

example, a AWS CRT-based S3AsyncClient (p. 169) instance is used as the underlying client for the S3

Transfer Manager.

172

AWS SDK for Java 2.x Developer Guide for version 2.x

Upload a ﬁle

S3AsyncClient s3AsyncClient =

S3AsyncClient.crtBuilder()

.credentialsProvider(DefaultCredentialsProvider.create())

.region(Region.US_EAST_1)

.targetThroughputInGbps(20.0)

.minimumPartSizeInBytes(8 * MB)

.build();

S3TransferManager transferManager =

S3TransferManager.builder()

.s3Client(s3AsyncClient)

.build();

Note

If the aws-crt dependency is not included in the build ﬁle, the S3 Transfer Manager is built on

top of the standard S3 asynchronous client used in the SDK for Java 2.x.

Upload a ﬁle to an S3 bucket

To upload a ﬁle to Amazon S3 using the S3 Transfer Manager, pass an UploadFileRequest object to

the S3TransferManager's uploadFile method.

The FileUpload object returned from the uploadFile method represents the upload process. After the

request ﬁnishes, the CompletedFileUpload object contains information about the upload.

The following example shows a ﬁle upload example along with the optional use of a

LoggingTransferListener, which logs the progress of the upload.

Imports

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import software.amazon.awssdk.transfer.s3.S3TransferManager;

import software.amazon.awssdk.transfer.s3.model.CompletedFileUpload;

import software.amazon.awssdk.transfer.s3.model.FileUpload;

import software.amazon.awssdk.transfer.s3.model.UploadFileRequest;

import software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener;

import java.net.URL;

import java.nio.file.Paths;

import java.util.UUID;

Code

public String uploadFile(S3TransferManager transferManager, String bucketName,

String key, String filePath) {

UploadFileRequest uploadFileRequest =

UploadFileRequest.builder()

.putObjectRequest(b -> b.bucket(bucketName).key(key))

.addTransferListener(LoggingTransferListener.create())

.source(Paths.get(filePath))

.build();

FileUpload fileUpload = transferManager.uploadFile(uploadFileRequest);

CompletedFileUpload uploadResult = fileUpload.completionFuture().join();

return uploadResult.response().eTag();

}

173

AWS SDK for Java 2.x Developer Guide for version 2.x

Download a ﬁle

Download a ﬁle from an S3 bucket

To download an object from an S3 bucket using the S3 Transfer Manager, build a DownloadFileRequest

object and pass it to the downloadFile method.

The FileDownload object returned by the S3TransferManager's downloadFile method represents

the ﬁle transfer. After the download completes, the CompletedFileDownload contains access to

information about the download.

The following example also shows a download example plus the optional use of a

LoggingTransferListener, which logs the progress of the download.

Imports

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import software.amazon.awssdk.core.sync.RequestBody;

import software.amazon.awssdk.transfer.s3.S3TransferManager;

import software.amazon.awssdk.transfer.s3.model.CompletedFileDownload;

import software.amazon.awssdk.transfer.s3.model.DownloadFileRequest;

import software.amazon.awssdk.transfer.s3.model.FileDownload;

import software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener;

import java.io.IOException;

import java.net.URL;

import java.nio.file.Files;

import java.nio.file.Paths;

import java.util.UUID;

Code

public Long downloadFile(S3TransferManager transferManager, String bucketName,

String key, String downloadedFileWithPath) {

DownloadFileRequest downloadFileRequest =

DownloadFileRequest.builder()

.getObjectRequest(b -> b.bucket(bucketName).key(key))

.addTransferListener(LoggingTransferListener.create())

.destination(Paths.get(downloadedFileWithPath))

.build();

FileDownload downloadFile = transferManager.downloadFile(downloadFileRequest);

CompletedFileDownload downloadResult = downloadFile.completionFuture().join();

logger.info("Content length [{}]", downloadResult.response().contentLength());

return downloadResult.response().contentLength();

}

Copy an Amazon S3 object to another bucket

To begin the copy of an object from an S3 bucket to another bucket, create a basic CopyObjectRequest

instance.

Next, wrap the basic CopyObjectRequest in a CopyRequest that can be used by the S3 Transfer

Manager.

The Copy object returned by the S3TransferManager's copy method represents the copy process.

After the copy process completes, the CompletedCopy object contains details about the response.

174

AWS SDK for Java 2.x Developer Guide for version 2.x

Upload a directory

Imports

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import software.amazon.awssdk.core.sync.RequestBody;

import software.amazon.awssdk.services.s3.model.CopyObjectRequest;

import software.amazon.awssdk.transfer.s3.S3TransferManager;

import software.amazon.awssdk.transfer.s3.model.CompletedCopy;

import software.amazon.awssdk.transfer.s3.model.Copy;

import software.amazon.awssdk.transfer.s3.model.CopyRequest;

import java.util.UUID;

Code

public String copyObject(S3TransferManager transferManager, String bucketName,

String key, String destinationBucket, String destinationKey){

CopyObjectRequest copyObjectRequest = CopyObjectRequest.builder()

.sourceBucket(bucketName)

.sourceKey(key)

.destinationBucket(destinationBucket)

.destinationKey(destinationKey)

.build();

CopyRequest copyRequest = CopyRequest.builder()

.copyObjectRequest(copyObjectRequest)

.build();

Copy copy = transferManager.copy(copyRequest);

CompletedCopy completedCopy = copy.completionFuture().join();

return completedCopy.response().copyObjectResult().eTag();

}

Note

Cross-Region copies are not currently supported.

Upload a local directory to an S3 bucket

To upload a local directory to an S3 bucket, start by calling the uploadDirectory method of the

S3TransferManager instance, passing in an UploadDirectoryRequest.

The DirectoryUpload object represents the upload process, which generates a

CompletedDirectoryUpload when the request completes. The CompleteDirectoryUpload object

contains information about the results of the transfer, including which ﬁles failed to transfer.

Imports

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import software.amazon.awssdk.services.s3.model.ObjectIdentifier;

import software.amazon.awssdk.transfer.s3.S3TransferManager;

import software.amazon.awssdk.transfer.s3.model.CompletedDirectoryUpload;

import software.amazon.awssdk.transfer.s3.model.DirectoryUpload;

import software.amazon.awssdk.transfer.s3.model.UploadDirectoryRequest;

import java.net.URL;

import java.nio.file.Paths;

import java.util.UUID;

175

AWS SDK for Java 2.x Developer Guide for version 2.x

Download to a directory

Code

public Integer uploadDirectory(S3TransferManager transferManager,

String sourceDirectory, String bucketName){

DirectoryUpload directoryUpload =

transferManager.uploadDirectory(UploadDirectoryRequest.builder()

.source(Paths.get(sourceDirectory))

.bucket(bucketName)

.build());

CompletedDirectoryUpload completedDirectoryUpload =

directoryUpload.completionFuture().join();

completedDirectoryUpload.failedTransfers().forEach(fail ->

logger.warn("Object [{}] failed to transfer", fail.toString()));

return completedDirectoryUpload.failedTransfers().size();

}

Download S3 bucket objects to a local directory

To download the objects in an S3 bucket to a local directory, begin by calling the downloadDirectory

method of the Transfer Manager, passing in a DownloadDirectoryRequest.

The DirectoryDownload object represents the download process, which generates a

CompletedDirectoryDownload when the request completes. The CompleteDirectoryDownload object

contains information about the results of the transfer, including which ﬁles failed to transfer.

Imports

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import software.amazon.awssdk.core.sync.RequestBody;

import software.amazon.awssdk.services.s3.model.ObjectIdentifier;

import software.amazon.awssdk.transfer.s3.S3TransferManager;

import software.amazon.awssdk.transfer.s3.model.CompletedDirectoryDownload;

import software.amazon.awssdk.transfer.s3.model.DirectoryDownload;

import software.amazon.awssdk.transfer.s3.model.DownloadDirectoryRequest;

import java.io.IOException;

import java.nio.file.Files;

import java.nio.file.Paths;

import java.util.HashSet;

import java.util.Set;

import java.util.UUID;

import java.util.stream.Collectors;

Code

public Integer downloadObjectsToDirectory(S3TransferManager transferManager,

String destinationPath, String bucketName) {

DirectoryDownload directoryDownload =

transferManager.downloadDirectory(DownloadDirectoryRequest.builder()

.destination(Paths.get(destinationPath))

.bucket(bucketName)

.build());

CompletedDirectoryDownload completedDirectoryDownload =

directoryDownload.completionFuture().join();

completedDirectoryDownload.failedTransfers().forEach(fail ->

logger.warn("Object [{}] failed to transfer", fail.toString()));

return completedDirectoryDownload.failedTransfers().size();

176

AWS SDK for Java 2.x Developer Guide for version 2.x

Waiters

}

Use waiters in the AWS SDK for Java 2.x

The waiters utility of the AWS SDK for Java 2.x enables you to validate that AWS resources are in a

speciﬁed state before performing operations on those resources.

A waiter is an abstraction used to poll AWS resources, such as DynamoDB tables or Amazon S3 buckets,

until a desired state is reached (or until a determination is made that the resource won’t ever reach

the desired state). Instead of writing logic to continuously poll your AWS resources, which can be

cumbersome and error-prone, you can use waiters to poll a resource and have your code continue to run

after the resource is ready.

Prerequisites

Before you can use waiters in a project with the AWS SDK for Java, you must complete the steps in

Setting up the AWS SDK for Java 2.x (p. 11).

You must also conﬁgure your project dependencies (for example, in your pom.xml or build.gradle

ﬁle) to use version 2.15.0 or later of the AWS SDK for Java.

For example:

<groupId>software.amazon.awssdk</groupId>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

</project>

Using waiters

To instantiate a waiters object, ﬁrst create a service client. Set the service client’s waiter() method as

the value of the waiter object. Once the waiter instance exists, set its response options to execute the

appropriate code.

Synchronous programming

The following code snippet shows how to wait for a DynamoDB table to exist and be in an ACTIVE state.

DynamoDbClient dynamo = DynamoDbClient.create();

DynamoDbWaiter waiter = dynamo.waiter();

WaiterResponse<DescribeTableResponse> waiterResponse =

waiter.waitUntilTableExists(r -> r.tableName("myTable"));

// print out the matched response with a tableStatus of ACTIVE

waiterResponse.matched().response().ifPresent(System.out::println);

177

AWS SDK for Java 2.x Developer Guide for version 2.x

Conﬁgure waiters

Asynchronous programming

The following code snippet shows how to wait for a DynamoDB table to no longer exist.

DynamoDbAsyncClient asyncDynamo = DynamoDbAsyncClient.create();

DynamoDbAsyncWaiter asyncWaiter = asyncDynamo.waiter();

CompletableFuture<WaiterResponse<DescribeTableResponse>> waiterResponse =

asyncWaiter.waitUntilTableNotExists(r -> r.tableName("myTable"));

waiterResponse.whenComplete((r, t) -> {

if (t == null) {

// print out the matched ResourceNotFoundException

r.matched().exception().ifPresent(System.out::println);

}

}).join();

Conﬁgure waiters

You can customize the conﬁguration for a waiter by using the overrideConfiguration() on its

builder. For some operations, you can apply a custom conﬁguration when you make the request.

Conﬁgure a waiter

The following code snippet shows how to override the conﬁguration on a waiter.

// sync

DynamoDbWaiter waiter =

DynamoDbWaiter.builder()

.overrideConfiguration(b -> b.maxAttempts(10))

.client(dynamoDbClient)

.build();

// async

DynamoDbAsyncWaiter asyncWaiter =

DynamoDbAsyncWaiter.builder()

.client(dynamoDbAsyncClient)

.overrideConfiguration(o -> o.backoffStrategy(

FixedDelayBackoffStrategy.create(Duration.ofSeconds(2))))

.scheduledExecutorService(Executors.newScheduledThreadPool(3))

.build();

Override conﬁguration for a speciﬁc request

The following code snippet shows how to override the conﬁguration for a waiter on a per-request basis.

Note that only some operations have customizable conﬁgurations.

waiter.waitUntilTableNotExists(b -> b.tableName("myTable"),

o -> o.maxAttempts(10));

asyncWaiter.waitUntilTableExists(b -> b.tableName("myTable"),

o -> o.waitTimeout(Duration.ofMinutes(1)));

Code examples

For a complete example using waiters with DynamoDB, see CreateTable.java in the AWS Code Examples

Repository.

178

AWS SDK for Java 2.x Developer Guide for version 2.x

IAM Policy Builder API

For a complete example using waiters with Amazon S3, see S3BucketOps.java in the AWS Code Examples

Repository.

IAM Policy Builder API

The IAM Policy Builder API is a library that you can use to build IAM policies in Java and upload them to

AWS Identity and Access Management (IAM).

Instead of building an IAM policy by manually assembling a JSON string or by reading a ﬁle, the API

provides a client-side, object-oriented approach to generate the JSON string. When you read an existing

IAM policy in JSON format, the API converts it to an IamPolicy instance for handling.

The IAM Policy Builder API became available with version 2.20.105 of the SDK, so use that version or a

later one in your Maven build ﬁle. The latest version number of the SDK is listed on Maven central.

The following snippet shows an example dependency block for a Maven pom.xml ﬁle. This allows you to

use the IAM Policy Builder API in your project.

<groupId>software.amazon.awssdk</groupId>

<artifactId>iam-policy-builder</artifactId>

</dependency>

Create an IamPolicy

This section shows several examples of how to build policies by using the IAM Policy Builder API.

In each of the following examples, start with the IamPolicy.Builder and add one or more statements

by using the addStatement method. Following this pattern, the IamStatement.Builder has methods to

add the eﬀect, actions, resources, and conditions to the statement.

Example: Create a time-based policy

The following example creates an identity-based policy that permits the Amazon DynamoDB GetItem

action between two points in time.

public String timeBasedPolicyExample() {

IamPolicy policy = IamPolicy.builder()

.addStatement(b -> b

.effect(IamEffect.ALLOW)

.addAction("dynamodb:GetItem")

.addResource(IamResource.ALL)

.addCondition(b1 -> b1

.operator(IamConditionOperator.DATE_GREATER_THAN)

.key("aws:CurrentTime")

.value("2020-04-01T00:00:00Z"))

.addCondition(b1 -> b1

.operator(IamConditionOperator.DATE_LESS_THAN)

.key("aws:CurrentTime")

.value("2020-06-30T23:59:59Z")))

.build();

// Use an IamPolicyWriter to write out the JSON string to a more readable format.

return policy.toJson(IamPolicyWriter.builder()

.prettyPrint(true)

179

AWS SDK for Java 2.x Developer Guide for version 2.x

Create an IamPolicy

.build());

}

JSON output

The last statement in the previous example returns the following JSON string.

Read more about this example in the AWS Identity and Access Management User Guide.

{

"Version" : "2012-10-17",

"Statement" : {

"Effect" : "Allow",

"Action" : "dynamodb:GetItem",

"Resource" : "*",

"Condition" : {

"DateGreaterThan" : {

"aws:CurrentTime" : "2020-04-01T00:00:00Z"

},

"DateLessThan" : {

"aws:CurrentTime" : "2020-06-30T23:59:59Z"

}

Example: Specify multiple conditions

The following example shows how you can create an identity-based policy that allows access to speciﬁc

DynamoDB attributes. The policy contains two conditions.

public String multipleConditionsExample() {

IamPolicy policy = IamPolicy.builder()

.addStatement(b -> b

.effect(IamEffect.ALLOW)

.addAction("dynamodb:GetItem")

.addAction("dynamodb:BatchGetItem")

.addAction("dynamodb:Query")

.addAction("dynamodb:PutItem")

.addAction("dynamodb:UpdateItem")

.addAction("dynamodb:DeleteItem")

.addAction("dynamodb:BatchWriteItem")

.addResource("arn:aws:dynamodb:*:*:table/table-name")

.addConditions(IamConditionOperator.STRING_EQUALS.addPrefix("ForAllValues:"),

"dynamodb:Attributes",

List.of("column-name1", "column-name2", "column-name3"))

.addCondition(b1 ->

b1.operator(IamConditionOperator.STRING_EQUALS.addSuffix("IfExists"))

.key("dynamodb:Select")

.value("SPECIFIC_ATTRIBUTES")))

.build();

return policy.toJson(IamPolicyWriter.builder()

.prettyPrint(true).build());

}

JSON output

The last statement in the previous example returns the following JSON string.

Read more about this example in the AWS Identity and Access Management User Guide.

180

AWS SDK for Java 2.x Developer Guide for version 2.x

Create an IamPolicy

{

"Version" : "2012-10-17",

"Statement" : {

"Effect" : "Allow",

"Action" : [ "dynamodb:GetItem", "dynamodb:BatchGetItem", "dynamodb:Query",

"dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem",

"dynamodb:BatchWriteItem" ],

"Resource" : "arn:aws:dynamodb:*:*:table/table-name",

"Condition" : {

"ForAllValues:StringEquals" : {

"dynamodb:Attributes" : [ "column-name1", "column-name2", "column-name3" ]

},

"StringEqualsIfExists" : {

"dynamodb:Select" : "SPECIFIC_ATTRIBUTES"

}

Example: Specify principals

The following example shows how to create a resource-based policy that denies access to a bucket for all

principals except for those speciﬁed in the condition.

public String specifyPrincipalsExample() {

IamPolicy policy = IamPolicy.builder()

.addStatement(b -> b

.effect(IamEffect.DENY)

.addAction("s3:*")

.addPrincipal(IamPrincipal.ALL)

.addResource("arn:aws:s3:::BUCKETNAME/*")

.addResource("arn:aws:s3:::BUCKETNAME")

.addCondition(b1 -> b1

.operator(IamConditionOperator.ARN_NOT_EQUALS)

.key("aws:PrincipalArn")

.value("arn:aws:iam::444455556666:user/user-name")))

.build();

return policy.toJson(IamPolicyWriter.builder()

.prettyPrint(true).build());

}

JSON output

The last statement in the previous example returns the following JSON string.

Read more about this example in the AWS Identity and Access Management User Guide.

{

"Version" : "2012-10-17",

"Statement" : {

"Effect" : "Deny",

"Principal" : "*",

"Action" : "s3:*",

"Resource" : [ "arn:aws:s3:::BUCKETNAME/*", "arn:aws:s3:::BUCKETNAME" ],

"Condition" : {

"ArnNotEquals" : {

"aws:PrincipalArn" : "arn:aws:iam::444455556666:user/user-name"

}

181

AWS SDK for Java 2.x Developer Guide for version 2.x

Use an IamPolicy with IAM

Example: Allow cross-account access

The following example shows how to allow another AWS account to upload objects to your bucket while

retaining full owner control of the uploaded objects.

public String allowCrossAccountAccessExample() {

IamPolicy policy = IamPolicy.builder()

.addStatement(b -> b

.effect(IamEffect.ALLOW)

.addPrincipal(IamPrincipalType.AWS, "111122223333")

.addAction("s3:PutObject")

.addResource("arn:aws:s3:::DOC-EXAMPLE-BUCKET/*")

.addCondition(b1 -> b1

.operator(IamConditionOperator.STRING_EQUALS)

.key("s3:x-amz-acl")

.value("bucket-owner-full-control")))

.build();

return policy.toJson(IamPolicyWriter.builder()

.prettyPrint(true).build());

}

JSON output

The last statement in the previous example returns the following JSON string.

Read more about this example in the Amazon Simple Storage Service User Guide.

{

"Version" : "2012-10-17",

"Statement" : {

"Effect" : "Allow",

"Principal" : {

"AWS" : "111122223333"

},

"Action" : "s3:PutObject",

"Resource" : "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*",

"Condition" : {

"StringEquals" : {

"s3:x-amz-acl" : "bucket-owner-full-control"

}

Use an IamPolicy with IAM

After you have created a IamPolicy instance, you use an IamClient to work with the IAM service.

The following example builds a policy that allows an IAM identity to write items to a DynamoDB table

in the account that is speciﬁed with the accountID parameter. The policy is then uploaded to IAM as a

JSON string.

public String createAndUploadPolicyExample(IamClient iam, String accountID, String

policyName) {

// Build the policy.

IamPolicy policy =

IamPolicy.builder() // 'version' defaults to "2012-10-17".

.addStatement(IamStatement.builder()

.effect(IamEffect.ALLOW)

.addAction("dynamodb:PutItem")

182

AWS SDK for Java 2.x Developer Guide for version 2.x

Use an IamPolicy with IAM

.addResource("arn:aws:dynamodb:us-east-1:" + accountID +

":table/exampleTableName")

.build())

.build();

// Upload the policy.

iam.createPolicy(r -> r.policyName(policyName).policyDocument(policy.toJson()));

return policy.toJson(IamPolicyWriter.builder().prettyPrint(true).build());

}

The next example builds on the previous example. The code downloads the policy and uses it as the basis

for a new policy by copying and altering the statement. The new policy is then uploaded.

public String createNewBasedOnExistingPolicyExample(IamClient iam, String accountID,

String policyName, String newPolicyName) {

String policyArn = "arn:aws:iam::" + accountID + ":policy/" + policyName;

GetPolicyResponse getPolicyResponse = iam.getPolicy(r -> r.policyArn(policyArn));

String policyVersion = getPolicyResponse.policy().defaultVersionId();

GetPolicyVersionResponse getPolicyVersionResponse =

iam.getPolicyVersion(r -> r.policyArn(policyArn).versionId(policyVersion));

// Create an IamPolicy instance from the JSON string returned from IAM.

String decodedPolicy =

URLDecoder.decode(getPolicyVersionResponse.policyVersion().document(),

StandardCharsets.UTF_8);

IamPolicy policy = IamPolicy.fromJson(decodedPolicy);

/*

All IamPolicy components are immutable, so use the copy method that creates a

new instance that

can be altered in the same method call.

Add the ability to get an item from DynamoDB as an additional action.

*/

IamStatement newStatement = policy.statements().get(0).copy(s ->

s.addAction("dynamodb:GetItem"));

// Create a new statement that replaces the original statement.

IamPolicy newPolicy = policy.copy(p -> p.statements(Arrays.asList(newStatement)));

// Upload the new policy. IAM now has both policies.

iam.createPolicy(r -> r.policyName(newPolicyName)

.policyDocument(newPolicy.toJson()));

return newPolicy.toJson(IamPolicyWriter.builder().prettyPrint(true).build());

}

IamClient

The previous examples use an IamClient argument that is created as shown in the following snippet.

IamClient iam = IamClient.builder().region(Region.AWS_GLOBAL).build();

Policies in JSON

The examples return the following JSON strings.

First example

{

"Version" : "2012-10-17",

183

AWS SDK for Java 2.x Developer Guide for version 2.x

Use an IamPolicy with IAM

"Statement" : {

"Effect" : "Allow",

"Action" : "dynamodb:PutItem",

"Resource" : "arn:aws:dynamodb:us-east-1:111122223333:table/exampleTableName"

}

Second example

{

"Version" : "2012-10-17",

"Statement" : {

"Effect" : "Allow",

"Action" : [ "dynamodb:PutItem", "dynamodb:GetItem" ],

"Resource" : "arn:aws:dynamodb:us-east-1:111122223333:table/exampleTableName"

}

184

AWS SDK for Java 2.x Developer Guide for version 2.x

CloudWatch

Work with AWS services using the

AWS SDK for Java 2.x

This section provides short tutorials and guidance for how to work with AWS services.

Topics

• Work with CloudWatch (p. 185)

• Work with Amazon Cognito (p. 195)

• AWS database services and AWS SDK for Java 2.x (p. 200)

• Work with DynamoDB (p. 201)

• Work with Amazon EC2 (p. 213)

• Work with IAM (p. 232)

• Work with Kinesis (p. 249)

• Invoke, list, and delete AWS Lambda functions (p. 256)

• Work with Amazon Pinpoint (p. 258)

• Work with Amazon S3 (p. 265)

• Work with Amazon Simple Notiﬁcation Service (p. 282)

• Work with Amazon Simple Queue Service (p. 286)

• Work with Amazon Transcribe (p. 291)

Work with CloudWatch

This section provides examples of programming CloudWatch by using the AWS SDK for Java 2.x.

Amazon CloudWatch monitors your Amazon Web Services (AWS) resources and the applications you run

on AWS in real time. You can use CloudWatch to collect and track metrics, which are variables you can

measure for your resources and applications. CloudWatch alarms send notiﬁcations or automatically

make changes to the resources you are monitoring based on rules that you deﬁne.

For more information about CloudWatch, see the Amazon CloudWatch User Guide.

The following examples include only the code needed to demonstrate each technique. The complete

example code is available on GitHub. From there, you can download a single source ﬁle or clone the

repository locally to get all the examples to build and run.

Topics

• Get metrics from CloudWatch (p. 186)

• Publish custom metric data to CloudWatch (p. 187)

• Work with CloudWatch alarms (p. 188)

• Use alarm actions in CloudWatch (p. 191)

• Send events to CloudWatch (p. 192)

185

AWS SDK for Java 2.x Developer Guide for version 2.x

Get metrics from CloudWatch

Listing metrics

To list CloudWatch metrics, create a ListMetricsRequest and call the CloudWatchClient’s listMetrics

method. You can use the ListMetricsRequest to ﬁlter the returned metrics by namespace, metric

name, or dimensions.

Note

A list of metrics and dimensions that are posted by AWS services can be found within the

Amazon CloudWatch Metrics and Dimensions Reference in the Amazon CloudWatch User Guide.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cloudwatch.CloudWatchClient;

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import software.amazon.awssdk.services.cloudwatch.model.ListMetricsRequest;

import software.amazon.awssdk.services.cloudwatch.model.ListMetricsResponse;

import software.amazon.awssdk.services.cloudwatch.model.Metric;

Code

public static void listMets( CloudWatchClient cw, String namespace) {

boolean done = false;

String nextToken = null;

try {

while(!done) {

ListMetricsResponse response;

if (nextToken == null) {

ListMetricsRequest request = ListMetricsRequest.builder()

.namespace(namespace)

.build();

response = cw.listMetrics(request);

} else {

ListMetricsRequest request = ListMetricsRequest.builder()

.namespace(namespace)

.nextToken(nextToken)

.build();

response = cw.listMetrics(request);

}

for (Metric metric : response.metrics()) {

System.out.printf(

"Retrieved metric %s", metric.metricName());

System.out.println();

}

if(response.nextToken() == null) {

done = true;

} else {

nextToken = response.nextToken();

}

186

AWS SDK for Java 2.x Developer Guide for version 2.x

Publish custom metric data to CloudWatch

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

The metrics are returned in a ListMetricsResponse by calling its getMetrics method.

The results may be paged. To retrieve the next batch of results, call nextToken on the response object

and use the token value to build a new request object. Then call the listMetrics method again with

the new request.

See the complete example on GitHub.

More information

• ListMetrics in the Amazon CloudWatch API Reference

Publish custom metric data to CloudWatch

A number of AWS services publish their own metrics in namespaces beginning with " AWS " You can also

publish custom metric data using your own namespace (as long as it doesn’t begin with " AWS ").

Publish custom metric data

To publish your own metric data, call the CloudWatchClient’s putMetricData method with a

PutMetricDataRequest. The PutMetricDataRequest must include the custom namespace to use for

the data, and information about the data point itself in a MetricDatum object.

Note

You cannot specify a namespace that begins with " AWS ". Namespaces that begin with " AWS "

are reserved for use by Amazon Web Services products.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cloudwatch.CloudWatchClient;

import software.amazon.awssdk.services.cloudwatch.model.Dimension;

import software.amazon.awssdk.services.cloudwatch.model.MetricDatum;

import software.amazon.awssdk.services.cloudwatch.model.StandardUnit;

import software.amazon.awssdk.services.cloudwatch.model.PutMetricDataRequest;

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import java.time.Instant;

import java.time.ZoneOffset;

import java.time.ZonedDateTime;

import java.time.format.DateTimeFormatter;

Code

public static void putMetData(CloudWatchClient cw, Double dataPoint ) {

try {

Dimension dimension = Dimension.builder()

.name("UNIQUE_PAGES")

.value("URLS")

.build();

// Set an Instant object

187

AWS SDK for Java 2.x Developer Guide for version 2.x

Work with CloudWatch alarms

String time =

ZonedDateTime.now( ZoneOffset.UTC ).format( DateTimeFormatter.ISO_INSTANT );

Instant instant = Instant.parse(time);

MetricDatum datum = MetricDatum.builder()

.metricName("PAGES_VISITED")

.unit(StandardUnit.NONE)

.value(dataPoint)

.timestamp(instant)

.dimensions(dimension).build();

PutMetricDataRequest request = PutMetricDataRequest.builder()

.namespace("SITE/TRAFFIC")

.metricData(datum).build();

cw.putMetricData(request);

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

System.out.printf("Successfully put data point %f", dataPoint);

}

See the complete example on GitHub.

More information

• Using Amazon CloudWatch Metrics in the Amazon CloudWatch User Guide.

• AWS Namespaces in the Amazon CloudWatch User Guide.

• PutMetricData in the Amazon CloudWatch API Reference.

Work with CloudWatch alarms

Create an alarm

To create an alarm based on a CloudWatch metric, call the CloudWatchClient’s putMetricAlarm

method with a PutMetricAlarmRequest ﬁlled with the alarm conditions.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cloudwatch.CloudWatchClient;

import software.amazon.awssdk.services.cloudwatch.model.Dimension;

import software.amazon.awssdk.services.cloudwatch.model.PutMetricAlarmRequest;

import software.amazon.awssdk.services.cloudwatch.model.ComparisonOperator;

import software.amazon.awssdk.services.cloudwatch.model.Statistic;

import software.amazon.awssdk.services.cloudwatch.model.StandardUnit;

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

Code

public static void putMetricAlarm(CloudWatchClient cw, String alarmName, String

instanceId) {

try {

Dimension dimension = Dimension.builder()

.name("InstanceId")

188

AWS SDK for Java 2.x Developer Guide for version 2.x

Work with CloudWatch alarms

.value(instanceId).build();

PutMetricAlarmRequest request = PutMetricAlarmRequest.builder()

.alarmName(alarmName)

.comparisonOperator(

ComparisonOperator.GREATER_THAN_THRESHOLD)

.evaluationPeriods(1)

.metricName("CPUUtilization")

.namespace("AWS/EC2")

.period(60)

.statistic(Statistic.AVERAGE)

.threshold(70.0)

.actionsEnabled(false)

.alarmDescription(

"Alarm when server CPU utilization exceeds 70%")

.unit(StandardUnit.SECONDS)

.dimensions(dimension)

.build();

cw.putMetricAlarm(request);

System.out.printf(

"Successfully created alarm with name %s", alarmName);

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

List alarms

To list the CloudWatch alarms that you have created, call the CloudWatchClient’s describeAlarms

method with a DescribeAlarmsRequest that you can use to set options for the result.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cloudwatch.CloudWatchClient;

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import software.amazon.awssdk.services.cloudwatch.model.DescribeAlarmsRequest;

import software.amazon.awssdk.services.cloudwatch.model.DescribeAlarmsResponse;

import software.amazon.awssdk.services.cloudwatch.model.MetricAlarm;

Code

public static void desCWAlarms( CloudWatchClient cw) {

try {

boolean done = false;

String newToken = null;

while(!done) {

DescribeAlarmsResponse response;

if (newToken == null) {

DescribeAlarmsRequest request =

DescribeAlarmsRequest.builder().build();

response = cw.describeAlarms(request);

} else {

189

AWS SDK for Java 2.x Developer Guide for version 2.x

Work with CloudWatch alarms

DescribeAlarmsRequest request = DescribeAlarmsRequest.builder()

.nextToken(newToken)

.build();

response = cw.describeAlarms(request);

}

for(MetricAlarm alarm : response.metricAlarms()) {

System.out.printf("\n Retrieved alarm %s", alarm.alarmName());

}

if(response.nextToken() == null) {

done = true;

} else {

newToken = response.nextToken();

}

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

System.out.printf("Done");

}

The list of alarms can be obtained by calling MetricAlarms on the DescribeAlarmsResponse that is

returned by describeAlarms.

The results may be paged. To retrieve the next batch of results, call nextToken on the response object

and use the token value to build a new request object. Then call the describeAlarms method again

with the new request.

Note

You can also retrieve alarms for a speciﬁc metric by using the CloudWatchClient’s

describeAlarmsForMetric method. Its use is similar to describeAlarms.

See the complete example on GitHub.

Delete alarms

To delete CloudWatch alarms, call the CloudWatchClient’s deleteAlarms method with a

DeleteAlarmsRequest containing one or more names of alarms that you want to delete.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cloudwatch.CloudWatchClient;

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import software.amazon.awssdk.services.cloudwatch.model.DeleteAlarmsRequest;

Code

public static void deleteCWAlarm(CloudWatchClient cw, String alarmName) {

try {

DeleteAlarmsRequest request = DeleteAlarmsRequest.builder()

.alarmNames(alarmName)

.build();

cw.deleteAlarms(request);

System.out.printf("Successfully deleted alarm %s", alarmName);

190

AWS SDK for Java 2.x Developer Guide for version 2.x

Use alarm actions in CloudWatch

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

More information

• Creating Amazon CloudWatch Alarms in the Amazon CloudWatch User Guide

• PutMetricAlarm in the Amazon CloudWatch API Reference

• DescribeAlarms in the Amazon CloudWatch API Reference

• DeleteAlarms in the Amazon CloudWatch API Reference

Use alarm actions in CloudWatch

Using CloudWatch alarm actions, you can create alarms that perform actions such as automatically

stopping, terminating, rebooting, or recovering Amazon EC2 instances.

Note

Alarm actions can be added to an alarm by using the PutMetricAlarmRequest's alarmActions

method when creating an alarm (p. 188).

Enable alarm actions

To enable alarm actions for a CloudWatch alarm, call the CloudWatchClient’s enableAlarmActions

with a EnableAlarmActionsRequest containing one or more names of alarms whose actions you want to

enable.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cloudwatch.CloudWatchClient;

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import software.amazon.awssdk.services.cloudwatch.model.EnableAlarmActionsRequest;

import software.amazon.awssdk.services.cloudwatch.model.EnableAlarmActionsResponse;

Code

public static void enableActions(CloudWatchClient cw, String alarm) {

try {

EnableAlarmActionsRequest request = EnableAlarmActionsRequest.builder()

.alarmNames(alarm).build();

cw.enableAlarmActions(request);

System.out.printf(

"Successfully enabled actions on alarm %s", alarm);

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

191

AWS SDK for Java 2.x Developer Guide for version 2.x

Send events to CloudWatch

Disable alarm actions

To disable alarm actions for a CloudWatch alarm, call the CloudWatchClient’s disableAlarmActions

with a DisableAlarmActionsRequest containing one or more names of alarms whose actions you want to

disable.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cloudwatch.CloudWatchClient;

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import software.amazon.awssdk.services.cloudwatch.model.DisableAlarmActionsRequest;

Code

public static void disableActions(CloudWatchClient cw, String alarmName) {

try {

DisableAlarmActionsRequest request = DisableAlarmActionsRequest.builder()

.alarmNames(alarmName)

.build();

cw.disableAlarmActions(request);

System.out.printf(

"Successfully disabled actions on alarm %s", alarmName);

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

More information

• Create Alarms to Stop, Terminate, Reboot, or Recover an Instance in the Amazon CloudWatch User

Guide

• PutMetricAlarm in the Amazon CloudWatch API Reference

• EnableAlarmActions in the Amazon CloudWatch API Reference

• DisableAlarmActions in the Amazon CloudWatch API Reference

Send events to CloudWatch

CloudWatch Events delivers a near real-time stream of system events that describe changes in AWS

resources to Amazon EC2 instances, Lambda functions, Kinesis streams, Amazon ECS tasks, Step

Functions state machines, Amazon SNS topics, Amazon SQS queues, or built-in targets. You can match

events and route them to one or more target functions or streams by using simple rules.

Add events

To add custom CloudWatch events, call the CloudWatchEventsClient’s putEvents method with a

PutEventsRequest object that contains one or more PutEventsRequestEntry objects that provide details

about each event. You can specify several parameters for the entry such as the source and type of the

event, resources associated with the event, and so on.

192

AWS SDK for Java 2.x Developer Guide for version 2.x

Send events to CloudWatch

Note

You can specify a maximum of 10 events per call to putEvents.

Imports

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import software.amazon.awssdk.services.cloudwatchevents.CloudWatchEventsClient;

import software.amazon.awssdk.services.cloudwatchevents.model.PutEventsRequest;

import software.amazon.awssdk.services.cloudwatchevents.model.PutEventsRequestEntry;

Code

public static void putCWEvents(CloudWatchEventsClient cwe, String resourceArn ) {

try {

final String EVENT_DETAILS =

"{ \"key1\": \"value1\", \"key2\": \"value2\" }";

PutEventsRequestEntry requestEntry = PutEventsRequestEntry.builder()

.detail(EVENT_DETAILS)

.detailType("sampleSubmitted")

.resources(resourceArn)

.source("aws-sdk-java-cloudwatch-example")

.build();

PutEventsRequest request = PutEventsRequest.builder()

.entries(requestEntry)

.build();

cwe.putEvents(request);

System.out.println("Successfully put CloudWatch event");

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

Add rules

To create or update a rule, call the CloudWatchEventsClient’s putRule method with a PutRuleRequest

with the name of the rule and optional parameters such as the event pattern, IAM role to associate with

the rule, and a scheduling expression that describes how often the rule is run.

Imports

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import software.amazon.awssdk.services.cloudwatchevents.CloudWatchEventsClient;

import software.amazon.awssdk.services.cloudwatchevents.model.PutRuleRequest;

import software.amazon.awssdk.services.cloudwatchevents.model.PutRuleResponse;

import software.amazon.awssdk.services.cloudwatchevents.model.RuleState;

Code

public static void putCWRule(CloudWatchEventsClient cwe, String ruleName, String

roleArn) {

193

AWS SDK for Java 2.x Developer Guide for version 2.x

Send events to CloudWatch

try {

PutRuleRequest request = PutRuleRequest.builder()

.name(ruleName)

.roleArn(roleArn)

.scheduleExpression("rate(5 minutes)")

.state(RuleState.ENABLED)

.build();

PutRuleResponse response = cwe.putRule(request);

System.out.printf(

"Successfully created CloudWatch events rule %s with arn %s",

roleArn, response.ruleArn());

} catch (

CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

Add targets

Targets are the resources that are invoked when a rule is triggered. Example targets include Amazon EC2

instances, Lambda functions, Kinesis streams, Amazon ECS tasks, Step Functions state machines, and

built-in targets.

To add a target to a rule, call the CloudWatchEventsClient’s putTargets method with a

PutTargetsRequest containing the rule to update and a list of targets to add to the rule.

Imports

import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException;

import software.amazon.awssdk.services.cloudwatchevents.CloudWatchEventsClient;

import software.amazon.awssdk.services.cloudwatchevents.model.PutTargetsRequest;

import software.amazon.awssdk.services.cloudwatchevents.model.PutTargetsResponse;

import software.amazon.awssdk.services.cloudwatchevents.model.Target;

Code

public static void putCWTargets(CloudWatchEventsClient cwe, String ruleName, String

functionArn, String targetId ) {

try {

Target target = Target.builder()

.arn(functionArn)

.id(targetId)

.build();

PutTargetsRequest request = PutTargetsRequest.builder()

.targets(target)

.rule(ruleName)

.build();

PutTargetsResponse response = cwe.putTargets(request);

System.out.printf(

"Successfully created CloudWatch events target for rule %s",

ruleName);

} catch (CloudWatchException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

194

AWS SDK for Java 2.x Developer Guide for version 2.x

Amazon Cognito

}

See the complete example on GitHub.

More information

• Adding Events with PutEvents in the Amazon CloudWatch Events User Guide

• Schedule Expressions for Rules in the Amazon CloudWatch Events User Guide

• Event Types for CloudWatch Events in the Amazon CloudWatch Events User Guide

• Events and Event Patterns in the Amazon CloudWatch Events User Guide

• PutEvents in the Amazon CloudWatch Events API Reference

• PutTargets in the Amazon CloudWatch Events API Reference

• PutRule in the Amazon CloudWatch Events API Reference

Work with Amazon Cognito

With Amazon Cognito, you can quickly add user sign-up or sign-in capability to your web or mobile app.

The examples here demonstrate some of the basic functionality of Amazon Cognito.

Create a user pool

A user pool is a directory of users that you can conﬁgure for your web or mobile app.

To create a user pool, start by building a CreateUserPoolRequest object, with the name of the user pool

as the value of its poolName(). Call the createUserPool() method of your CreateUserPoolRequest,

passing in the CreateUserPoolRequest object. You can capture the result of this request as a

CreateUserPoolResponse object, as demonstrated in the following code snippet.

Imports

import software.amazon.awssdk.regions.Region;

import

software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CognitoIdentityProviderException;

import software.amazon.awssdk.services.cognitoidentityprovider.model.CreateUserPoolRequest;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CreateUserPoolResponse;

Code

public static String createPool(CognitoIdentityProviderClient cognitoClient, String

userPoolName ) {

try {

CreateUserPoolResponse response = cognitoClient.createUserPool(

CreateUserPoolRequest.builder()

.poolName(userPoolName)

.build()

);

return response.userPool().id();

195

AWS SDK for Java 2.x Developer Guide for version 2.x

List users from a user pool

} catch (CognitoIdentityProviderException e){

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

return "";

}

See the complete example on GitHub.

List users from a user pool

To list users from your user pools, start by building a ListUserPoolsRequest object, with the number

of maximum results as the value of its maxResults(). Call the listUserPools() method of your

CognitoIdentityProviderClient, passing in the ListUserPoolsRequest object. You can capture

the result of this request as a ListUserPoolsResponse object, as demonstrated in the following code

snippet. Create a UserPoolDescriptionType object to easily iterate over the results and pull out the

attributes of each user.

Imports

import software.amazon.awssdk.regions.Region;

import

software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CognitoIdentityProviderException;

import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsResponse;

import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;

Code

public static void listAllUserPools(CognitoIdentityProviderClient cognitoClient ) {

try {

ListUserPoolsRequest request = ListUserPoolsRequest.builder()

.maxResults(10)

.build();

ListUserPoolsResponse response = cognitoClient.listUserPools(request);

response.userPools().forEach(userpool -> {

System.out.println("User pool " + userpool.name() + ", User ID " +

userpool.id() );

}

);

} catch (CognitoIdentityProviderException e){

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

Create an identity pool

An identity pool is a container that organizes the IDs from your external identity provider,

keeping a unique identiﬁer for each user. To create an identity pool, start by building a

CreateIdentityPoolRequest with the name of the user pool as the value of its identityPoolName().

Set allowUnauthenticatedIdentities() to true or false. Call the createIdentityPool()

196

AWS SDK for Java 2.x Developer Guide for version 2.x

Add an app client

method of your CognitoIdentityClient object, passing in the CreateIdentityPoolRequest

object. You can capture the result of this request as a CreateIdentityPoolResponse object, as

demonstrated in the following code snippet.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cognitoidentity.CognitoIdentityClient;

import software.amazon.awssdk.services.cognitoidentity.model.CreateIdentityPoolRequest;

import software.amazon.awssdk.services.cognitoidentity.model.CreateIdentityPoolResponse;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CognitoIdentityProviderException;

Code

public static String createIdPool(CognitoIdentityClient cognitoClient, String

identityPoolName ) {

try {

CreateIdentityPoolRequest poolRequest = CreateIdentityPoolRequest.builder()

.allowUnauthenticatedIdentities(false)

.identityPoolName(identityPoolName)

.build() ;

CreateIdentityPoolResponse response =

cognitoClient.createIdentityPool(poolRequest);

return response.identityPoolId();

} catch (CognitoIdentityProviderException e){

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

return "";

}

See the complete example on GitHub.

Add an app client

To enable the hosted web sign-up or sign-in UI for your app, create an app client. To create an app client,

start by building a CreateUserPoolClientRequest object, with the name of the client as the value of its

clientName(). Set userPoolId() to the ID of the user pool to which you want to attach this app

client. Call the createUserPoolClient() method of your CognitoIdentityProviderClient,

passing in the CreateUserPoolClientRequest object. You can capture the result of this request as a

CreateUserPoolClientResponse object, as demonstrated in the following code snippet.

Imports

import software.amazon.awssdk.regions.Region;

import

software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CognitoIdentityProviderException;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CreateUserPoolClientRequest;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CreateUserPoolClientResponse;

Code

197

AWS SDK for Java 2.x Developer Guide for version 2.x

Add a third-party identity provider

public static void createPoolClient ( CognitoIdentityProviderClient cognitoClient,

String clientName,

String userPoolId ) {

try {

CreateUserPoolClientResponse response = cognitoClient.createUserPoolClient(

CreateUserPoolClientRequest.builder()

.clientName(clientName)

.userPoolId(userPoolId)

.build()

);

System.out.println("User pool " + response.userPoolClient().clientName() + "

created. ID: " + response.userPoolClient().clientId());

} catch (CognitoIdentityProviderException e){

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

Add a third-party identity provider

Adding an external identity provider (IdP) enables your users to log into your app using that

service’s login mechanism. To add a third-party IdP, start by building an UpdateIdentityPoolRequest

object, with the name of the identity pool as the value of its identityPoolName(). Set

allowUnauthenticatedIdentities() to true or false, specify the identityPoolId(),

and deﬁne which login providers will be supported with supportedLoginProviders().

Call the updateIdentityPool() method of your CognitoIdentityClient, passing in

the UpdateIdentityPoolRequest object. You can capture the result of this request as an

UpdateIdentityPoolResponse object, as demonstrated in the following code snippet.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cognitoidentity.CognitoIdentityClient;

import software.amazon.awssdk.services.cognitoidentity.model.CognitoIdentityProvider;

import software.amazon.awssdk.services.cognitoidentity.model.UpdateIdentityPoolRequest;

import software.amazon.awssdk.services.cognitoidentity.model.UpdateIdentityPoolResponse;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CognitoIdentityProviderException;

import java.util.ArrayList;

import java.util.List;

Code

public static void createNewUser(CognitoIdentityProviderClient cognitoClient,

String userPoolId,

String name,

String email,

String password){

try{

AttributeType userAttrs = AttributeType.builder()

.name("email")

.value(email)

198

AWS SDK for Java 2.x Developer Guide for version 2.x

Get credentials for an ID

.build();

AdminCreateUserRequest userRequest = AdminCreateUserRequest.builder()

.userPoolId(userPoolId)

.username(name)

.temporaryPassword(password)

.userAttributes(userAttrs)

.messageAction("SUPPRESS")

.build() ;

AdminCreateUserResponse response = cognitoClient.adminCreateUser(userRequest);

System.out.println("User " + response.user().username() + "is created. Status:

" + response.user().userStatus());

} catch (CognitoIdentityProviderException e){

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

See the complete example on GitHub.

Get credentials for an ID

To get the credentials for an identity in an identity pool, ﬁrst build a GetCredentialsForIdentityRequest

with the identity ID as the value of its identityId(). Call the getCredentialsForIdentity()

method of your CognitoIdentityClient, passing in the GetCredentialsForIdentityRequest.

You can capture the result of this request as a GetCredentialsForIdentityResponse object, as

demonstrated in the following code snippet.

Imports

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.cognitoidentity.CognitoIdentityClient;

import

software.amazon.awssdk.services.cognitoidentity.model.GetCredentialsForIdentityRequest;

import

software.amazon.awssdk.services.cognitoidentity.model.GetCredentialsForIdentityResponse;

import

software.amazon.awssdk.services.cognitoidentityprovider.model.CognitoIdentityProviderException;

Code

public static void getCredsForIdentity(CognitoIdentityClient cognitoClient, String

identityId) {

try {

GetCredentialsForIdentityRequest getCredentialsForIdentityRequest =

GetCredentialsForIdentityRequest.builder()

.identityId(identityId)

.build();

GetCredentialsForIdentityResponse response =

cognitoClient.getCredentialsForIdentity(getCredentialsForIdentityRequest);

System.out.println("Identity ID " + response.identityId() + ", Access key ID "

+ response.credentials().accessKeyId());

} catch (CognitoIdentityProviderException e) {

System.err.println(e.awsErrorDetails().errorMessage());

System.exit(1);

}

199

AWS SDK for Java 2.x Developer Guide for version 2.x

AWS database services

}

See the complete example on GitHub.

For more information, see the Amazon Cognito Developer Guide.

AWS database services and AWS SDK for Java 2.x

AWS oﬀers several database types: relational, key-value, in-memory, document, and several others. The

SDK for Java 2.x support varies depending the nature of the database service in AWS.

Some database services, for example Amazon DynamoDB service, have web service APIs to manage the

AWS resource (database) as well as web service APIs to interact with the data. In the SDK for Java 2.x

these types of services have dedicated service clients, for example DynamoDBClient.

Other database services have web service APIs that interact with the resource, such the Amazon

DocumentDB API (for cluster, instance and resource management), but do not have a web service API for

working with the data. The SDK for Java 2.x has a corresponding DocDbClient interface for working with

the resource. However, you need another Java API, such as MongoDB for Java to work with the data.

Use the examples below to learn how you use the SDK for Java 2.x service clients with the diﬀerent types

of databases.

Amazon DynamoDB examples

Working with the data Working with the database

SDK service client: DynamoDBClient SDK service client: DynamoDBClient

Example: React/Spring REST application using

DynamoDB

Examples: CreateTable, ListTables, DeleteTable

Examples: Several DynamoDB examples

SDK service client: DynamoDBEnhancedClient

Example: React/Spring REST application using

DynamoDB

Examples: Several DynamoDB examples (names

starting with 'Enhanced")

See additional DynamoDB examples (p. 201) in the guided code examples section of this guide.

Amazon RDS examples

Working with the data Working with the database

Non-SDK API: JDBC, database-speciﬁc SQL ﬂavor;

your code manages database connections or a

connection pool.

SDK service client: RdsClient

200

AWS SDK for Java 2.x Developer Guide for version 2.x

Amazon Redshift

Working with the data Working with the database

Example: React/Spring REST application using

MySQL

Examples: Several RdsClient examples

Amazon Redshift examples

Working with the data Working with the database

SDK service client: RedshiftDataClient SDK service client: RedshiftClient

Examples: Several RedshiftDataClient examples Examples: Several RedshiftClient examples

Example: React/Spring REST application using

RedshiftDataClient



Amazon Aurora Serverless v1 examples

Working with the data Working with the database

SDK service client: RdsDataClient SDK service client: RdsClient

Example: React/Spring REST application using

RdsDataClient

Examples: Several RdsClient examples

Amazon DocumentDB examples

Working with the data Working with the database

Non-SDK API: MongoDB-speciﬁc Java library (for

example MongoDB for Java); your code manages

database connections or a connection pool.

SDK service client: DocDbClient

Examples: DocumentDB (Mongo) Developer Guide

(select 'Java' tab)



Work with DynamoDB

This section provides examples that show you how to work with DynamoDB. The examples in this section

use the standard, low-level DynamoDB client (DynamoDbClient) oﬀered with the AWS SDK for Java 2.x.

The SDK also oﬀers the DynamoDB Enhanced Client (p. 81) that provides a high-level, object-oriented

approach for working with DynamoDB.

Topics

• Work with tables in DynamoDB (p. 202)

• Work with items in DynamoDB (p. 208)

201

AWS SDK for Java 2.x Developer Guide for version 2.x

Work with tables in DynamoDB

Tables are the containers for all items in a DynamoDB database. Before you can add or remove data from

DynamoDB, you must create a table.

For each table, you must deﬁne:

• A table name that is unique for your account and region.

• A primary key for which every value must be unique; no two items in your table can have the same

primary key value.

A primary key can be simple, consisting of a single partition (HASH) key, or composite, consisting of a

partition and a sort (RANGE) key.

Each key value has an associated data type, enumerated by the ScalarAttributeType class. The key

value can be binary (B), numeric (N), or a string (S). For more information, see Naming Rules and Data

Types in the Amazon DynamoDB Developer Guide.

• Provisioned throughput are values that deﬁne the number of reserved read/write capacity units for the

table.

Note

Amazon DynamoDB pricing is based on the provisioned throughput values that you set on

your tables, so reserve only as much capacity as you think you’ll need for your table.

Provisioned throughput for a table can be modiﬁed at any time, so you can adjust capacity as your

needs change.

Create a table

Use the DynamoDbClient’s createTable method to create a new DynamoDB table. You need to

construct table attributes and a table schema, both of which are used to identify the primary key of your

table. You must also supply initial provisioned throughput values and a table name.

Note

If a table with the name you chose already exists, an DynamoDbException is thrown.

Create a table with a simple primary key

This code creates a table with one attribute that is the table's simple primary key. the example uses

AttributeDeﬁnition and KeySchemaElement objects for the CreateTableRequest.

Imports

import software.amazon.awssdk.core.waiters.WaiterResponse;

import software.amazon.awssdk.regions.Region;

import software.amazon.awssdk.services.dynamodb.model.CreateTableRequest;

import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition;

import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType;

import software.amazon.awssdk.services.dynamodb.model.KeySchemaElement;

import software.amazon.awssdk.services.dynamodb.model.ProvisionedThroughput;

import software.amazon.awssdk.services.dynamodb.model.KeyType;

import software.amazon.awssdk.services.dynamodb.model.CreateTableResponse;

import software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest;

import software.amazon.awssdk.services.dynamodb.model.DescribeTableResponse;

import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;

import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;

202

AWS SDK for Java 2.x Developer Guide for version 2.x

Work with tables in DynamoDB

Code

public static String createTable(DynamoDbClient ddb, String tableName, String key) {

DynamoDbWaiter dbWaiter = ddb.waiter();

CreateTableRequest request = CreateTableRequest.builder()

.attributeDefinitions(AttributeDefinition.builder()

.attributeName(key)

.attributeType(ScalarAttributeType.S)

.build())

.keySchema(KeySchemaElement.builder()

.attributeName(key)

.keyType(KeyType.HASH)

.build())

.provisionedThroughput(ProvisionedThroughput.builder()

.readCapacityUnits(new Long(10))

.writeCapacityUnits(new Long(10))

.build())

.tableName(tableName)

.build();

String newTable ="";

try {

CreateTableResponse response = ddb.createTable(request);

DescribeTableRequest tableRequest = DescribeTableRequest.builder()

.tableName(tableName)

.build();

// Wait until the Amazon DynamoDB table is created

WaiterResponse<DescribeTableResponse> waiterResponse =

dbWaiter.waitUntilTableExists(tableRequest);

waiterResponse.matched().response().ifPresent(System.out::println);

newTable = response.tableDescription().tableName();

return newTable;

} catch (DynamoDbException e) {

System.err.println(e.getMessage());

System.exit(1);

}

return "";

}

See the complete example on GitHub.

Create a table with a composite primary key

The following example creates a table with two attributes. Both attributes are used for the composite

primary key.