software.amazon.awssdk.core.sync

Interface ResponseTransformer<ResponseT,ReturnT>

Type Parameters:

ResponseT - Type of unmarshalled POJO response.

ReturnT - Return type of the apply(Object, AbortableInputStream) method. Implementations are free to perform whatever transformations are appropriate.

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface ResponseTransformer<ResponseT,ReturnT>

Interface for processing a streaming response from a service in a synchronous fashion. This interfaces gives access to the unmarshalled response POJO which may contain metadata about the streamed contents. It also provides access to the content via an AbortableInputStream. Callers do not need to worry about calling InputStream.close() on the content, but if they wish to stop reading data from the stream AbortableInputStream.abort() may be called to kill the underlying HTTP connection. This is generally not recommended and should only be done when the cost of reading the rest of the data exceeds the cost of establishing a new connection. If callers do not call abort and do not read all of the data in the stream, then the content will be drained by the SDK and the underlying HTTP connection will be returned to the connection pool (if applicable).

Retries

Exceptions thrown from the transformer's apply(Object, AbortableInputStream) method are not automatically retried by the RetryPolicy of the client. Since we can't know if a transformer implementation is idempotent or safe to retry, if you wish to retry on the event of a failure you must throw a SdkException with retryable set to true from the transformer. This exception can wrap the original exception that was thrown. Note that throwing a SdkException that is marked retryable from the transformer does not guarantee the request will be retried, retries are still limited by the max retry attempts and retry throttling feature of the RetryPolicy.

Thread Interrupts

Implementations should have proper handling of Thread interrupts. For long running, non-interruptible tasks, it is recommended to check the thread interrupt status periodically and throw an InterruptedException if set. When an InterruptedException is thrown from a interruptible task, you should either re-interrupt the current thread or throw that InterruptedException from the apply(Object, AbortableInputStream) method. Failure to do these things will prevent the total execution timeout from working (see ClientOverrideConfiguration#totalExecutionTimeout() and may prevent the SDK from stopping the request in a timely manner in the event the thread is interrupted externally.

Method Summary

Modifier and Type	Method and Description
ReturnT	apply(ResponseT response, AbortableInputStream inputStream) Process the response contents.
default boolean	needsConnectionLeftOpen() Hook to allow connection to be left open after the SDK returns a response.
static <ResponseT> ResponseTransformer<ResponseT,ResponseBytes<ResponseT>>	toBytes() Creates a response transformer that loads all response content into memory, exposed as ResponseBytes.
static <ResponseT> ResponseTransformer<ResponseT,ResponseT>	toFile(File file) Creates a response transformer that writes all response content to the specified file.
static <ResponseT> ResponseTransformer<ResponseT,ResponseT>	toFile(Path path) Creates a response transformer that writes all response content to the specified file.
static <ResponseT> ResponseTransformer<ResponseT,ResponseInputStream<ResponseT>>	toInputStream() Creates a response transformer that returns an unmanaged input stream with the response content.
static <ResponseT> ResponseTransformer<ResponseT,ResponseT>	toOutputStream(OutputStream outputStream) Creates a response transformer that writes all response content to the given OutputStream.
static <ResponseT,ReturnT> ResponseTransformer<ResponseT,ReturnT>	unmanaged(ResponseTransformer<ResponseT,ReturnT> transformer) Static helper method to create a response transformer that allows the connection to be left open.

Method Detail

apply

ReturnT apply(ResponseT response,
              AbortableInputStream inputStream)
       throws Exception

Process the response contents.

Parameters:

response - Unmarshalled POJO response

inputStream - Input stream of streamed data.

Returns:

Transformed type.

Throws:

Exception - if any error occurs during processing of the response. This will be re-thrown by the SDK, possibly wrapped in an SdkClientException.

needsConnectionLeftOpen

default boolean needsConnectionLeftOpen()

Hook to allow connection to be left open after the SDK returns a response. Useful for returning the InputStream to the response content from the transformer.

Returns:

True if connection (and InputStream) should be left open after the SDK returns a response, false otherwise.

toFile

static <ResponseT> ResponseTransformer<ResponseT,ResponseT> toFile(Path path)

Creates a response transformer that writes all response content to the specified file. If the file already exists then a FileAlreadyExistsException will be thrown.

Type Parameters:

ResponseT - Type of unmarshalled response POJO.

Parameters:

path - Path to file to write to.

Returns:

ResponseTransformer instance.

toFile

static <ResponseT> ResponseTransformer<ResponseT,ResponseT> toFile(File file)

Creates a response transformer that writes all response content to the specified file. If the file already exists then a FileAlreadyExistsException will be thrown.

Type Parameters:

ResponseT - Type of unmarshalled response POJO.

Parameters:

file - File to write to.

Returns:

ResponseTransformer instance.

toOutputStream

static <ResponseT> ResponseTransformer<ResponseT,ResponseT> toOutputStream(OutputStream outputStream)

Creates a response transformer that writes all response content to the given OutputStream. Note that the OutputStream is not closed or flushed after writing.

Type Parameters:

ResponseT - Type of unmarshalled response POJO.

Parameters:

outputStream - Output stream to write data to.

Returns:

ResponseTransformer instance.

toBytes

static <ResponseT> ResponseTransformer<ResponseT,ResponseBytes<ResponseT>> toBytes()

Creates a response transformer that loads all response content into memory, exposed as ResponseBytes. This allows for conversion into a String, ByteBuffer, etc.

Type Parameters:

ResponseT - Type of unmarshalled response POJO.

Returns:

The streaming response transformer that can be used on the client streaming method.

toInputStream

static <ResponseT> ResponseTransformer<ResponseT,ResponseInputStream<ResponseT>> toInputStream()

Creates a response transformer that returns an unmanaged input stream with the response content. This input stream must be explicitly closed to release the connection. The unmarshalled response object can be obtained via the ResponseInputStream.response method.

Note that the returned stream is not subject to the retry policy or timeout settings (except for socket timeout) of the client. No retries will be performed in the event of a socket read failure or connection reset. Similarly, the total execution timeout (see software.amazon.awssdk.core.config.ClientOverrideConfiguration#totalExecutionTimeout) will stop once the input stream has been returned by the SDK.

Type Parameters:

ResponseT - Type of unmarshalled response POJO.

Returns:

ResponseTransformer instance.

unmanaged

static <ResponseT,ReturnT> ResponseTransformer<ResponseT,ReturnT> unmanaged(ResponseTransformer<ResponseT,ReturnT> transformer)

Static helper method to create a response transformer that allows the connection to be left open. Useful for creating a ResponseTransformer with a lambda or method reference rather than an anonymous inner class.

Type Parameters:

ResponseT - Type of unmarshalled response POJO.

ReturnT - Return type of transformer.

Parameters:

transformer - Transformer to wrap.

Returns:

New ResponseTransformer which does not close the connection afterwards.