Package software.amazon.awssdk.core.async

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, FileAsyncResponseTransformer, InputStreamResponseTransformer, PublisherAsyncResponseTransformer
    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 Detail

      • 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

        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(Path, FileTransformerConfiguration)

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

      • 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
     }