xref: /aosp_15_r20/external/aws-sdk-java-v2/docs/BestPractices.md (revision 8a52c7834d808308836a99fc2a6e0ed8db339086) 
1##  AWS Java SDK 2.x Best Practices
2
3Here are the best practices of using AWS Java SDK 2.x.
4
5### Reuse SDK client if possible
6
7Each SDK client maintains its own HTTP connection pool so that connections can be reused by a new request
8to cut down the time to establish a new connection. It is recommended to share a single instance of the client to
9avoid the overhead of having too many connection pools that are not being utilized effectively. All SDK clients are thread safe.
10
11If it is not desirable to share a client instance, invoke `client.close()` to release the resources once the client is not needed.
12
13### Close input streams from client operations
14
15For streaming operations such as `S3Client#getObject`,  if you are working with `ResponseInputStream` directly, we have the following recommendations:
16
17- Read all the data from the input stream as soon as possible
18- Close the input stream as soon as possible
19
20This is because the input stream is a direct stream of data from the HTTP connection and the underlying HTTP connection cannot be
21reused until all data from the stream has been read and the stream is closed. If these rules are not followed, the client can
22run out of resources by allocating too many open, but unused, HTTP connections.
23
24### Close input streams of responseBody() from Custom Client based on SdkHttpClient
25While implementing custom clients from  `SdkHttpClient` interface
26- Close the [responseBody](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/HttpExecuteResponse.html#responseBody()) Input Stream: Always close the "responseBody" input stream to release the HTTP Connection, even when handling error responses.
27- SDK Requirement: The SDK requires the closing of the input stream to manage HTTP connections effectively.
28- Handling Error Responses: Even in the case of error responses, the SDK client creates an input stream for reading error data.
29- Consistent Practice: Ensure that consumers close the input stream in the "responseBody" attribute for both success and error cases.
30
31### Tune HTTP configurations based on performance tests
32
33The SDK provides a set of [default http configurations] that apply to general use cases. Customers are recommended to tune the configurations for their applications based on their use cases.
34
35### Use OpenSSL for Netty async client
36
37By default, `NettyNioAsyncHttpClient` uses JDK as the SslProvider. In our local tests, we found that using `OpenSSL`
38is more performant than JDK. Using OpenSSL is also the recommended approach by Netty community, see [Netty TLS with OpenSSL].
39Note that you need to add `netty-tcnative` to your dependency in order to use OpenSSL, see [Configuring netty-tcnative]
40
41Once you have `netty-tcnative` configured correctly, `NettyAsyncHttpClient` will select OpenSSL automatically, or you can set the
42`SslProvider` explicitly on the NettyNioAsyncHttpClient builder.
43
44```
45   NettyNioAsyncHttpClient.builder()
46                          .sslProvider(SslProvider.OPENSSL)
47                          .build();
48```
49
50### Utilize timeout configurations
51
52The SDK provides timeout configurations on requests out of box and they can be configured via `ClientOverrideConfiguration#apiCallAttemptTimeout` and `ClientOverrideConfiguration#ApiCallTimeout`.
53
54```java
55  S3Client.builder()
56          .overrideConfiguration(b -> b.apiCallTimeout(Duration.ofMillis(API_CALL_TIMEOUT))
57                                       .apiCallAttemptTimeout(Duration.ofMillis(API_CALL_ATTEMPT_TIMEOUT))
58          .build();
59```
60
61- `ApiCallAttemptTimeout` tracks the amount of time for a single http attempt and the request can be retried if timed out on api call attempt.
62- `ApiCallTimeout` configures the amount of time for the entire execution including all retry attempts.
63
64By default, timeouts are disabled. Using them together is helpful to set a hard limit on total time spent on all attempts across retries and each individual HTTP request to fail fast on one slow request.
65
66[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
67[Netty TLS with OpenSSL]: https://netty.io/wiki/requirements-for-4.x.html#tls-with-openssl
68[Configuring netty-tcnative]: https://netty.io/wiki/forked-tomcat-native.html