1 /*
2  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License").
5  * You may not use this file except in compliance with the License.
6  * A copy of the License is located at
7  *
8  *  http://aws.amazon.com/apache2.0
9  *
10  * or in the "license" file accompanying this file. This file is distributed
11  * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12  * express or implied. See the License for the specific language governing
13  * permissions and limitations under the License.
14  */
15 
16 package software.amazon.awssdk.http.async;
17 
18 import java.util.concurrent.CompletableFuture;
19 import software.amazon.awssdk.annotations.Immutable;
20 import software.amazon.awssdk.annotations.SdkPublicApi;
21 import software.amazon.awssdk.annotations.ThreadSafe;
22 import software.amazon.awssdk.http.SdkHttpConfigurationOption;
23 import software.amazon.awssdk.utils.AttributeMap;
24 import software.amazon.awssdk.utils.SdkAutoCloseable;
25 import software.amazon.awssdk.utils.builder.SdkBuilder;
26 
27 /**
28 * Interface to take a representation of an HTTP request, asynchronously make an HTTP call, and return a representation of an
29 * HTTP response.
30 *
31 * <p>Implementations MUST be thread safe.</p>
32 */
33 @Immutable
34 @ThreadSafe
35 @SdkPublicApi
36 public interface SdkAsyncHttpClient extends SdkAutoCloseable {
37 
38     /**
39      * Execute the request.
40      *
41      * @param request The request object.
42      *
43      * @return The future holding the result of the request execution. Upon success execution of the request, the future is
44      * completed with {@code null}, otherwise it is completed exceptionally.
45      */
execute(AsyncExecuteRequest request)46     CompletableFuture<Void> execute(AsyncExecuteRequest request);
47 
48     /**
49      * Each HTTP client implementation should return a well-formed client name
50      * that allows requests to be identifiable back to the client that made the request.
51      * The client name should include the backing implementation as well as the Sync or Async
52      * to identify the transmission type of the request. Client names should only include
53      * alphanumeric characters. Examples of well formed client names include, Apache, for
54      * requests using Apache's http client or NettyNio for Netty's http client.
55      *
56      * @return String containing the name of the client
57      */
clientName()58     default String clientName() {
59         return "UNKNOWN";
60     }
61 
62     @FunctionalInterface
63     interface Builder<T extends SdkAsyncHttpClient.Builder<T>> extends SdkBuilder<T, SdkAsyncHttpClient> {
64         /**
65          * Create a {@link SdkAsyncHttpClient} with global defaults applied. This is useful for reusing an HTTP client across
66          * multiple services.
67          */
68         @Override
build()69         default SdkAsyncHttpClient build() {
70             return buildWithDefaults(AttributeMap.empty());
71         }
72 
73         /**
74          * Create an {@link SdkAsyncHttpClient} with service specific defaults applied. Applying service defaults is optional
75          * and some options may not be supported by a particular implementation.
76          *
77          * @param serviceDefaults Service specific defaults. Keys will be one of the constants defined in {@link
78          *                        SdkHttpConfigurationOption}.
79          * @return Created client
80          */
buildWithDefaults(AttributeMap serviceDefaults)81         SdkAsyncHttpClient buildWithDefaults(AttributeMap serviceDefaults);
82     }
83 }
84