ResponseT
- POJO response type.ResultT
- Type this response handler produces. I.E. the type you are transforming the response into.public interface AsyncResponseTransformer<ResponseT,ResultT>
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.
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 the CompletableFuture
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 after onResponse
. This is always invoked, even if the service
operation response does not contain a body. If the response does not have a body, then the SdkPublisher
will
complete the subscription without signaling any elements.
exceptionOccurred(Throwable)
: If there is an error sending the request. This method is called before Subscriber.onError(Throwable)
.
Subscriber.onError(Throwable)
: If an error is encountered while the Publisher
is
publishing to a Subscriber
.
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
.
Modifier and Type | Method and Description |
---|---|
void |
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.
|
CompletableFuture<ResultT> |
prepare()
Initial call to enable any setup required before the response is handled.
|
static <ResponseT extends SdkResponse> |
toBlockingInputStream()
Creates an
AsyncResponseTransformer that allows reading the response body content as an
InputStream . |
static <ResponseT> |
toBytes()
Creates an
AsyncResponseTransformer that writes all content to a byte array. |
static <ResponseT> |
toFile(File file)
Creates an
AsyncResponseTransformer that writes all the content to the given file. |
static <ResponseT> |
toFile(File file,
Consumer<FileTransformerConfiguration.Builder> config)
This is a convenience method that creates an instance of the
FileTransformerConfiguration builder,
avoiding the need to create one manually via FileTransformerConfiguration.builder() . |
static <ResponseT> |
toFile(File file,
FileTransformerConfiguration config)
Creates an
AsyncResponseTransformer that writes all the content to the given file with the specified FileTransformerConfiguration . |
static <ResponseT> |
toFile(Path path)
Creates an
AsyncResponseTransformer that writes all the content to the given file. |
static <ResponseT> |
toFile(Path path,
Consumer<FileTransformerConfiguration.Builder> config)
This is a convenience method that creates an instance of the
FileTransformerConfiguration builder,
avoiding the need to create one manually via FileTransformerConfiguration.builder() . |
static <ResponseT> |
toFile(Path path,
FileTransformerConfiguration config)
Creates an
AsyncResponseTransformer that writes all the content to the given file with the specified FileTransformerConfiguration . |
static <ResponseT extends SdkResponse> |
toPublisher()
Creates an
AsyncResponseTransformer that publishes the response body content through a ResponsePublisher ,
which is an SdkPublisher that also contains a reference to the SdkResponse returned by the service. |
CompletableFuture<ResultT> prepare()
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.
void onResponse(ResponseT response)
response
- The unmarshalled response.void onStream(SdkPublisher<ByteBuffer> publisher)
publisher
- The publisher.void exceptionOccurred(Throwable error)
error
- Error that occurred.static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(Path path)
AsyncResponseTransformer
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.ResponseT
- Pojo Response type.path
- Path to file to write to.toFile(Path, FileTransformerConfiguration)
static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(Path path, FileTransformerConfiguration config)
AsyncResponseTransformer
that writes all the content to the given file with the specified FileTransformerConfiguration
.ResponseT
- Pojo Response type.path
- Path to file to write to.config
- configuration for the transformerFileTransformerConfiguration
static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(Path path, Consumer<FileTransformerConfiguration.Builder> config)
FileTransformerConfiguration
builder,
avoiding the need to create one manually via FileTransformerConfiguration.builder()
.static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(File file)
AsyncResponseTransformer
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.ResponseT
- Pojo Response type.file
- File to write to.static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(File file, FileTransformerConfiguration config)
AsyncResponseTransformer
that writes all the content to the given file with the specified FileTransformerConfiguration
.ResponseT
- Pojo Response type.file
- File to write to.config
- configuration for the transformerFileTransformerConfiguration
static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(File file, Consumer<FileTransformerConfiguration.Builder> config)
FileTransformerConfiguration
builder,
avoiding the need to create one manually via FileTransformerConfiguration.builder()
.static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseBytes<ResponseT>> toBytes()
AsyncResponseTransformer
that writes all content to a byte array.ResponseT
- Pojo response type.static <ResponseT extends SdkResponse> AsyncResponseTransformer<ResponseT,ResponsePublisher<ResponseT>> toPublisher()
AsyncResponseTransformer
that publishes the response body content through a ResponsePublisher
,
which is an SdkPublisher
that also contains a reference to the SdkResponse
returned by the service.
When this transformer is used with an async client, the CompletableFuture
that the client returns will be completed
once the SdkResponse
is available and the response body begins streaming. This behavior differs from some
other transformers, like toFile(Path)
and toBytes()
, which only have their CompletableFuture
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();
ResponseT
- Pojo response type.static <ResponseT extends SdkResponse> AsyncResponseTransformer<ResponseT,ResponseInputStream<ResponseT>> toBlockingInputStream()
AsyncResponseTransformer
that allows reading the response body content as an
InputStream
.
When this transformer is used with an async client, the CompletableFuture
that the client returns will
be completed once the SdkResponse
is available and the response body begins streaming. This
behavior differs from some other transformers, like toFile(Path)
and toBytes()
, which only
have their CompletableFuture
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
}
Copyright © 2023. All rights reserved.