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 static java.util.Collections.singletonList; 19 20 import java.io.Serializable; 21 import java.util.List; 22 import java.util.Map; 23 import java.util.Optional; 24 import software.amazon.awssdk.annotations.Immutable; 25 import software.amazon.awssdk.annotations.SdkPublicApi; 26 import software.amazon.awssdk.utils.builder.CopyableBuilder; 27 import software.amazon.awssdk.utils.builder.ToCopyableBuilder; 28 29 /** 30 * An immutable HTTP response without access to the response body. {@link SdkHttpFullResponse} should be used when access to a 31 * response body stream is required. 32 */ 33 @SdkPublicApi 34 @Immutable 35 public interface SdkHttpResponse extends ToCopyableBuilder<SdkHttpResponse.Builder, SdkHttpResponse>, 36 SdkHttpHeaders, Serializable { 37 38 /** 39 * @return Builder instance to construct a {@link DefaultSdkHttpFullResponse}. 40 */ builder()41 static SdkHttpFullResponse.Builder builder() { 42 return new DefaultSdkHttpFullResponse.Builder(); 43 } 44 45 /** 46 * Returns the HTTP status text returned by the service. 47 * 48 * <p>If this was not provided by the service, empty will be returned.</p> 49 */ statusText()50 Optional<String> statusText(); 51 52 /** 53 * Returns the HTTP status code (eg. 200, 404, etc.) returned by the service. 54 * 55 * <p>This will always be positive.</p> 56 */ statusCode()57 int statusCode(); 58 59 /** 60 * If we get back any 2xx status code, then we know we should treat the service call as successful. 61 */ isSuccessful()62 default boolean isSuccessful() { 63 return HttpStatusFamily.of(statusCode()) == HttpStatusFamily.SUCCESSFUL; 64 } 65 66 /** 67 * Builder for a {@link DefaultSdkHttpFullResponse}. 68 */ 69 interface Builder extends CopyableBuilder<Builder, SdkHttpResponse>, SdkHttpHeaders { 70 /** 71 * The status text, exactly as it was configured with {@link #statusText(String)}. 72 */ statusText()73 String statusText(); 74 75 /** 76 * Configure an {@link SdkHttpResponse#statusText()} to be used in the created HTTP response. This is not validated 77 * until the http response is created. 78 */ statusText(String statusText)79 Builder statusText(String statusText); 80 81 /** 82 * The status text, exactly as it was configured with {@link #statusCode(int)}. 83 */ statusCode()84 int statusCode(); 85 86 /** 87 * Configure an {@link SdkHttpResponse#statusCode()} to be used in the created HTTP response. This is not validated 88 * until the http response is created. 89 */ statusCode(int statusCode)90 Builder statusCode(int statusCode); 91 92 /** 93 * The HTTP headers, exactly as they were configured with {@link #headers(Map)}, 94 * {@link #putHeader(String, String)} and {@link #putHeader(String, List)}. 95 */ headers()96 Map<String, List<String>> headers(); 97 98 /** 99 * Add a single header to be included in the created HTTP response. 100 * 101 * <p>This completely <b>OVERRIDES</b> any values already configured with this header name in the builder.</p> 102 * 103 * @param headerName The name of the header to add (eg. "Host") 104 * @param headerValue The value for the header 105 */ putHeader(String headerName, String headerValue)106 default Builder putHeader(String headerName, String headerValue) { 107 return putHeader(headerName, singletonList(headerValue)); 108 } 109 110 /** 111 * Add a single header with multiple values to be included in the created HTTP response. 112 * 113 * <p>This completely <b>OVERRIDES</b> any values already configured with this header name in the builder.</p> 114 * 115 * @param headerName The name of the header to add 116 * @param headerValues The values for the header 117 */ putHeader(String headerName, List<String> headerValues)118 Builder putHeader(String headerName, List<String> headerValues); 119 120 121 /** 122 * Add a single header to be included in the created HTTP request. 123 * 124 * <p>This will <b>ADD</b> the value to any existing values already configured with this header name in 125 * the builder.</p> 126 * 127 * @param headerName The name of the header to add 128 * @param headerValue The value for the header 129 */ appendHeader(String headerName, String headerValue)130 Builder appendHeader(String headerName, String headerValue); 131 132 /** 133 * Configure an {@link SdkHttpResponse#headers()} to be used in the created HTTP response. This is not validated 134 * until the http response is created. This overrides any values currently configured in the builder. 135 */ headers(Map<String, List<String>> headers)136 Builder headers(Map<String, List<String>> headers); 137 138 /** 139 * Remove all values for the requested header from this builder. 140 */ removeHeader(String headerName)141 Builder removeHeader(String headerName); 142 143 /** 144 * Removes all headers from this builder. 145 */ clearHeaders()146 Builder clearHeaders(); 147 } 148 } 149