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