ResponseT
- Type of unmarshalled POJO response.ReturnT
- Return type of the transform(Object, AbortableInputStream)
method. Implementations are free to
perform whatever transformations are appropriate.@FunctionalInterface public interface ResponseTransformer<ResponseT,ReturnT>
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).
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
.
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.
Modifier and Type | Method and Description |
---|---|
default boolean |
needsConnectionLeftOpen()
Hook to allow connection to be left open after the SDK returns a response.
|
static <ResponseT> |
toBytes()
Creates a response transformer that loads all response content into memory, exposed as
ResponseBytes . |
static <ResponseT> |
toFile(File file)
Creates a response transformer that writes all response content to the specified file.
|
static <ResponseT> |
toFile(Path path)
Creates a response transformer that writes all response content to the specified file.
|
static <ResponseT> |
toInputStream()
Creates a response transformer that returns an unmanaged input stream with the response content.
|
static <ResponseT> |
toOutputStream(OutputStream outputStream)
Creates a response transformer that writes all response content to the given
OutputStream . |
ReturnT |
transform(ResponseT response,
AbortableInputStream inputStream)
Process the response contents.
|
static <ResponseT,ReturnT> |
unmanaged(ResponseTransformer<ResponseT,ReturnT> transformer)
Static helper method to create a response transformer that allows the connection to be left open.
|
ReturnT transform(ResponseT response, AbortableInputStream inputStream) throws Exception
response
- Unmarshalled POJO responseinputStream
- Input stream of streamed data.Exception
- if any error occurs during processing of the response. This will be re-thrown by the SDK, possibly
wrapped in an SdkClientException
.default boolean needsConnectionLeftOpen()
static <ResponseT> ResponseTransformer<ResponseT,ResponseT> toFile(Path path)
FileAlreadyExistsException
will be thrown.ResponseT
- Type of unmarshalled response POJO.path
- Path to file to write to.static <ResponseT> ResponseTransformer<ResponseT,ResponseT> toFile(File file)
FileAlreadyExistsException
will be thrown.ResponseT
- Type of unmarshalled response POJO.file
- File to write to.static <ResponseT> ResponseTransformer<ResponseT,ResponseT> toOutputStream(OutputStream outputStream)
OutputStream
. Note that
the OutputStream
is not closed or flushed after writing.ResponseT
- Type of unmarshalled response POJO.outputStream
- Output stream to write data to.static <ResponseT> ResponseTransformer<ResponseT,ResponseBytes<ResponseT>> toBytes()
ResponseBytes
. This allows
for conversion into a String
, ByteBuffer
, etc.ResponseT
- Type of unmarshalled response POJO.static <ResponseT> ResponseTransformer<ResponseT,ResponseInputStream<ResponseT>> toInputStream()
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.
ResponseT
- Type of unmarshalled response POJO.static <ResponseT,ReturnT> ResponseTransformer<ResponseT,ReturnT> unmanaged(ResponseTransformer<ResponseT,ReturnT> transformer)
ResponseTransformer
with a lambda or method reference rather than an anonymous inner class.ResponseT
- Type of unmarshalled response POJO.ReturnT
- Return type of transformer.transformer
- Transformer to wrap.ResponseTransformer
which does not close the connection afterwards.Copyright © 2020. All rights reserved.