Interface ResponseTransformer<ResponseT,ReturnT>
- Type Parameters:
ResponseT
- Type of unmarshalled POJO response.ReturnT
- Return type of thetransform(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.
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 transform(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 and return or
throw that InterruptedException
from the transform(Object, AbortableInputStream)
method. Failure to do these
things may prevent the SDK from stopping the request in a timely manner in the event the thread is interrupted externally.
-
Method Summary
Modifier and TypeMethodDescriptiondefault boolean
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 asResponseBytes
.static <ResponseT>
ResponseTransformer<ResponseT, ResponseT> Creates a response transformer that writes all response content to the specified file.static <ResponseT>
ResponseTransformer<ResponseT, ResponseT> Creates a response transformer that writes all response content to the specified file.static <ResponseT>
ResponseTransformer<ResponseT, ResponseInputStream<ResponseT>> 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 givenOutputStream
.transform
(ResponseT response, AbortableInputStream inputStream) Process the response contents.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 Details
-
transform
Process the response contents.- Parameters:
response
- Unmarshalled POJO responseinputStream
- 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 anSdkClientException
.
-
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
Creates a response transformer that writes all response content to the specified file. If the file already exists then aFileAlreadyExistsException
will be thrown.- Type Parameters:
ResponseT
- Type of unmarshalled response POJO.- Parameters:
path
- Path to file to write to.- Returns:
- ResponseTransformer instance.
-
toFile
Creates a response transformer that writes all response content to the specified file. If the file already exists then aFileAlreadyExistsException
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 givenOutputStream
. Note that theOutputStream
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
Creates a response transformer that loads all response content into memory, exposed asResponseBytes
. This allows for conversion into aString
,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
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 theResponseInputStream.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.
- 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 aResponseTransformer
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.
-