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.
@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 anAbortableInputStream
. Callers do not need to worry about callingInputStream.close()
on the content, but if they wish to stop reading data from the streamAbortableInputStream.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 aSdkException
with retryable set to true from the transformer. This exception can wrap the original exception that was thrown. Note that throwing aSdkException
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 theRetryPolicy
.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 anInterruptedException
is thrown from a interruptible task, you should either re-interrupt the current thread and return or throw thatInterruptedException
from thetransform(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
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description 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 asResponseBytes
.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 givenOutputStream
.ReturnT
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 Detail
-
transform
ReturnT transform(ResponseT response, AbortableInputStream inputStream) throws Exception
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
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 aFileAlreadyExistsException
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 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
static <ResponseT> ResponseTransformer<ResponseT,ResponseBytes<ResponseT>> 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
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 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.
-
-