Using the AWS SDK for Java 2.x

After completing the steps in Setting up the SDK, you are ready to make requests to AWS services such as Amazon S3, DynamoDB, IAM, Amazon EC2, and more.

Creating service clients

To make a request to an AWS service, you must first instantiate an object to serve as a client for that service using the static factory method builder. Then customize it by using the setters in the builder. The fluent setter methods return the builder object, so that you can chain the method calls for convenience and for more readable code. After you configure the properties you want, you can call the build method to create the client.

As an example, this 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 different configuration 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 for more information.

Using the default client

The client builders have another factory method named create. This method creates a service client with the default configuration. 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 and Region selection for more information about how credentials and region are determined.

As an example, this code snippet instantiates a DynamoDbClient object as a service client for Amazon DynamoDB:

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

Making requests

You use the service client to make requests to that AWS service.

For example, this code snippet shows how to create a RunInstancesRequest object to create a new Amazon EC2 instance:

RunInstancesRequest runInstancesRequest = RunInstancesRequest.builder()
        .imageId(amiId)
        .instanceType(InstanceType.T1_MICRO)
        .maxCount(1)
        .minCount(1)
        .build();

ec2Client.runInstances(runInstancesRequest);

Handling 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());

Closing the client

When you no longer need the service client, close it.

ec2Client.close();

Note

Service clients extend the AutoClosable interface, but as a best practice - especially with short-lived code such as AWS Lambda functions - you should explicitly call the close() method.

Handling exceptions

The SDK uses runtime (or unchecked) exceptions, providing you fine-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 while uploading a file to Amazon S3.

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 e) {
    System.err.println(e.awsErrorDetails().errorMessage());
    System.exit(1);
}

See Handling exceptions for more information.

Using 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 for more information.

Configuring service clients

To customize the configuration of a service client, use the setters on the factory method builder. For convenience and to create more readable code, you chain the methods to set multiple configuration options.

As an example, refere to the following code snippet.

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();

HTTP clients

You can change the default configuration for HTTP clients in applications you build with the AWS SDK for Java. For information on how to configure HTTP clients and settings, see HTTP configuration.

Retries

You can change the default settings for retries in your service clients, including the retry mode and back-off 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 backoff in AWS.

Timeouts

You can configure 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 different parts of the request/response lifecycle. This enables you to publish metrics, modify a request in-flight, debug request processing, view exceptions, and more. For more information, see the ExecutionInterceptor interface in the AWS SDK for Java API Reference.

Additional information

• For complete examples of the code snippets above, see Working with Amazon DynamoDB, Working with Amazon EC2, and Working with Amazon S3.