Introducing Smart Configuration Defaults in the AWS SDK for Java v2

The default configuration in the AWS SDK for Java v2 just got smarter! We are pleased to announce a new SDK feature —⁠ smart configuration defaults in the AWS SDK for Java v2 (version 2.17.102 or later), which vends a set of predefined sensible default values tailored to common usage patterns. With this new opt-in feature, you will get an optimized SDK client out-of-box with configuration already tuned to adhere to AWS SDK best practices. This feature is also available in the AWS SDK for .NET, JavaScript v3, Ruby v3, Go v2 , Python and PHP. In this post, we will explain the feature and show you how to leverage it in the AWS SDK for Java v2.

What is smart configuration defaults?

The AWS SDK for Java v2 exposes different optional configuration settings, such as retry policy and connect timeout, and it provides default values if they are not configured. The smart configuration defaults offers enhanced default values for those settings based on the usage scenarios. This feature can be enabled via a setting called defaults mode, which determines how the default values should be resolved.

The SDK supports six defaults modes: legacy, standard, in-region, cross-region, mobile and auto. We will explain each mode in detail in a later section.

To enable smart configuration defaults feature, you simply need to replace the default legacy value with the one that fits your use-case.

How to configure the defaults mode?

You can configure this feature in several ways.

Option 1: Service client builder
You can configure the defaults mode on a SDK client via the service client builder directly. Below is the sample code to configure auto defaults mode on an S3Client

S3Client s3Client = S3Client.builder()
                            .defaultsMode(DefaultsMode.AUTO)
                            .build();

Option 2: System property

You can specify defaults mode using the system property aws.defaultsMode. The system property has to be set before the SDK client initialization to take effect.

System.setProperty("aws.defaultsMode", "auto");

Option 3: Environment variable

You can set the environment variable AWS_DEFAULTS_MODE to the mode you want to choose. Similar to the option above, the environment variable has to be set before the SDK client initialization to take effect.

export AWS_DEFAULTS_MODE=auto

Option 4: AWS config file

Lastly, you can add defaults_mode in your AWS config file.

[default]
defaults_mode = auto

Which defaults mode to choose?

Now that we know how to configure the defaults mode, let’s find out which one to choose for your application. Here are the defaults mode supported in the SDK.

standard – provides the default values according to the latest AWS SDK recommended practices that should be safe to run in most scenarios.
in-region – builds on the standard mode and further improves the SDK client resilience for in-region API requests. It is tailored for applications that call AWS services from within the same AWS region. For example, if your application is running in us-east-1 and only sending requests to an AWS service in us-east-1, then this is the right defaults mode.
cross-region – builds on the standard mode and further improves SDK client resilience for cross-region API requests. It is tailored for applications which call AWS services in a different region. For example, if your application is running in us-west-2 and making requests to AWS services in us-east-1, then this is the right defaults mode.
mobile – builds on the standard mode and is further optimized for mobile applications.
auto – the SDK first attempts to discover the execution environment, e.g. check if the application is running on mobile or if the SDK client makes cross-region call, and it then provides default values accordingly. Note that auto detection is heuristics-based, and thus 100% accuracy is not guaranteed.

All the modes except auto mode are static defaults modes, which means the optimized configuration defaults are determined at compile time. auto mode, on the other hand, is dynamic as it will attempt to inspect the execution environment to determine the right static defaults mode to apply at runtime. If the runtime environment can’t be determined, the values from standard mode will be used. The auto detection might query EC2 Instance metadata and user data, which may introduce latency in some scenarios. If your application is sensitive to startup latency, we recommend choosing one of the static default modes.

To determine which mode to select, you can use the following flowchart as a guideline.

What configuration options are optimized?

Let’s take a look at the settings that are optimized by a given mode. You can check out the values for each mode in our AWS SDKs and Tools Reference Guide.

retryMode: Specifies how the SDK attempts retries. See RetryMode.
s3UsEast1RegionalEndpoints: Specifies how the SDK determines the AWS service endpoint that it uses to talk to the Amazon S3 for the us-east-1 region. See AWS_S3_US_EAST_1_REGIONAL_ENDPOINT
connectTimeoutInMillis: The amount of time after making an initial connection attempt on a socket, where if the client does not receive a completion of the connect handshake, the client gives up and fails the operation. See NettyNioAsyncHttpClient.Builder#connectionTimeout
tlsNegotiationTimeoutInMillis: The maximum amount of time that a TLS handshake is allowed to take from the time the CLIENT HELLO message is sent to the time the client and server have fully negotiated ciphers and exchanged keys. See NettyNioAsyncHttpClient.Builder#tlsNegotiationTimeout

Any value that you configure explicitly on the SDK client will always take precedence over smart configuration default values. For example, if you have already set the SDK client with connect timeout of 2 seconds , the defaults mode will NOT override it.

Please note that default values set by this feature might change as the SDK best practices evolve, therefore we recommend that you test your application thoroughly whenever you upgrade the SDK.

Conclusion

We hope this addition makes configuring the AWS SDK for Java v2 even easier! You can learn more from the AWS SDKs and Tools Reference Guide. We would love your feedback on this feature and as well as any other improvements you would like to see implemented in the future. Please let us know by opening a GitHub issue.