• 1. Clients
  • 1.1. Client Creation Defaults
  • 1.2. AWS Client Configuration: Custom Regions, Credentials and Endpoints
    • 1.2.1. Client Regions
    • 1.2.2. Client Credentials
  • 1.3. SDK Client Configuration
    • 1.3.1. Client HTTP Configuration
    • 1.3.2. Client HTTP Proxy Configuration
    • 1.3.3. Client Override Configuration
    • 1.3.4. Client Override Retry Configuration
    • 1.3.5. Async Configuration
    • 1.3.6. Other Options
• 2. Operations, Request and Response Changes
  • 2.1. Streaming Operations
• 3. Exception Changes
• 4. Service Changes
  • 4.1. S3 Changes
    • 4.1.1. S3 Operation Migration
  • 4.2. SNS Changes
  • 4.3. SQS Changes
• 5. Profile File Changes
• 6. Conversion Tables
  • 6.1. Environment Variables and System Properties
  • 6.2. Credential Providers
  • 6.3. Client Names
• 7. High-Level Libraries

Clients, like the DynamoDbClient are the most direct way of communicating with AWS services. See 7. High-Level Libraries for the status of high-level libraries like S3 Transfer Manager, the Dynamo DB Mapper, S3 Encryption Client and waiters.

In 2.0, the following changes have been made to the clients:

1. Clients can no longer be mutated.
2. Clients can no longer be created by their default constructor. The static create or builder methods must be used instead: new AmazonDynamoDBClient is now DynamoDbClient.create and AmazonDynamoDBClient.builder is now DynamoDbClient.builder.
3. Client builders no longer contain static methods. The static methods on the clients must be used: AmazonDynamoDBClientBuilder.defaultClient is now DynamoDbClient.create and AmazonDynamoDBClientBuilder.standard is now DynamoDbClient.builder.
4. Client classes have been renamed. See 6.3. Client Names for the 2.0-equivalent client names.
5. Async clients now use non-blocking IO.
6. Async operations now return CompletableFuture.
7. Async clients now use an internal executor only for calling complete on the CompletableFuture and retries.

In 2.0, the following changes have been made to the default client creation logic:

1. The default credential provider chain for S3 no longer includes anonymous credentials. Anonymous access to S3 must be specified manually using the AnonymousCredentialsProvider.
2. The following environment variables related to default client creation have been changed:
   1. AWS_CBOR_DISABLED is now CBOR_ENABLED
   2. AWS_ION_BINARY_DISABLE is now BINARY_ION_ENABLED
3. The following system properties related to default client creation have been changed:
   1. com.amazonaws.sdk.disableEc2Metadata is now aws.disableEc2Metadata.
   2. com.amazonaws.sdk.ec2MetadataServiceEndpointOverride is now aws.ec2MetadataServiceEndpoint.
   3. com.amazonaws.sdk.disableCbor is now aws.cborEnabled.
   4. com.amazonaws.sdk.disableIonBinary is now aws.binaryIonEnabled.
   5. The following system properties no longer supported: com.amazonaws.sdk.disableCertChecking, com.amazonaws.sdk.enableDefaultMetrics, com.amazonaws.sdk.enableThrottledRetry, com.amazonaws.regions.RegionUtils.fileOverride, com.amazonaws.regions.RegionUtils.disableRemote, com.amazonaws.services.s3.disableImplicitGlobalClients, com.amazonaws.sdk.enableInRegionOptimizedMode
4. Loading region configuration from a custom endpoints.json file is no longer supported.
5. The default credentials logic has been modified. See com.amazonaws.auth.DefaultAWSCredentialsProviderChain changes below for more information.
6. Profile file format has changed to more closely match the CLI's behavior. See 5. Profile File Changes.

In 2.0, regions, credentials and endpoints must be specified using the client builder.

In 2.0, the following changes have been made related to regions:

1. When using a service that does not currently have region-specific endpoints, you must use Region.AWS_GLOBAL or Region.AWS_CN_GLOBAL instead of a region-specific endpoint.
2. com.amazonaws.regions.Regions changes:
   1. This class has been replaced with software.amazon.awssdk.regions.Region.
   2. Regions.fromName is now Region.of.
   3. Regions.getName is now Region.id.
   4. The following Regions methods and fields are no longer supported: DEFAULT_REGION, getDescription, getCurrentRegion, name.
3. com.amazonaws.regions.Region changes:
   1. For region identification:
      1. This class has been replaced with software.amazon.awssdk.regions.Region, created with Region.of.
      2. Region.getName is now Region.id.
   2. For region metadata:
      1. This class has been replaced with software.amazon.awssdk.regions.RegionMetadata, created with RegionMetadata.of.
      2. Region.getName is now RegionMetadata.name.
      3. Region.getDomain is now RegionMetadata.domain.
      4. Region.getPartition is now RegionMetadata.partition.
   3. For service metadata:
      1. This class has been replaced with software.amazon.awssdk.regions.ServiceMetadata, created by calling ServiceMetadata.of (or the serviceMetadata method on any service client).
      2. Region.getServiceEndpoint is now ServiceMetadata.endpointFor(Region).
      3. Region.isServiceSupported is now ServiceMetadata.regions().contains(Region).
   4. The following Region methods are no longer supported: hasHttpsEndpoint, hasHttpEndpoint, getAvailableEndpoints, createClient.

In 2.0, the following changes have been made related to the credentials providers:

1. com.amazonaws.auth.AWSCredentialsProvider changes:
   1. This class has been replaced with software.amazon.awssdk.auth.credentials.AwsCredentialsProvider.
   2. AWSCredentialsProvider.getCredentials is now AwsCredentialsProvider.resolveCredentials.
   3. The following AWSCredentialsProvider methods are no longer supported: refresh.
2. com.amazonaws.auth.DefaultAWSCredentialsProviderChain changes:
   1. This class has been replaced with software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider.
   2. new DefaultAWSCredentialsProviderChain is now DefaultCredentialsProvider.create.
   3. System properties are treated as higher-priority than environment variables.
   4. See EnvironmentVariableCredentialsProvider, SystemPropertiesCredentialsProvider, ProfileCredentialsProvider and EC2ContainerCredentialsProviderWrapper below for more changes.
   5. The following DefaultAWSCredentialsProviderChain methods are no longer supported: getInstance.
3. com.amazonaws.auth.AWSStaticCredentialsProvider changes:
   1. This class has been replaced with software.amazon.awssdk.auth.credentials.StaticCredentialsProvider.
   2. new AWSStaticCredentialsProvider is now StaticCredentialsProvider.create.
4. com.amazonaws.auth.EnvironmentVariableCredentialsProvider changes:
   1. This class has been replaced with software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider.
   2. new EnvironmentVariableCredentialsProvider is now EnvironmentVariableCredentialsProvider.create.
   3. The AWS_ACCESS_KEY environment variable is now AWS_ACCESS_KEY_ID.
   4. The AWS_SECRET_KEY environment variable is now AWS_SECRET_ACCESS_KEY.
5. com.amazonaws.auth.SystemPropertiesCredentialsProvider changes:
   1. This class has been replaced with software.amazon.awssdk.auth.credentials.SystemPropertyCredentialsProvider.
   2. new SystemPropertiesCredentialsProvider is now SystemPropertyCredentialsProvider.create.
   3. The aws.secretKey system property is now aws.secretAccessKey.
6. com.amazonaws.auth.profile.ProfileCredentialsProvider changes:
   1. This class has been replaced with software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider.
   2. new ProfileCredentialsProvider is now ProfileCredentialsProvider.create.
   3. Custom profile file paths are now specified via ProfileCredentialsProvider.builder.
   4. The AWS_CREDENTIAL_PROFILES_FILE environment variable is now AWS_SHARED_CREDENTIALS_FILE.
   5. Profile file format has changed to more closely match the CLI's behavior. See 5. Profile File Changes.
7. com.amazonaws.auth.ContainerCredentialsProvider changes:
   1. This class has been replaced with software.amazon.awssdk.auth.credentials.ContainerCredentialsProvider.
   2. Async refresh is specified via ContainerCredentialsProvider.builder.
   3. new ContainerCredentialsProvider is now ContainerCredentialsProvider.create.
8. com.amazonaws.auth.InstanceProfileCredentialsProvider changes:
   1. This class has been replaced with software.amazon.awssdk.auth.credentials.InstanceProfileCredentialsProvider.
   2. Async refresh is specified via InstanceProfileCredentialsProvider.builder.
   3. new InstanceProfileCredentialsProvider is now InstanceProfileCredentialsProvider.create.
   4. The com.amazonaws.sdk.disableEc2Metadata system property is now aws.disableEc2Metadata.
   5. The com.amazonaws.sdk.ec2MetadataServiceEndpointOverride system property is now aws.ec2MetadataServiceEndpoint.
   6. The following AWSCredentialsProvider methods are no longer supported: getInstance.
9. com.amazonaws.auth.STSAssumeRoleSessionCredentialsProvider changes:
   1. This class has been replaced with software.amazon.awssdk.services.sts.auth.StsAssumeRoleCredentialsProvider.
   2. Async refresh is no longer the default, but can be specified via StsAssumeRoleCredentialsProvider.builder.
   3. new STSAssumeRoleSessionCredentialsProvider and new STSAssumeRoleSessionCredentialsProvider.Builder are now StsAssumeRoleCredentialsProvider.builder.
   4. All builder configuration has been replaced in favor of specifying a StsClient and AssumeRoleRequest request.
10. com.amazonaws.auth.STSSessionCredentialsProvider changes:
    1. This class has been replaced with software.amazon.awssdk.services.sts.auth.StsGetSessionTokenCredentialsProvider.
    2. Async refresh is no longer the default, but can be specified via StsGetSessionTokenCredentialsProvider.builder.
    3. new STSAssumeRoleSessionCredentialsProvider is now StsGetSessionTokenCredentialsProvider.builder.
    4. All constructor parameters have been replaced in favor of specifying a StsClient and GetSessionTokenRequest request in a builder.
11. com.amazonaws.auth.WebIdentityFederationSessionCredentialsProvider changes:
    1. This class has been replaced with software.amazon.awssdk.services.sts.auth.StsAssumeRoleWithWebIdentityCredentialsProvider.
    2. Async refresh is no longer the default, but can be specified via StsAssumeRoleWithWebIdentityCredentialsProvider.builder.
    3. new WebIdentityFederationSessionCredentialsProvider is now StsAssumeRoleWithWebIdentityCredentialsProvider.builder.
    4. All constructor parameters have been replaced in favor of specifying a StsClient and AssumeRoleWithWebIdentityRequest request in a builder.
12. com.amazonaws.auth.EC2ContainerCredentialsProviderWrapper has been removed in favor of software.amazon.awssdk.auth.credentials.ContainerCredentialsProvider and software.amazon.awssdk.auth.credentials.InstanceProfileCredentialsProvider.
13. com.amazonaws.services.s3.S3CredentialsProviderChain has been removed in favor of software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider and software.amazon.awssdk.auth.credentials.AnonymousCredentialsProvider.
14. com.amazonaws.auth.ClasspathPropertiesFileCredentialsProvider and com.amazonaws.auth.PropertiesFileCredentialsProvider have been removed.

In 1.11.x, SDK client configuration was modified by setting a ClientConfiguration instance on the client or client builder:

In 2.0, SDK client configuration is split into separate configuration settings:

Synchronous Configuration

ProxyConfiguration.Builder proxyConfig =
        ProxyConfiguration.builder();

ApacheHttpClient.Builder httpClientBuilder = 
        ApacheHttpClient.builder()
                        .proxyConfiguration(proxyConfig.build());

ClientOverrideConfiguration.Builder overrideConfig =
        ClientOverrideConfiguration.builder();

DynamoDbClient client = 
        DynamoDbClient.builder()
                      .httpClientBuilder(httpClientBuilder)
                      .overrideConfiguration(overrideConfig.build())
                      .build();

Asynchronous Configuration

NettyNioAsyncHttpClient.Builder httpClientBuilder = 
        NettyNioAsyncHttpClient.builder();

ClientOverrideConfiguration.Builder overrideConfig =
        ClientOverrideConfiguration.builder();

ClientAsyncConfiguration.Builder asyncConfig =
        ClientAsyncConfiguration.builder();

DynamoDbAsyncClient client = 
        DynamoDbAsyncClient.builder()
                           .httpClientBuilder(httpClientBuilder)
                           .overrideConfiguration(overrideConfig.build())
                           .asyncConfiguration(asyncConfig.build())
                           .build();

1. It is now possible to change which HTTP client is used at runtime by specifying an implementation via clientBuilder.httpClientBuilder.
2. HTTP clients passed to clientBuilder.httpClient are not closed by default, allowing them to be shared between AWS clients.
3. HTTP for async clients now use non-blocking IO.
4. Some operations now utilize HTTP/2 for performance improvements.

Retry configuration has changed in 2.0 to be controlled entirely through the RetryPolicy in the ClientOverrideConfiguration.

1. Async executors passed to asyncConfig.advancedOption(SdkAdvancedAsyncClientOption.FUTURE_COMPLETION_EXECUTOR, ...) must be shut down by the user.

These ClientConfiguration options from 1.11.x have changed in 2.0 of the SDK and don't have direct equivalents.

Requests, like DynamoDbClient's PutItemRequest are passed to a client operation, like DynamoDbClient.putItem. These operations return a response from the AWS service, like a PutItemResponse.

In 2.0, the following changes have been made to the operations:

1. Operations with multiple response pages now have a Paginator method for automatically iterating over all items in the response.
2. Requests and responses can no longer be mutated.
3. Requests and responses can no longer be created by their default constructor. The static builder method must be used instead: new PutItemRequest().withTableName(...) is now PutItemRequest.builder().tableName(...).build().
4. Operations and requests support a short-hand method of creating requests: dynamoDbClient.putItem(request -> request.tableName(...)).

Streaming operations, like S3Client's getObject and putObject accept a stream of bytes or return a stream of bytes, without loading the entire payload into memory.

1. Streaming operation request objects no longer include the payload.
2. Sync streaming request methods now accept request payloads as a RequestBody that simplifies common loading logic: eg. RequestBody.fromFile(...).
3. Async streaming request methods now accept request payloads as an AsyncRequestBody that simplifies common loading logic: eg. AsyncRequestBody.fromFile(...).
4. Sync streaming response methods now specify response handling as a ResponseTransformer that simplifies common transformation logic: eg. ResponseTransformer.toFile(...).
5. Async streaming response methods now specify response handling as an AsyncResponseTransformer that simplifies common transformation logic: eg. AsyncResponseTransformer.toFile(...).
6. Streaming response operations now have an AsBytes method to load the response into memory and simplify common in-memory type conversions.

In 2.0, the following changes have been made related to exceptions:

1. com.amazonaws.SdkBaseException and com.amazonaws.AmazonClientException changes:
   1. These classes have combined and replaced with software.amazon.awssdk.core.exception.SdkException.
   2. AmazonClientException.isRetryable is now SdkException.retryable.
2. com.amazonaws.SdkClientException changes:
   1. This class has been replaced with software.amazon.awssdk.core.exception.SdkClientException.
   2. This class now extends software.amazon.awssdk.core.exception.SdkException.
3. com.amazonaws.AmazonServiceException changes:
   1. This class has been replaced with software.amazon.awssdk.awscore.exception.AwsServiceException.
   2. This class now extends software.amazon.awssdk.core.exception.SdkServiceException, a new exception type that extends software.amazon.awssdk.core.exception.SdkException.
   3. AmazonServiceException.getRequestId is now SdkServiceException.requestId.
   4. AmazonServiceException.getServiceName is now AwsServiceException.awsErrorDetails().serviceName.
   5. AmazonServiceException.getErrorCode is now AwsServiceException.awsErrorDetails().errorCode.
   6. AmazonServiceException.getErrorMessage is now AwsServiceException.awsErrorDetails().errorMessage.
   7. AmazonServiceException.getStatusCode is now AwsServiceException.awsErrorDetails().sdkHttpResponse().statusCode.
   8. AmazonServiceException.getHttpHeaders is now AwsServiceException.awsErrorDetails().sdkHttpResponse().headers.
   9. AmazonServiceException.rawResponse is now AwsServiceException.awsErrorDetails().rawResponse.
   10. AmazonServiceException.getErrorType is no longer supported.

The S3 client in 2.0 is drastically different from the client in 1.11, because it is now generated from models like every other service.

1. Cross-region access is no longer supported. A client may now only access buckets in the region with which the client has been configured.
2. Anonymous access is disabled by default and must be enabled using the AnonymousCredentialsProvider.

1. An SNS client may no longer access SNS topics in regions different than the one with which the client was configured.

1. An SQS client may no longer access SQS queues in regions different than the one with which the client was configured.

1. The classRdsIamAuthTokenGenerator has been replaced with RdsUtilities#generateAuthenticationToken.

The parsing of the ~/.aws/config and ~/.aws/credentials has changed to more closely emulate that used by the AWS CLI.

1. A ~/ or ~ followed by the file system's default path separator at the start of the path is resolved by checking, in order, $HOME, $USERPROFILE (Windows only), $HOMEDRIVE$HOMEPATH (Windows only), and then the user.home system property.
2. The AWS_CREDENTIAL_PROFILES_FILE environment variable is now AWS_SHARED_CREDENTIALS_FILE.
3. Profile definitions in configuration files without a profile prefix are silently dropped.
4. Profile names that do not consist of alphanumeric, underscore or dash characters are silently dropped (after the profile prefix has been removed for configuration files).
5. Profiles duplicated within the same file have their properties merged.
6. Profiles duplicated in both the configuration and credentials files have their properties merged.
7. If both [profile foo] and [foo] are specified in the same file, their properties are NOT merged.
8. If both [profile foo] and [foo] are specified in the configuration file, [profile foo]'s properties are used.
9. Properties duplicated within the same file and profile use the later property in the file.
10. Both ; and # are supported for defining a comment.
11. In profile definitions, ; and # define a comment, even if they are adjacent to the closing bracket.
12. In property values, ; and # define a comment only if they are preceded by whitespace.
13. In property values, ; and # and all following content are included in the value if they are not preceded by whitespace.
14. Role-based credentials are the highest-priority credentials, and are always used if the user specifies the role_arn property.
15. Session-based credentials are the next-highest-priority credentials, and are always used if role-based credentials were not used and the user specifies the aws_access_key_id and aws_session_token properties.
16. Basic credentials are used if role-based and session-based credentials are not used and the user specified the aws_access_key_id property.

All high-level libraries will be re-designed to match the 2.0 programming model and re-introduced over time. The following libraries are available in 2.0: