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

public interface AsyncResponseTransformer<ResponseT,ResultT>
Callback interface to handle a streaming asynchronous response.

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 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.

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 Details

    • 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

      void onResponse(ResponseT response)
      Called when the unmarshalled response object is ready.
      Parameters:
      response - The unmarshalled response.
    • onStream

      void onStream(SdkPublisher<ByteBuffer> publisher)
      Called when the response stream is ready.
      Parameters:
      publisher - The publisher.
    • exceptionOccurred

      void exceptionOccurred(Throwable error)
      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

      static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(Path path)
      Creates an 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.
      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 an AsyncResponseTransformer that writes all the content to the given file with the specified FileTransformerConfiguration.
      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 the FileTransformerConfiguration builder, avoiding the need to create one manually via FileTransformerConfiguration.builder().
      See Also:
    • toFile

      static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseT> toFile(File file)
      Creates an 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.
      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 an AsyncResponseTransformer that writes all the content to the given file with the specified FileTransformerConfiguration.
      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 the FileTransformerConfiguration builder, avoiding the need to create one manually via FileTransformerConfiguration.builder().
      See Also:
    • toBytes

      static <ResponseT> AsyncResponseTransformer<ResponseT,ResponseBytes<ResponseT>> toBytes()
      Creates an AsyncResponseTransformer 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 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.

      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();
       
       
      Type Parameters:
      ResponseT - Pojo response type.
      Returns:
      AsyncResponseTransformer instance.
    • toBlockingInputStream

      static <ResponseT extends SdkResponse> AsyncResponseTransformer<ResponseT,ResponseInputStream<ResponseT>> toBlockingInputStream()
      Creates an 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
           }