• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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.core.http;
17 
18 import java.util.Collections;
19 import java.util.Set;
20 import java.util.stream.Collectors;
21 import java.util.stream.Stream;
22 import software.amazon.awssdk.annotations.SdkProtectedApi;
23 import software.amazon.awssdk.core.interceptor.ExecutionAttributes;
24 import software.amazon.awssdk.http.SdkHttpFullResponse;
25 
26 /**
27  * Responsible for handling an HTTP response and returning an object of type T.
28  * For example, a typical response handler might accept a response, and
29  * translate it into a concrete typed object.
30  *
31  * @param <T>
32  *            The output of this response handler.
33  */
34 @SdkProtectedApi
35 @FunctionalInterface
36 public interface HttpResponseHandler<T> {
37     String X_AMZN_REQUEST_ID_HEADER = "x-amzn-RequestId";
38     String X_AMZN_REQUEST_ID_HEADER_ALTERNATE = "x-amz-request-id";
39     Set<String> X_AMZN_REQUEST_ID_HEADERS = Collections.unmodifiableSet(Stream.of(X_AMZN_REQUEST_ID_HEADER,
40                                                                                   X_AMZN_REQUEST_ID_HEADER_ALTERNATE)
41                                                                               .collect(Collectors.toSet()));
42     String X_AMZ_ID_2_HEADER = "x-amz-id-2";
43 
44     /**
45      * Accepts an HTTP response object, and returns an object of type T.
46      * Individual implementations may choose to handle the response however they
47      * need to, and return any type that they need to.
48      *
49      * @param response The HTTP response to handle, as received from an AWS service.
50      * @param executionAttributes The attributes attached to this particular execution.
51      * @return An object of type T, as defined by individual implementations.
52      *
53      * @throws Exception
54      *             If any problems are encountered handling the response.
55      */
handle(SdkHttpFullResponse response, ExecutionAttributes executionAttributes)56     T handle(SdkHttpFullResponse response, ExecutionAttributes executionAttributes) throws Exception;
57 
58     /**
59      * Indicates if this response handler requires that the underlying HTTP
60      * connection <b>not</b> be closed automatically after the response is
61      * handled.
62      * <p>
63      * For example, if the object returned by this response handler manually
64      * manages the stream of data from the HTTP connection, and doesn't read all
65      * the data from the connection in the {@link #handle(SdkHttpFullResponse, ExecutionAttributes)} method,
66      * this method can be used to prevent the underlying connection from being
67      * prematurely closed.
68      * <p>
69      * Response handlers should use this option very carefully, since it means
70      * that resource cleanup is no longer handled automatically, and if
71      * neglected, can result in the client runtime running out of resources for
72      * new HTTP connections.
73      *
74      * @return True if this response handler requires that the underlying HTTP
75      *         connection be left open, and not automatically closed, otherwise
76      *         false.
77      */
needsConnectionLeftOpen()78     default boolean needsConnectionLeftOpen() {
79         return false;
80     }
81 }
82