Periodic update - 04/11/23-09:41pm UTC

Author: Paul-B-AWS

doc_source/asynchronous.md

@@ -1,9 +1,3 @@
---------
-
-You can now use the [Amazon S3 Transfer Manager \(Developer Preview\)](https://bit.ly/2WQebiP) in the AWS SDK for Java 2\.x for accelerated file transfers\. Give it a try and [let us know what you think](https://bit.ly/3zT1YYM)\!
-
---------
-
 # Asynchronous programming<a name="asynchronous"></a>
 
 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 benefit of nonblocking I/O\.
@@ -288,7 +282,7 @@ public class S3AsyncStreamOps {
 
 ## Advanced operations<a name="advanced-operations"></a>
 
-The AWS SDK for Java 2\.x uses [Netty](https://netty.io), 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, 50 Threads are generated for each asynchronous client, and managed in a queue within the `ExecutorService`\.
+The AWS SDK for Java 2\.x uses [Netty](https://netty.io), 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\.
 
@@ -310,7 +304,7 @@ To optimize performance, you can manage your own thread pool executor, and inclu
 ```
 ThreadPoolExecutor executor = new ThreadPoolExecutor(50, 50,
     10, TimeUnit.SECONDS,
-    new LinkedBlockingQueue<>(10_000),
+    new LinkedBlockingQueue<>(<custom_value>),
     new ThreadFactoryBuilder()
       .threadNamePrefix("sdk-async-response").build());
 

doc_source/best-practices.md

@@ -0,0 +1,85 @@
+# Best practices for AWS SDK for Java 2\.x<a name="best-practices"></a>
+
+This section lists best practices for using the SDK for Java 2\.x\.
+
+**Topics**
++ [Reuse an SDK client, if possible](#bestpractice1)
++ [Close input streams from client operations](#bestpractice2)
++ [Tune HTTP configurations based on performance tests](#bestpractice3)
++ [Use OpenSSL for the Netty\-based HTTP client](#bestpractice4)
++ [Configure API timeouts](#bestpractice5)
++ [Use metrics](#bestpractice6)
+
+## Reuse an SDK client, if possible<a name="bestpractice1"></a>
+
+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 effectively\. 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<a name="bestpractice2"></a>
+
+For streaming operations such as `[S3Client\#getObject](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Client.html#getObject(java.util.function.Consumer,java.nio.file.Path))`, if you are working with `[ResponseInputStream](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/ResponseInputStream.html)` directly, we recommend that you do the following:
++ 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 configurations based on performance tests<a name="bestpractice3"></a>
+
+The SDK provides a set of [default http configurations](https://github.com/aws/aws-sdk-java-v2/blob/master/http-client-spi/src/main/java/software/amazon/awssdk/http/SdkHttpConfigurationOption.java) that apply to general use cases\. We recommend that customers tune HTTP configurations for their applications based on their use cases\. 
+
+As a good starting point, the SDK offers a [smart configuration defaults](http-configuration.md#http-config-smart-defaults) feature\. This feature is available starting with version 2\.17\.102\. You choose a mode depending on your use case, which provides sensible configuration values\. 
+
+## Use OpenSSL for the Netty\-based HTTP client<a name="bestpractice4"></a>
+
+By default, the SDK's [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) 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](https://netty.io/wiki/requirements-for-4.x.html#tls-with-openssl)\. 
+
+To use OpenSSL, add `netty-tcnative` to your dependencies\. For configuration details, see the [Netty project documentation](https://netty.io/wiki/forked-tomcat-native.html)\.
+
+After you have `netty-tcnative` configured 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();
+```
+
+## Configure API timeouts<a name="bestpractice5"></a>
+
+The SDK provides [default values](https://github.com/aws/aws-sdk-java-v2/blob/a0c8a0af1fa572b16b5bd78f310594d642324156/http-client-spi/src/main/java/software/amazon/awssdk/http/SdkHttpConfigurationOption.java#L134) 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 configure timeouts for all requests made by a service clients using `[ClientOverrideConfiguration\#apiCallAttemptTimeout](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.html#apiCallAttemptTimeout())` and `[ClientOverrideConfiguration\#apiCallTimeout](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.html#apiCallTimeout())`\.
+
+The following example shows the configuration 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();
+```
+
+**`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 configures 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 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/RequestOverrideConfiguration.html#apiCallTimeout()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/RequestOverrideConfiguration.html#apiCallTimeout()) and `[RequestOverrideConfiguration\#apiCallAttemptTimeout\(\)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/RequestOverrideConfiguration.html#apiCallAttemptTimeout())` to configure a single request \.
+
+The following example configures 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<a name="bestpractice6"></a>
+
+The SDK for Java can [collect metrics](metrics.md) 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\.

doc_source/compliance-validation.md

@@ -0,0 +1,16 @@
+# Compliance Validation for this AWS Product or Service<a name="compliance-validation"></a>
+
+This AWS product or service follows the [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) through the specific Amazon Web Services \(AWS\) services it supports\. For AWS service security information, see the [AWS service security documentation page](https://docs.aws.amazon.com/security/?id=docs_gateway#aws-security) and [AWS services that are in scope of AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/)\.
+
+The security and compliance of AWS services is assessed by third\-party auditors as part of multiple AWS compliance programs\. These include SOC, PCI, FedRAMP, HIPAA, and others\. AWS provides a frequently updated list of AWS services in scope of specific compliance programs at [AWS Services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/)\.
+
+Third\-party audit reports are available for you to download using AWS Artifact\. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html)\.
+
+For more information about AWS compliance programs, see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/)\.
+
+Your compliance responsibility when using this AWS product or service to access an AWS service is determined by the sensitivity of your data, your organization’s compliance objectives, and applicable laws and regulations\. If your use of an AWS service is subject to compliance with standards such as HIPAA, PCI, or FedRAMP, AWS provides resources to help:
++ [Security and Compliance Quick Start Guides](https://aws.amazon.com/quickstart/?quickstart-all.sort-by=item.additionalFields.updateDate&quickstart-all.sort-order=desc&awsf.quickstart-homepage-filter=categories%23security-identity-compliance) – Deployment guides that discuss architectural considerations and provide steps for deploying security\-focused and compliance\-focused baseline environments on AWS\. 
++ [Architecting for HIPAA Security and Compliance Whitepaper](https://d0.awsstatic.com/whitepapers/compliance/AWS_HIPAA_Compliance_Whitepaper.pdf) – A whitepaper that describes how companies can use AWS to create HIPAA\-compliant applications\. 
++ [AWS Compliance Resources](https://aws.amazon.com/compliance/resources/) – A collection of workbooks and guides that might apply to your industry and location\. 
++ [AWS Config](https://aws.amazon.com/config/) – A service that assesses how well your resource configurations comply with internal practices, industry guidelines, and regulations\. 
++ [AWS Security Hub](https://aws.amazon.com/security-hub/) – A comprehensive view of your security state within AWS that helps you check your compliance with security industry standards and best practices\. 

doc_source/credentials-chain.md

@@ -0,0 +1,41 @@
+# Default credentials provider chain<a name="credentials-chain"></a>
+
+The default credentials provider chain is implemented by the [DefaultCredentialsProvider](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html) class\. It sequentially checks each place where you can set the default configuration for supplying temporary credentials, and then selects the first 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 configuration settings\.
+
+```
+Region region = Region.US_WEST_2;
+DynamoDbClient ddb = 
+    DynamoDbEnhancedClient.builder()
+                          .region(region)
+                          .build();
+```
+
+## Credential settings retrieval order<a name="credentials-default"></a>
+
+The default credentials provider chain of the SDK for Java 2\.x searches for configuration in your environment using a predefined sequence\.
+
+1. Java system properties
+   + The SDK uses the [SystemPropertyCredentialsProvider](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/SystemPropertyCredentialsProvider.html) 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](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) tutorial on the official *Java Tutorials* website\.
+
+1. Environment variables
+   + The SDK uses the [EnvironmentVariableCredentialsProvider](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/EnvironmentVariableCredentialsProvider.html) class to load temporary credentials from the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables\.
+
+1. Web identity token from AWS Security Token Service
+   + The SDK uses the [WebIdentityTokenFileCredentialsProvider](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/WebIdentityTokenFileCredentialsProvider.html) class to load temporary credentials from Java system properties or environment variables\.
+
+1. The shared `credentials` and `config` files
+   + The SDK uses the [ProfileCredentialsProvider](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html) to load IAM Identity Center single sign\-on settings or temporary credentials from the `[default]` profile in the shared `credentials` and `config` files\. 
+
+     The AWS SDKs and Tools Reference Guide has [detailed information](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html#idccredres) 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` files are shared by various AWS SDKs and Tools\. For more information, see [The \.aws/credentials and \.aws/config files](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) in the AWS SDKs and Tools Reference Guide\.
+
+1.  Amazon ECS container credentials
+   + The SDK uses the [ContainerCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ContainerCredentialsProvider.html) class to load temporary credentials from the `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` system environment variable\.
+
+1.  Amazon EC2 instance IAM role\-provided credentials
+   + The SDK uses the [InstanceProfileCredentialsProvider](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/InstanceProfileCredentialsProvider.html) class to load temporary credentials from the Amazon EC2 metadata service\.

doc_source/credentials-explicit.md

@@ -0,0 +1,51 @@
+# Supply temporary credentials in code<a name="credentials-explicit"></a>
+
+If the default credential chain or a specific 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](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html) as[ described above](credentials-temporary.md#credentials-temporary-from-portal) 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. Instantiate a class that provides the [AwsCredentials](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/AwsCredentials.html) interface, such as [AwsSessionCredentials](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/AwsSessionCredentials.html)\. Supply it with the AWS access keys and session token to use for the connection\.
+
+1. Create a [StaticCredentialsProvider](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/auth/credentials/StaticCredentialsProvider.html) object and supply it with the `AwsSessionCredentials` object\.
+
+1. Configure the service client builder with the `StaticCredentialsProvider` and build the client\.
+
+The following example creates an Amazon S3 service client using temporary credentials that you supply\.
+
+```
+public static void assumeRole(String roleArn, String roleSessionName) {
+    // The IAM role represented by the roleArn parameter can be assumed by any user in the same account
+    // and has read-only permissions when it accesses Amazon S3.
+
+    // The default credentials provider chain will find the single sign-on settings in the [default] profile.
+    StsClient stsClient = StsClient.builder()
+            .region(Region.US_EAST_1)
+            .build();
+    try {
+        AssumeRoleRequest roleRequest = AssumeRoleRequest.builder()
+                .roleArn(roleArn)
+                .roleSessionName(roleSessionName)
+                .build();
+
+        AssumeRoleResponse roleResponse = stsClient.assumeRole(roleRequest);
+        Credentials tempRoleCredentials = roleResponse.credentials();
+        // The following temporary credential items are used when Amazon S3 is called
+        String key = tempRoleCredentials.accessKeyId();
+        String secKey = tempRoleCredentials.secretAccessKey();
+        String secToken = tempRoleCredentials.sessionToken();
+
+        // List all buckets in the account using the temporary credentials retrieved by invoking assumeRole.
+        Region region = Region.US_EAST_1;
+        S3Client s3 = S3Client.builder()
+                .credentialsProvider(StaticCredentialsProvider.create(AwsSessionCredentials.create(key, secKey, secToken)))
+                .region(region)
+                .build();
+
+        List<Bucket> buckets = s3.listBuckets().buckets();
+        for (Bucket bucket : buckets) {
+            System.out.println("bucket name: " + bucket.name());
+        }
+    } catch (StsException e) {
+        System.err.println(e.getMessage());
+        System.exit(1);
+    }
+}
+```