Interface AsyncResponseTransformer<ResponseT,ResultT>
- Type Parameters:
ResponseT
- POJO response type.ResultT
- Type this response handler produces. I.E. the type you are transforming the response into.
- All Known Implementing Classes:
AsyncResponseTransformerListener.NotifyingAsyncResponseTransformer
,ByteArrayAsyncResponseTransformer
,EventStreamAsyncResponseTransformer
,FileAsyncResponseTransformer
,InputStreamResponseTransformer
,PublisherAsyncResponseTransformer
,RestEventStreamAsyncResponseTransformer
Synchronization
All operations, including those called on the Subscriber
of the stream are guaranteed to be
synchronized externally; i.e. no two methods on this interface or on the Subscriber
will be
invoked concurrently. It is not guaranteed that the methods will being invoked by the same thread.
Invocation Order
The methods are called in the following order:
-
prepare()
: This method is always called first. Implementations should use this to setup or perform any cleanup necessary. Note that this will be called upon each request attempt. If theCompletableFuture
returned from the previous invocation has already been completed, the implementation should return a new instance. -
onResponse(ResponseT)
: If the response was received successfully, this method is called next. -
onStream(SdkPublisher)
: Called afteronResponse
. This is always invoked, even if the service operation response does not contain a body. If the response does not have a body, then theSdkPublisher
will complete the subscription without signaling any elements. -
exceptionOccurred(Throwable)
: If there is an error sending the request. This method is called beforeSubscriber.onError(Throwable)
. -
Subscriber.onError(Throwable)
: If an error is encountered while thePublisher
is publishing to aSubscriber
.
Retries
The transformer has the ability to trigger retries at any time by completing the CompletableFuture
with an
exception that is deemed retryable by the configured RetryPolicy
.
-
Method Summary
Modifier and TypeMethodDescriptionvoid
exceptionOccurred
(Throwable error) Called when an error is encountered while making the request or receiving the response.void
onResponse
(ResponseT response) Called when the unmarshalled response object is ready.void
onStream
(SdkPublisher<ByteBuffer> publisher) Called when the response stream is ready.prepare()
Initial call to enable any setup required before the response is handled.static <ResponseT extends SdkResponse>
AsyncResponseTransformer<ResponseT, ResponseInputStream<ResponseT>> Creates anAsyncResponseTransformer
that allows reading the response body content as anInputStream
.static <ResponseT>
AsyncResponseTransformer<ResponseT, ResponseBytes<ResponseT>> toBytes()
Creates anAsyncResponseTransformer
that writes all content to a byte array.static <ResponseT>
AsyncResponseTransformer<ResponseT, ResponseT> Creates anAsyncResponseTransformer
that writes all the content to the given file.static <ResponseT>
AsyncResponseTransformer<ResponseT, ResponseT> toFile
(File file, Consumer<FileTransformerConfiguration.Builder> config) This is a convenience method that creates an instance of theFileTransformerConfiguration
builder, avoiding the need to create one manually viaFileTransformerConfiguration.builder()
.static <ResponseT>
AsyncResponseTransformer<ResponseT, ResponseT> toFile
(File file, FileTransformerConfiguration config) Creates anAsyncResponseTransformer
that writes all the content to the given file with the specifiedFileTransformerConfiguration
.static <ResponseT>
AsyncResponseTransformer<ResponseT, ResponseT> Creates anAsyncResponseTransformer
that writes all the content to the given file.static <ResponseT>
AsyncResponseTransformer<ResponseT, ResponseT> toFile
(Path path, Consumer<FileTransformerConfiguration.Builder> config) This is a convenience method that creates an instance of theFileTransformerConfiguration
builder, avoiding the need to create one manually viaFileTransformerConfiguration.builder()
.static <ResponseT>
AsyncResponseTransformer<ResponseT, ResponseT> toFile
(Path path, FileTransformerConfiguration config) Creates anAsyncResponseTransformer
that writes all the content to the given file with the specifiedFileTransformerConfiguration
.static <ResponseT extends SdkResponse>
AsyncResponseTransformer<ResponseT, ResponsePublisher<ResponseT>> Creates anAsyncResponseTransformer
that publishes the response body content through aResponsePublisher
, which is anSdkPublisher
that also contains a reference to theSdkResponse
returned by the service.
-
Method Details
-
prepare
CompletableFuture<ResultT> prepare()Initial call to enable any setup required before the response is handled.Note that this will be called for each request attempt, up to the number of retries allowed by the configured
RetryPolicy
.This method is guaranteed to be called before the request is executed, and before
onResponse(Object)
is signaled.- Returns:
- The future holding the transformed response.
-
onResponse
Called when the unmarshalled response object is ready.- Parameters:
response
- The unmarshalled response.
-
onStream
Called when the response stream is ready.- Parameters:
publisher
- The publisher.
-
exceptionOccurred
Called when an error is encountered while making the request or receiving the response. Implementations should free up any resources in this method. This method may be called multiple times during the lifecycle of a request if automatic retries are enabled.- Parameters:
error
- Error that occurred.
-
toFile
Creates anAsyncResponseTransformer
that writes all the content to the given file. In the event of an error, the SDK will attempt to delete the file (whatever has been written to it so far). If the file already exists, an exception will be thrown.- Type Parameters:
ResponseT
- Pojo Response type.- Parameters:
path
- Path to file to write to.- Returns:
- AsyncResponseTransformer instance.
- See Also:
-
toFile
static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(Path path, FileTransformerConfiguration config) Creates anAsyncResponseTransformer
that writes all the content to the given file with the specifiedFileTransformerConfiguration
.- Type Parameters:
ResponseT
- Pojo Response type.- Parameters:
path
- Path to file to write to.config
- configuration for the transformer- Returns:
- AsyncResponseTransformer instance.
- See Also:
-
toFile
static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(Path path, Consumer<FileTransformerConfiguration.Builder> config) This is a convenience method that creates an instance of theFileTransformerConfiguration
builder, avoiding the need to create one manually viaFileTransformerConfiguration.builder()
.- See Also:
-
toFile
Creates anAsyncResponseTransformer
that writes all the content to the given file. In the event of an error, the SDK will attempt to delete the file (whatever has been written to it so far). If the file already exists, an exception will be thrown.- Type Parameters:
ResponseT
- Pojo Response type.- Parameters:
file
- File to write to.- Returns:
- AsyncResponseTransformer instance.
-
toFile
static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(File file, FileTransformerConfiguration config) Creates anAsyncResponseTransformer
that writes all the content to the given file with the specifiedFileTransformerConfiguration
.- Type Parameters:
ResponseT
- Pojo Response type.- Parameters:
file
- File to write to.config
- configuration for the transformer- Returns:
- AsyncResponseTransformer instance.
- See Also:
-
toFile
static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(File file, Consumer<FileTransformerConfiguration.Builder> config) This is a convenience method that creates an instance of theFileTransformerConfiguration
builder, avoiding the need to create one manually viaFileTransformerConfiguration.builder()
.- See Also:
-
toBytes
Creates anAsyncResponseTransformer
that writes all content to a byte array.- Type Parameters:
ResponseT
- Pojo response type.- Returns:
- AsyncResponseTransformer instance.
-
toPublisher
static <ResponseT extends SdkResponse> AsyncResponseTransformer<ResponseT,ResponsePublisher<ResponseT>> toPublisher()Creates anAsyncResponseTransformer
that publishes the response body content through aResponsePublisher
, which is anSdkPublisher
that also contains a reference to theSdkResponse
returned by the service.When this transformer is used with an async client, the
CompletableFuture
that the client returns will be completed once theSdkResponse
is available and the response body begins streaming. This behavior differs from some other transformers, liketoFile(Path)
andtoBytes()
, which only have theirCompletableFuture
completed after the entire response body has finished streaming.You are responsible for subscribing to this publisher and managing the associated back-pressure. Therefore, this transformer is only recommended for advanced use cases.
Example usage:
CompletableFuture<ResponsePublisher<GetObjectResponse>> responseFuture = s3AsyncClient.getObject(getObjectRequest, AsyncResponseTransformer.toPublisher()); ResponsePublisher<GetObjectResponse> responsePublisher = responseFuture.join(); System.out.println(responsePublisher.response()); CompletableFuture<Void> drainPublisherFuture = responsePublisher.subscribe(System.out::println); drainPublisherFuture.join();
- Type Parameters:
ResponseT
- Pojo response type.- Returns:
- AsyncResponseTransformer instance.
-
toBlockingInputStream
static <ResponseT extends SdkResponse> AsyncResponseTransformer<ResponseT,ResponseInputStream<ResponseT>> toBlockingInputStream()Creates anAsyncResponseTransformer
that allows reading the response body content as anInputStream
.When this transformer is used with an async client, the
CompletableFuture
that the client returns will be completed once theSdkResponse
is available and the response body begins streaming. This behavior differs from some other transformers, liketoFile(Path)
andtoBytes()
, which only have theirCompletableFuture
completed after the entire response body has finished streaming.You are responsible for performing blocking reads from this input stream and closing the stream when you are finished.
Example usage:
CompletableFuture<ResponseInputStream<GetObjectResponse>> responseFuture = s3AsyncClient.getObject(getObjectRequest, AsyncResponseTransformer.toBlockingInputStream()); try (ResponseInputStream<GetObjectResponse> responseStream = responseFuture.join()) { responseStream.transferTo(System.out); // BLOCKS the calling thread }
-