software.amazon.awssdk.core.async

Interface AsyncRequestBody

All Superinterfaces:

org.reactivestreams.Publisher<ByteBuffer>, SdkPublisher<ByteBuffer>

All Known Implementing Classes:

AsyncRequestBodyListener.NotifyingAsyncRequestBody, BlockingInputStreamAsyncRequestBody, BlockingOutputStreamAsyncRequestBody, ByteArrayAsyncRequestBody, ChecksumCalculatingAsyncRequestBody, FileAsyncRequestBody, InputStreamWithExecutorAsyncRequestBody

public interface AsyncRequestBody
extends SdkPublisher<ByteBuffer>

Interface to allow non-blocking streaming of request content. This follows the reactive streams pattern where this interface is the Publisher of data (specifically ByteBuffer chunks) and the HTTP client is the Subscriber of the data (i.e. to write that data on the wire).

Publisher.subscribe(Subscriber) should be implemented to tie this publisher to a subscriber. Ideally each call to subscribe should reproduce the content (i.e if you are reading from a file each subscribe call should produce a Subscription that reads the file fully). This allows for automatic retries to be performed in the SDK. If the content is not reproducible, an exception may be thrown from any subsequent Publisher.subscribe(Subscriber) calls.

It is important to only send the number of chunks that the subscriber requests to avoid out of memory situations. The subscriber does it's own buffering so it's usually not needed to buffer in the publisher. Additional permits for chunks will be notified via the Subscription.request(long) method.

See Also:

FileAsyncRequestBody, ByteArrayAsyncRequestBody

Method Summary

Modifier and Type	Method and Description
Optional<Long>	contentLength()
default String	contentType()
static AsyncRequestBody	empty() Creates a AsyncRequestBody with no content.
static BlockingInputStreamAsyncRequestBody	forBlockingInputStream(Long contentLength) Creates a BlockingInputStreamAsyncRequestBody to use for writing an input stream to the downstream service.
static BlockingOutputStreamAsyncRequestBody	forBlockingOutputStream(Long contentLength) Creates a BlockingOutputStreamAsyncRequestBody to use for writing to the downstream service as if it's an output stream.
static AsyncRequestBody	fromByteBuffer(ByteBuffer byteBuffer) Creates a AsyncRequestBody from a ByteBuffer.
static AsyncRequestBody	fromBytes(byte[] bytes) Creates a AsyncRequestBody from a byte array.
static AsyncRequestBody	fromFile(File file) Creates an AsyncRequestBody that produces data from the contents of a file.
static AsyncRequestBody	fromFile(Path path) Creates an AsyncRequestBody that produces data from the contents of a file.
static AsyncRequestBody	fromInputStream(InputStream inputStream, Long contentLength, ExecutorService executor) Creates a AsyncRequestBody from a InputStream.
static AsyncRequestBody	fromPublisher(org.reactivestreams.Publisher<ByteBuffer> publisher) Creates an AsyncRequestBody the produces data from the input ByteBuffer publisher.
static AsyncRequestBody	fromString(String string) Creates an AsyncRequestBody that uses a single string as data with UTF_8 encoding.
static AsyncRequestBody	fromString(String string, Charset cs) Creates an AsyncRequestBody that uses a single string as data.

Methods inherited from interface software.amazon.awssdk.core.async.SdkPublisher

adapt, buffer, doAfterOnCancel, doAfterOnComplete, doAfterOnError, filter, filter, flatMapIterable, limit, map, subscribe

Methods inherited from interface org.reactivestreams.Publisher

subscribe

Method Detail

contentLength

Optional<Long> contentLength()

Returns:

The content length of the data being produced.

contentType

default String contentType()

Returns:

The content type of the data being produced.

fromPublisher

static AsyncRequestBody fromPublisher(org.reactivestreams.Publisher<ByteBuffer> publisher)

Creates an AsyncRequestBody the produces data from the input ByteBuffer publisher. The data is delivered when the publisher publishes the data.

Parameters:

publisher - Publisher of source data

Returns:

Implementation of AsyncRequestBody that produces data send by the publisher

fromFile

static AsyncRequestBody fromFile(Path path)

Creates an AsyncRequestBody that produces data from the contents of a file. See FileAsyncRequestBody.builder() to create a customized body implementation.

Parameters:

path - Path to file to read from.

Returns:

Implementation of AsyncRequestBody that reads data from the specified file.

See Also:

FileAsyncRequestBody

fromFile

static AsyncRequestBody fromFile(File file)

Creates an AsyncRequestBody that produces data from the contents of a file. See FileAsyncRequestBody.builder() to create a customized body implementation.

Parameters:

file - The file to read from.

Returns:

Implementation of AsyncRequestBody that reads data from the specified file.

See Also:

FileAsyncRequestBody

fromString

static AsyncRequestBody fromString(String string,
                                   Charset cs)

Creates an AsyncRequestBody that uses a single string as data.

Parameters:

string - The string to provide.

cs - The Charset to use.

Returns:

Implementation of AsyncRequestBody that uses the specified string.

See Also:

ByteArrayAsyncRequestBody

fromString

static AsyncRequestBody fromString(String string)

Creates an AsyncRequestBody that uses a single string as data with UTF_8 encoding.

Parameters:

string - The string to send.

Returns:

Implementation of AsyncRequestBody that uses the specified string.

See Also:

fromString(String, Charset)

fromBytes

static AsyncRequestBody fromBytes(byte[] bytes)

Creates a AsyncRequestBody from a byte array. The contents of the byte array are copied so modifications to the original byte array are not reflected in the AsyncRequestBody.

Parameters:

bytes - The bytes to send to the service.

Returns:

AsyncRequestBody instance.

fromByteBuffer

static AsyncRequestBody fromByteBuffer(ByteBuffer byteBuffer)

Creates a AsyncRequestBody from a ByteBuffer. Buffer contents are copied so any modifications made to the original ByteBuffer are not reflected in the AsyncRequestBody.

Parameters:

byteBuffer - ByteBuffer to send to the service.

Returns:

AsyncRequestBody instance.

fromInputStream

static AsyncRequestBody fromInputStream(InputStream inputStream,
                                        Long contentLength,
                                        ExecutorService executor)

Creates a AsyncRequestBody from a InputStream.

An ExecutorService is required in order to perform the blocking data reads, to prevent blocking the non-blocking event loop threads owned by the SDK.

forBlockingInputStream

static BlockingInputStreamAsyncRequestBody forBlockingInputStream(Long contentLength)

Creates a BlockingInputStreamAsyncRequestBody to use for writing an input stream to the downstream service.

Example Usage

forBlockingOutputStream

static BlockingOutputStreamAsyncRequestBody forBlockingOutputStream(Long contentLength)

Creates a BlockingOutputStreamAsyncRequestBody to use for writing to the downstream service as if it's an output stream. Retries are not supported for this request body.

The caller is responsible for calling OutputStream.close() on the #outputStream() when writing is complete.

Example Usage

empty

static AsyncRequestBody empty()

Creates a AsyncRequestBody with no content.

Returns:

AsyncRequestBody instance.