Introducing Smart Configuration Defaults in the Amazon SDK for Java v2

{"value":"The default configuration in the [AWS SDK for Java v2](https://github.com/aws/aws-sdk-java-v2/) just got smarter! We are pleased to announce a new SDK feature —⁠ [smart configuration defaults](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html) 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.\n\n\n#### **What is smart configuration defaults?**\n\nThe 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.\n\nThe 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.\n\nTo enable smart configuration defaults feature, you simply need to replace the default ```legacy``` value with the one that fits your use-case.\n\n#### How to configure the defaults mode?\n\nYou can configure this feature in several ways.\n\n##### **Option 1: Service client builder**\n\nYou 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```\n\nJava\n```\nS3Client s3Client = S3Client.builder()\n .defaultsMode(DefaultsMode.AUTO)\n .build();\n```\n\n##### **Option 2: System property**\n\nYou 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.\n\nJava\n```\nSystem.setProperty(\"aws.defaultsMode\", \"auto\");\n```\n\n##### **Option 3: Environment variable**\n\nYou 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.\n\nBash\n```\nexport AWS_DEFAULTS_MODE=auto\n```\n\n##### **Option 4: AWS config file**\n\nLastly, you can add ```defaults_mode``` in your AWS config file.\n\n```\n[default]\ndefaults_mode = auto\n```\n##### **Which defaults mode to choose?**\n\nNow 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.\n\n- **standard** – provides the default values according to the latest AWS SDK recommended practices that should be safe to run in most scenarios.\n- **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.\n- **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.\n- **mobile** – builds on the ```standard``` mode and is further optimized for mobile applications.\n- **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.\n\nAll 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html), which may introduce latency in some scenarios. If your application is sensitive to startup latency, we recommend choosing one of the static default modes.\n\nTo determine which mode to select, you can use the following flowchart as a guideline.\n\n\n\n#### **What configuration options are optimized?**\n\nLet’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](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html).\n\n- **retryMode**: Specifies how the SDK attempts retries. See [RetryMode](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryMode.html).\n- **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](AWS_S3_US_EAST_1_REGIONAL_ENDPOINT)\n- **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 ](NettyNioAsyncHttpClient.Builder#connectionTimeout) \n- **tlsNegotiationTimeoutInMillis**: The maximum amount of time that a TLS handshake is allowed to take from the time the CLIENT HELLO message is sentto the time the client and server have fully negotiated ciphers and exchangedkeys.See [NettyNioAsyncHttpClient.Builder#tlsNegotiationTimeout](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.Builder.html#tlsNegotiationTimeout-java.time.Duration-)\n\nAny 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.\n\nPlease 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.\n\n### **Conclusion**\n\nWe 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](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html). 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](https://github.com/aws/aws-sdk-java-v2/issues).\n\n\n\n\n### **[Zoe Wang](https://github.com/zoewangg)**\nZoe is a Software Development Engineer working on the AWS SDK for Java. She is passionate about building tools to improve the developer experience. You can find her on GitHub **@zoewangg**.","render":"<p>The default configuration in the <a href=\"https://github.com/aws/aws-sdk-java-v2/\" target=\"_blank\">AWS SDK for Java v2</a> just got smarter! We are pleased to announce a new SDK feature —⁠ <a href=\"https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html\" target=\"_blank\">smart configuration defaults</a> 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.</p>\n<h4><a id=\"What_is_smart_configuration_defaults_3\"></a><strong>What is smart configuration defaults?</strong></h4>\n<p>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.</p>\n<p>The SDK supports six defaults modes: <code>legacy</code>, <code>standard</code>, <code>in-region</code>, <code>cross-region</code>, <code>mobile</code> and <code>auto</code>. We will explain each mode in detail in a later section.</p>\n<p>To enable smart configuration defaults feature, you simply need to replace the default <code>legacy</code> value with the one that fits your use-case.</p>\n<h4><a id=\"How_to_configure_the_defaults_mode_11\"></a>How to configure the defaults mode?</h4>\n<p>You can configure this feature in several ways.</p>\n<h5><a id=\"Option_1_Service_client_builder_15\"></a><strong>Option 1: Service client builder</strong></h5>\n<p>You can configure the defaults mode on a SDK client via the service client builder directly. Below is the sample code to configure <code>auto</code> defaults mode on an <code>S3Client</code></p>\n<p>Java</p>\n<pre><code class=\"lang-\">S3Client s3Client = S3Client.builder()\n .defaultsMode(DefaultsMode.AUTO)\n .build();\n</code></pre>\n<h5><a id=\"Option_2_System_property_26\"></a><strong>Option 2: System property</strong></h5>\n<p>You can specify defaults mode using the system property <code>aws.defaultsMode</code>. The system property has to be set before the SDK client initialization to take effect.</p>\n<p>Java</p>\n<pre><code class=\"lang-\">System.setProperty(&quot;aws.defaultsMode&quot;, &quot;auto&quot;);\n</code></pre>\n<h5><a id=\"Option_3_Environment_variable_35\"></a><strong>Option 3: Environment variable</strong></h5>\n<p>You can set the environment variable <code>AWS_DEFAULTS_MODE</code> 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.</p>\n<p>Bash</p>\n<pre><code class=\"lang-\">export AWS_DEFAULTS_MODE=auto\n</code></pre>\n<h5><a id=\"Option_4_AWS_config_file_44\"></a><strong>Option 4: AWS config file</strong></h5>\n<p>Lastly, you can add <code>defaults_mode</code> in your AWS config file.</p>\n<pre><code class=\"lang-\">[default]\ndefaults_mode = auto\n</code></pre>\n<h5><a id=\"Which_defaults_mode_to_choose_52\"></a><strong>Which defaults mode to choose?</strong></h5>\n<p>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.</p>\n<ul>\n<li><strong>standard</strong> – provides the default values according to the latest AWS SDK recommended practices that should be safe to run in most scenarios.</li>\n<li><strong>in-region</strong> – builds on the <code>standard</code> 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.</li>\n<li><strong>cross-region</strong> – builds on the <code>standard</code> 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.</li>\n<li><strong>mobile</strong> – builds on the <code>standard</code> mode and is further optimized for mobile applications.</li>\n<li><strong>auto</strong> – 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.</li>\n</ul>\n<p>All the modes except <code>auto</code> mode are static defaults modes, which means the optimized configuration defaults are determined at compile time. <code>auto</code> 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 <code>standard</code> mode will be used. The auto detection might query <a href=\"https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html\" target=\"_blank\">EC2 Instance metadata and user data</a>, which may introduce latency in some scenarios. If your application is sensitive to startup latency, we recommend choosing one of the static default modes.</p>\n<p>To determine which mode to select, you can use the following flowchart as a guideline.</p>\n<p><img src=\"https://dev-media.amazoncloud.cn/87f606bd33544b84ad94278e8bb7e409_image.png\" alt=\"image.png\" /></p>\n<h4><a id=\"What_configuration_options_are_optimized_68\"></a><strong>What configuration options are optimized?</strong></h4>\n<p>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 <a href=\"https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html\" target=\"_blank\">AWS SDKs and Tools Reference Guide</a>.</p>\n<ul>\n<li><strong>retryMode</strong>: Specifies how the SDK attempts retries. See <a href=\"https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryMode.html\" target=\"_blank\">RetryMode</a>.</li>\n<li><strong>s3UsEast1RegionalEndpoints</strong>: 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 <a href=\"AWS_S3_US_EAST_1_REGIONAL_ENDPOINT\" target=\"_blank\">AWS_S3_US_EAST_1_REGIONAL_ENDPOINT</a></li>\n<li><strong>connectTimeoutInMillis</strong>: 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 <a href=\"NettyNioAsyncHttpClient.Builder#connectionTimeout\" target=\"_blank\">NettyNioAsyncHttpClient.Builder#connectionTimeout </a></li>\n<li><strong>tlsNegotiationTimeoutInMillis</strong>: The maximum amount of time that a TLS handshake is allowed to take from the time the CLIENT HELLO message is sentto the time the client and server have fully negotiated ciphers and exchangedkeys.See <a href=\"https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.Builder.html#tlsNegotiationTimeout-java.time.Duration-\" target=\"_blank\">NettyNioAsyncHttpClient.Builder#tlsNegotiationTimeout</a></li>\n</ul>\n<p>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.</p>\n<p>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.</p>\n<h3><a id=\"Conclusion_81\"></a><strong>Conclusion</strong></h3>\n<p>We hope this addition makes configuring the AWS SDK for Java v2 even easier! You can learn more from the <a href=\"https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html\" target=\"_blank\">AWS SDKs and Tools Reference Guide</a>. 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 <a href=\"https://github.com/aws/aws-sdk-java-v2/issues\" target=\"_blank\">GitHub issue</a>.</p>\n<p><img src=\"https://dev-media.amazoncloud.cn/9eaa9b5b2d034baf89824576049cd4ff_image.png\" alt=\"image.png\" /></p>\n<h3><a id=\"Zoe_Wanghttpsgithubcomzoewangg_88\"></a><strong><a href=\"https://github.com/zoewangg\" target=\"_blank\">Zoe Wang</a></strong></h3>\n<p>Zoe is a Software Development Engineer working on the AWS SDK for Java. She is passionate about building tools to improve the developer experience. You can find her on GitHub <strong>@zoewangg</strong>.</p>\n"}