public interface ExecutionInterceptor
Interceptor Hooks
Methods for a given interceptor are executed in a predictable order, each receiving the information that is known about the
message so far as well as a ExecutionAttributes
object for storing data that is specific to a particular execution.
beforeExecution(software.amazon.awssdk.core.interceptor.Context.BeforeExecution, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Read the request before it is modified by other interceptors.modifyRequest(software.amazon.awssdk.core.interceptor.Context.ModifyRequest, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Modify the request object before it is marshalled into an HTTP request.beforeMarshalling(software.amazon.awssdk.core.interceptor.Context.BeforeMarshalling, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Read the request that has potentially been modified by other request interceptors before
it is marshalled into an HTTP request.afterMarshalling(software.amazon.awssdk.core.interceptor.Context.AfterMarshalling, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Read the HTTP request after it is created and before it can be modified by other
interceptors.modifyHttpRequest(software.amazon.awssdk.core.interceptor.Context.ModifyHttpRequest, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Modify the HTTP request object before it is transmitted.beforeTransmission(software.amazon.awssdk.core.interceptor.Context.BeforeTransmission, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Read the HTTP request that has potentially been modified by other request interceptors
before it is sent to the service.afterTransmission(software.amazon.awssdk.core.interceptor.Context.AfterTransmission, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Read the HTTP response after it is received and before it can be modified by other
interceptors.modifyHttpResponse(software.amazon.awssdk.core.interceptor.Context.ModifyHttpResponse, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Modify the HTTP response object before it is unmarshalled.beforeUnmarshalling(software.amazon.awssdk.core.interceptor.Context.BeforeUnmarshalling, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Read the HTTP response that has potentially been modified by other request interceptors
before it is unmarshalled.afterUnmarshalling(software.amazon.awssdk.core.interceptor.Context.AfterUnmarshalling, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Read the response after it is created and before it can be modified by other
interceptors.modifyResponse(software.amazon.awssdk.core.interceptor.Context.ModifyResponse, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Modify the response object before before it is returned to the client.afterExecution(software.amazon.awssdk.core.interceptor.Context.AfterExecution, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
- Read the response that has potentially been modified by other request interceptors.onExecutionFailure(software.amazon.awssdk.core.interceptor.Context.FailedExecution, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
method is provided that is invoked if an execution fails at any point during the
lifecycle of a request, including exceptions being thrown from this or other interceptors.
Interceptor Registration Interceptors can be registered in one of many ways.
ClientOverrideConfiguration.Builder#addExecutionInterceptor(ExecutionInterceptor)
method.
Interceptor Order The order in which interceptors are executed is sometimes relevant to the accuracy of the interceptor itself. For example, an interceptor that adds a field to a message should be executed before an interceptor that reads and modifies that field. Interceptor's order is determined by their method of registration. The following order is used:
ClientOverrideConfiguration.Builder#addExecutionInterceptor(ExecutionInterceptor)
in the order they were added.beforeTransmission(software.amazon.awssdk.core.interceptor.Context.BeforeTransmission, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
, interceptors are applied in forward-order,
according to the order described above. When a response is being processed (after and including afterTransmission(software.amazon.awssdk.core.interceptor.Context.AfterTransmission, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
,
interceptors are applied in reverse-order from the order described above. This means that the last interceptors to touch the
request are the first interceptors to touch the response.
Execution Attributes
ExecutionAttributes
are unique to an execution (the process of an SDK processing a SdkRequest
). This mutable
collection of attributes is created when a call to a service client is made and can be mutated throughout the course of the
client call. These attributes are made available to every interceptor hook and is available for storing data between method
calls. The SDK provides some attributes automatically, available via SdkExecutionAttribute
.
Modifier and Type | Method and Description |
---|---|
default void |
afterExecution(Context.AfterExecution context,
ExecutionAttributes executionAttributes)
Read the finalized
SdkResponse as it will be returned by the client invocation. |
default void |
afterMarshalling(Context.AfterMarshalling context,
ExecutionAttributes executionAttributes)
Read the marshalled HTTP request, before it is modified by other interceptors.
|
default void |
afterTransmission(Context.AfterTransmission context,
ExecutionAttributes executionAttributes)
Read the HTTP response as it was returned by the HTTP client, before it is modified by other interceptors.
|
default void |
afterUnmarshalling(Context.AfterUnmarshalling context,
ExecutionAttributes executionAttributes)
Read the
SdkResponse as it was returned by the unmarshaller, before it is modified by other interceptors. |
default void |
beforeExecution(Context.BeforeExecution context,
ExecutionAttributes executionAttributes)
Read a request that has been given to a service client before it is modified by other interceptors.
|
default void |
beforeMarshalling(Context.BeforeMarshalling context,
ExecutionAttributes executionAttributes)
Read the finalized request as it will be given to the marshaller to be converted into an
SdkHttpFullRequest . |
default void |
beforeTransmission(Context.BeforeTransmission context,
ExecutionAttributes executionAttributes)
Read the finalized HTTP request as it will be sent to the HTTP client.
|
default void |
beforeUnmarshalling(Context.BeforeUnmarshalling context,
ExecutionAttributes executionAttributes)
Read the finalized HTTP response as it will be given to the unmarshaller to be converted into an
SdkResponse . |
default Optional<AsyncRequestBody> |
modifyAsyncHttpContent(Context.ModifyHttpRequest context,
ExecutionAttributes executionAttributes) |
default Optional<org.reactivestreams.Publisher<ByteBuffer>> |
modifyAsyncHttpResponseContent(Context.ModifyHttpResponse context,
ExecutionAttributes executionAttributes)
Modify the
SdkHttpFullRequest before it is unmarshalled into an SdkResponse . |
default Throwable |
modifyException(Context.FailedExecution context,
ExecutionAttributes executionAttributes)
Modify the exception before it is thrown.
|
default Optional<RequestBody> |
modifyHttpContent(Context.ModifyHttpRequest context,
ExecutionAttributes executionAttributes) |
default SdkHttpRequest |
modifyHttpRequest(Context.ModifyHttpRequest context,
ExecutionAttributes executionAttributes)
Modify the
SdkHttpFullRequest before it is sent to the service. |
default SdkHttpResponse |
modifyHttpResponse(Context.ModifyHttpResponse context,
ExecutionAttributes executionAttributes)
Modify the
SdkHttpFullRequest before it is unmarshalled into an SdkResponse . |
default Optional<InputStream> |
modifyHttpResponseContent(Context.ModifyHttpResponse context,
ExecutionAttributes executionAttributes)
Modify the
SdkHttpFullRequest before it is unmarshalled into an SdkResponse . |
default SdkRequest |
modifyRequest(Context.ModifyRequest context,
ExecutionAttributes executionAttributes)
Modify an
SdkRequest given to a service client before it is marshalled into an SdkHttpFullRequest . |
default SdkResponse |
modifyResponse(Context.ModifyResponse context,
ExecutionAttributes executionAttributes)
Modify the
SdkResponse before it is returned by the client. |
default void |
onExecutionFailure(Context.FailedExecution context,
ExecutionAttributes executionAttributes)
Invoked when any error happens during an execution that prevents the request from succeeding.
|
default void beforeExecution(Context.BeforeExecution context, ExecutionAttributes executionAttributes)
beforeMarshalling(software.amazon.awssdk.core.interceptor.Context.BeforeMarshalling, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
should be used in most circumstances for reading the request because it includes modifications
made by other interceptors.
This method is guaranteed to be executed on the thread that is making the client call. This is true even if a non-
blocking I/O client is used. This is useful for transferring data that may be stored thread-locally into the execution's
ExecutionAttributes
.
context
- The current state of the execution, including the unmodified SDK request from the service client call.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used todefault SdkRequest modifyRequest(Context.ModifyRequest context, ExecutionAttributes executionAttributes)
SdkRequest
given to a service client before it is marshalled into an SdkHttpFullRequest
.context
- The current state of the execution, including the current SDK request from the service client call.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default void beforeMarshalling(Context.BeforeMarshalling context, ExecutionAttributes executionAttributes)
SdkHttpFullRequest
.context
- The current state of the execution, including the SDK request (potentially modified by other interceptors)
from the service client call.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used todefault void afterMarshalling(Context.AfterMarshalling context, ExecutionAttributes executionAttributes)
beforeTransmission(software.amazon.awssdk.core.interceptor.Context.BeforeTransmission, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
should be used
in most circumstances for reading the HTTP request because it includes modifications made by other interceptors.context
- The current state of the execution, including the SDK and unmodified HTTP request.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used todefault SdkHttpRequest modifyHttpRequest(Context.ModifyHttpRequest context, ExecutionAttributes executionAttributes)
SdkHttpFullRequest
before it is sent to the service.context
- The current state of the execution, including the SDK and current HTTP request.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default Optional<RequestBody> modifyHttpContent(Context.ModifyHttpRequest context, ExecutionAttributes executionAttributes)
default Optional<AsyncRequestBody> modifyAsyncHttpContent(Context.ModifyHttpRequest context, ExecutionAttributes executionAttributes)
default void beforeTransmission(Context.BeforeTransmission context, ExecutionAttributes executionAttributes)
Note: Unlike many other lifecycle methods, this one may be invoked multiple times. If the RetryPolicy
determines
a request failure is retriable, this will be invoked for each retry attempt.
context
- The current state of the execution, including the SDK and HTTP request (potentially modified by other
interceptors) to be sent to the downstream service.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used todefault void afterTransmission(Context.AfterTransmission context, ExecutionAttributes executionAttributes)
beforeUnmarshalling(software.amazon.awssdk.core.interceptor.Context.BeforeUnmarshalling, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
should be used in most circumstances for reading the HTTP response because it includes
modifications made by other interceptors.
It is possible that the HTTP client could have already modified this response, so debug-level wire logging should be trusted over the parameters to this method.
Note: Unlike many other lifecycle methods, this one may be invoked multiple times. If the RetryPolicy
determines
the error code returned by the service is retriable, this will be invoked for each response returned by the service.
context
- The current state of the execution, including the SDK and HTTP requests and the unmodified HTTP response.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used todefault SdkHttpResponse modifyHttpResponse(Context.ModifyHttpResponse context, ExecutionAttributes executionAttributes)
SdkHttpFullRequest
before it is unmarshalled into an SdkResponse
.
Note: Unlike many other lifecycle methods, this one may be invoked multiple times. If the RetryPolicy
determines
the error code returned by the service is retriable, this will be invoked for each response returned by the service.
context
- The current state of the execution, including the SDK and HTTP requests and the current HTTP response.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default Optional<org.reactivestreams.Publisher<ByteBuffer>> modifyAsyncHttpResponseContent(Context.ModifyHttpResponse context, ExecutionAttributes executionAttributes)
SdkHttpFullRequest
before it is unmarshalled into an SdkResponse
.
Note: Unlike many other lifecycle methods, this one may be invoked multiple times. If the RetryPolicy
determines
the error code returned by the service is retriable, this will be invoked for each response returned by the service.
context
- The current state of the execution, including the SDK and HTTP requests and the current HTTP response.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default Optional<InputStream> modifyHttpResponseContent(Context.ModifyHttpResponse context, ExecutionAttributes executionAttributes)
SdkHttpFullRequest
before it is unmarshalled into an SdkResponse
.
Note: Unlike many other lifecycle methods, this one may be invoked multiple times. If the RetryPolicy
determines
the error code returned by the service is retriable, this will be invoked for each response returned by the service.
context
- The current state of the execution, including the SDK and HTTP requests and the current HTTP response.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default void beforeUnmarshalling(Context.BeforeUnmarshalling context, ExecutionAttributes executionAttributes)
SdkResponse
.
Note: Unlike many other lifecycle methods, this one may be invoked multiple times. If the RetryPolicy
determines
the error code returned by the service is retriable, this will be invoked for each response returned by the service.
context
- The current state of the execution, including the SDK and HTTP requests as well as the (potentially
modified by other interceptors) HTTP response.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default void afterUnmarshalling(Context.AfterUnmarshalling context, ExecutionAttributes executionAttributes)
SdkResponse
as it was returned by the unmarshaller, before it is modified by other interceptors.
afterExecution(software.amazon.awssdk.core.interceptor.Context.AfterExecution, software.amazon.awssdk.core.interceptor.ExecutionAttributes)
should be used in most circumstances for reading the SDK response because it includes
modifications made by other interceptors.context
- The current state of the execution, including the SDK and HTTP requests and the HTTP response.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default SdkResponse modifyResponse(Context.ModifyResponse context, ExecutionAttributes executionAttributes)
SdkResponse
before it is returned by the client.context
- The current state of the execution, including the SDK and HTTP requests as well as the SDK and HTTP
response.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default void afterExecution(Context.AfterExecution context, ExecutionAttributes executionAttributes)
SdkResponse
as it will be returned by the client invocation.context
- The current state of the execution, including the SDK and HTTP requests as well as the SDK and HTTP
response.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default Throwable modifyException(Context.FailedExecution context, ExecutionAttributes executionAttributes)
This will only be invoked if the entire execution fails. If a retriable error happens (according to the
RetryPolicy
) and a subsequent retry succeeds, this method will not be invoked.
context
- The context associated with the execution that failed. An SDK request will always be available, but
depending on the time at which the failure happened, the HTTP request, HTTP response and SDK response may
not be available. This also includes the exception that triggered the failure.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.default void onExecutionFailure(Context.FailedExecution context, ExecutionAttributes executionAttributes)
This will only be invoked if the entire execution fails. If a retriable error happens (according to the
RetryPolicy
) and a subsequent retry succeeds, this method will not be invoked.
context
- The context associated with the execution that failed. An SDK request will always be available, but
depending on the time at which the failure happened, the HTTP request, HTTP response and SDK response may
not be available. This also includes the exception that triggered the failure.executionAttributes
- A mutable set of attributes scoped to one specific request/response cycle that can be used to
give data to future lifecycle methods.Copyright © 2020. All rights reserved.