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.interceptor; 17 18 import java.io.InputStream; 19 import java.nio.ByteBuffer; 20 import java.util.Optional; 21 import org.reactivestreams.Publisher; 22 import software.amazon.awssdk.annotations.SdkProtectedApi; 23 import software.amazon.awssdk.annotations.SdkPublicApi; 24 import software.amazon.awssdk.annotations.ThreadSafe; 25 import software.amazon.awssdk.core.SdkRequest; 26 import software.amazon.awssdk.core.SdkResponse; 27 import software.amazon.awssdk.core.async.AsyncRequestBody; 28 import software.amazon.awssdk.core.sync.RequestBody; 29 import software.amazon.awssdk.http.SdkHttpFullRequest; 30 import software.amazon.awssdk.http.SdkHttpFullResponse; 31 import software.amazon.awssdk.http.SdkHttpRequest; 32 import software.amazon.awssdk.http.SdkHttpResponse; 33 34 /** 35 * A wrapper for the immutable context objects that are visible to the {@link ExecutionInterceptor}s. 36 */ 37 @SdkProtectedApi 38 public final class Context { Context()39 private Context() { 40 } 41 42 /** 43 * The state of the execution when the {@link ExecutionInterceptor#beforeExecution} method is invoked. 44 */ 45 @ThreadSafe 46 @SdkPublicApi 47 public interface BeforeExecution { 48 /** 49 * The {@link SdkRequest} to be executed. 50 */ request()51 SdkRequest request(); 52 } 53 54 /** 55 * The state of the execution when the {@link ExecutionInterceptor#modifyRequest} method is invoked. 56 */ 57 @ThreadSafe 58 @SdkPublicApi 59 public interface ModifyRequest extends BeforeExecution { 60 } 61 62 /** 63 * The state of the execution when the {@link ExecutionInterceptor#beforeMarshalling} method is invoked. 64 */ 65 @ThreadSafe 66 @SdkPublicApi 67 public interface BeforeMarshalling extends ModifyRequest { 68 } 69 70 /** 71 * The state of the execution when the {@link ExecutionInterceptor#afterMarshalling} method is invoked. 72 */ 73 @ThreadSafe 74 @SdkPublicApi 75 public interface AfterMarshalling extends BeforeMarshalling { 76 /** 77 * The {@link SdkHttpRequest} that was created as a result of marshalling the {@link #request()}. This is the HTTP 78 * request that will be sent to the downstream service. 79 */ httpRequest()80 SdkHttpRequest httpRequest(); 81 82 /** 83 * The {@link RequestBody} that represents the body of an HTTP request. 84 */ requestBody()85 Optional<RequestBody> requestBody(); 86 87 /** 88 * The {@link AsyncRequestBody} that allows non-blocking streaming of request content. 89 */ asyncRequestBody()90 Optional<AsyncRequestBody> asyncRequestBody(); 91 } 92 93 /** 94 * The state of the execution when the {@link ExecutionInterceptor#modifyHttpRequest} method is invoked. 95 */ 96 @ThreadSafe 97 @SdkPublicApi 98 public interface ModifyHttpRequest extends AfterMarshalling { 99 } 100 101 /** 102 * The state of the execution when the {@link ExecutionInterceptor#beforeTransmission} method is invoked. 103 */ 104 @ThreadSafe 105 @SdkPublicApi 106 public interface BeforeTransmission extends ModifyHttpRequest { 107 } 108 109 /** 110 * The state of the execution when the {@link ExecutionInterceptor#afterTransmission} method is invoked. 111 */ 112 @ThreadSafe 113 @SdkPublicApi 114 public interface AfterTransmission extends BeforeTransmission { 115 /** 116 * The HTTP response returned by the service with which the SDK is communicating. 117 */ httpResponse()118 SdkHttpResponse httpResponse(); 119 120 /** 121 * The {@link Publisher} that provides {@link ByteBuffer} events upon request. 122 */ responsePublisher()123 Optional<Publisher<ByteBuffer>> responsePublisher(); 124 125 /** 126 * The {@link InputStream} that provides streaming content returned from the service. 127 */ responseBody()128 Optional<InputStream> responseBody(); 129 } 130 131 /** 132 * The state of the execution when the {@link ExecutionInterceptor#modifyHttpResponse} method is invoked. 133 */ 134 @ThreadSafe 135 @SdkPublicApi 136 public interface ModifyHttpResponse extends AfterTransmission { 137 } 138 139 /** 140 * The state of the execution when the {@link ExecutionInterceptor#beforeUnmarshalling} method is invoked. 141 */ 142 @ThreadSafe 143 @SdkPublicApi 144 public interface BeforeUnmarshalling extends ModifyHttpResponse { 145 } 146 147 /** 148 * The state of the execution when the {@link ExecutionInterceptor#afterUnmarshalling} method is invoked. 149 */ 150 @ThreadSafe 151 @SdkPublicApi 152 public interface AfterUnmarshalling extends BeforeUnmarshalling { 153 /** 154 * The {@link SdkResponse} that was generated by unmarshalling the {@link #httpResponse()}. 155 */ response()156 SdkResponse response(); 157 } 158 159 /** 160 * The state of the execution when the {@link ExecutionInterceptor#modifyResponse} method is invoked. 161 */ 162 @ThreadSafe 163 @SdkPublicApi 164 public interface ModifyResponse extends AfterUnmarshalling { 165 } 166 167 /** 168 * The state of the execution when the {@link ExecutionInterceptor#afterExecution} method is invoked. 169 */ 170 @ThreadSafe 171 @SdkPublicApi 172 public interface AfterExecution extends ModifyResponse { 173 } 174 175 /** 176 * All information that is known about a particular execution that has failed. This is given to 177 * {@link ExecutionInterceptor#onExecutionFailure} if an entire execution fails for any reason. This includes all information 178 * that is known about the request, like the {@link #request()} and the {@link #exception()} that caused the failure. 179 */ 180 @ThreadSafe 181 @SdkPublicApi 182 public interface FailedExecution { 183 /** 184 * The exception associated with the failed execution. This is the reason the execution has failed, and is the exception 185 * that will be returned or thrown from the client method call. This will never return null. 186 */ exception()187 Throwable exception(); 188 189 /** 190 * The latest version of the {@link SdkRequest} available when the execution failed. This will never return null. 191 */ request()192 SdkRequest request(); 193 194 /** 195 * The latest version of the {@link SdkHttpRequest} available when the execution failed. This may be a 196 * {@link SdkHttpFullRequest}; if so, it can be accessed by casting the returned {@link SdkHttpRequest}. 197 * If the execution failed before or during request marshalling, this will return {@link Optional#empty()}. 198 */ httpRequest()199 Optional<SdkHttpRequest> httpRequest(); 200 201 /** 202 * The latest version of the {@link SdkHttpResponse} available when the execution failed. This may be a 203 * {@link SdkHttpFullResponse}; if so, it can be accessed by casting the returned {@link SdkHttpResponse}. 204 * If the execution failed before or during transmission, this will return {@link Optional#empty()}. 205 */ httpResponse()206 Optional<SdkHttpResponse> httpResponse(); 207 208 /** 209 * The latest version of the {@link SdkResponse} available when the execution failed. If the execution failed before or 210 * during response unmarshalling, this will return {@link Optional#empty()}. 211 */ response()212 Optional<SdkResponse> response(); 213 } 214 } 215