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;
17 
18 import software.amazon.awssdk.annotations.Immutable;
19 import software.amazon.awssdk.annotations.SdkPublicApi;
20 import software.amazon.awssdk.annotations.ThreadSafe;
21 import software.amazon.awssdk.utils.AttributeMap;
22 import software.amazon.awssdk.utils.SdkAutoCloseable;
23 import software.amazon.awssdk.utils.builder.SdkBuilder;
24 
25 /**
26  * Interface to take a representation of an HTTP request, make an HTTP call, and return a representation of an HTTP response.
27  *
28  * <p>Implementations MUST be thread safe.</p>
29  */
30 @Immutable
31 @ThreadSafe
32 @SdkPublicApi
33 public interface SdkHttpClient extends SdkAutoCloseable {
34 
35     /**
36      * Create a {@link ExecutableHttpRequest} that can be used to execute the HTTP request.
37      *
38      * @param request        Representation of an HTTP request.
39      * @return Task that can execute an HTTP request and can be aborted.
40      */
prepareRequest(HttpExecuteRequest request)41     ExecutableHttpRequest prepareRequest(HttpExecuteRequest request);
42 
43     /**
44      * Each HTTP client implementation should return a well-formed client name
45      * that allows requests to be identifiable back to the client that made the request.
46      * The client name should include the backing implementation as well as the Sync or Async
47      * to identify the transmission type of the request. Client names should only include
48      * alphanumeric characters. Examples of well formed client names include, ApacheSync, for
49      * requests using Apache's synchronous http client or NettyNioAsync for Netty's asynchronous
50      * http client.
51      *
52      * @return String containing the name of the client
53      */
clientName()54     default String clientName() {
55         return "UNKNOWN";
56     }
57 
58     /**
59      * Interface for creating an {@link SdkHttpClient} with service specific defaults applied.
60      */
61     @FunctionalInterface
62     interface Builder<T extends SdkHttpClient.Builder<T>> extends SdkBuilder<T, SdkHttpClient> {
63         /**
64          * Create a {@link SdkHttpClient} with global defaults applied. This is useful for reusing an HTTP client across multiple
65          * services.
66          */
67         @Override
build()68         default SdkHttpClient build() {
69             return buildWithDefaults(AttributeMap.empty());
70         }
71 
72         /**
73          * Create an {@link SdkHttpClient} with service specific defaults and defaults from {@code DefaultsMode} applied.
74          * Applying service defaults is optional and some options may not be supported by a particular implementation.
75          *
76          * @param serviceDefaults Service specific defaults. Keys will be one of the constants defined in
77          *                        {@link SdkHttpConfigurationOption}.
78          * @return Created client
79          */
buildWithDefaults(AttributeMap serviceDefaults)80         SdkHttpClient buildWithDefaults(AttributeMap serviceDefaults);
81     }
82 }
83