Package software.amazon.awssdk.core.async

Interface AsyncRequestBody

All Superinterfaces:

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

All Known Implementing Classes:

AsyncRequestBodyListener.NotifyingAsyncRequestBody, BlockingInputStreamAsyncRequestBody, BlockingOutputStreamAsyncRequestBody, ByteBuffersAsyncRequestBody, ChecksumCalculatingAsyncRequestBody, CompressionAsyncRequestBody, 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, ByteBuffersAsyncRequestBody

Method Summary

Modifier and Type	Method	Description
Optional<Long>	contentLength()
default String	contentType()
static AsyncRequestBody	empty()	Creates an 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 an AsyncRequestBody from a ByteBuffer.
static AsyncRequestBody	fromByteBuffers(ByteBuffer... byteBuffers)	Creates an AsyncRequestBody from a ByteBuffer array.
static AsyncRequestBody	fromByteBuffersUnsafe(ByteBuffer... byteBuffers)	Creates an AsyncRequestBody from a ByteBuffer array without copying the contents of each ByteBuffer.
static AsyncRequestBody	fromByteBufferUnsafe(ByteBuffer byteBuffer)	Creates an AsyncRequestBody from a ByteBuffer without copying the contents of the ByteBuffer.
static AsyncRequestBody	fromBytes(byte[] bytes)	Creates an AsyncRequestBody from a byte array.
static AsyncRequestBody	fromBytesUnsafe(byte[] bytes)	Creates an AsyncRequestBody from a byte array without copying the contents of the 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	fromFile(Consumer<FileRequestBodyConfiguration.Builder> configuration)	Creates an AsyncRequestBody that produces data from the contents of a file.
static AsyncRequestBody	fromFile(FileRequestBodyConfiguration configuration)	Creates an AsyncRequestBody that produces data from the contents of a file.
static AsyncRequestBody	fromInputStream(InputStream inputStream, Long contentLength, ExecutorService executor)	Creates an AsyncRequestBody from an InputStream.
static AsyncRequestBody	fromInputStream(Consumer<AsyncRequestBodyFromInputStreamConfiguration.Builder> configuration)	This is a convenience method that passes an instance of the AsyncRequestBodyFromInputStreamConfiguration builder, avoiding the need to create one manually via AsyncRequestBodyFromInputStreamConfiguration.builder().
static AsyncRequestBody	fromInputStream(AsyncRequestBodyFromInputStreamConfiguration configuration)	Creates an AsyncRequestBody from an InputStream with the provided AsyncRequestBodySplitConfiguration.
static AsyncRequestBody	fromPublisher(org.reactivestreams.Publisher<ByteBuffer> publisher)	Creates an AsyncRequestBody the produces data from the input ByteBuffer publisher.
static AsyncRequestBody	fromRemainingByteBuffer(ByteBuffer byteBuffer)	Creates an AsyncRequestBody from the remaining readable bytes from a ByteBuffer.
static AsyncRequestBody	fromRemainingByteBuffers(ByteBuffer... byteBuffers)	Creates an AsyncRequestBody from a ByteBuffer array.
static AsyncRequestBody	fromRemainingByteBuffersUnsafe(ByteBuffer... byteBuffers)	Creates an AsyncRequestBody from a ByteBuffer array without copying the contents of each ByteBuffer.
static AsyncRequestBody	fromRemainingByteBufferUnsafe(ByteBuffer byteBuffer)	Creates an AsyncRequestBody from a ByteBuffer without copying the contents of the ByteBuffer.
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.
default SdkPublisher<AsyncRequestBody>	split(Consumer<AsyncRequestBodySplitConfiguration.Builder> splitConfiguration)	This is a convenience method that passes an instance of the AsyncRequestBodySplitConfiguration builder, avoiding the need to create one manually via AsyncRequestBodySplitConfiguration.builder().
default SdkPublisher<AsyncRequestBody>	split(AsyncRequestBodySplitConfiguration splitConfiguration)	Converts this AsyncRequestBody to a publisher of AsyncRequestBodys, each of which publishes a specific portion of the original data, based on the provided AsyncRequestBodySplitConfiguration.

Methods inherited from interface org.reactivestreams.Publisher

subscribe

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

addTrailingData, buffer, doAfterOnCancel, doAfterOnComplete, doAfterOnError, filter, filter, flatMapIterable, limit, map, 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 fromFile(FileRequestBodyConfiguration) to create a customized body implementation.

Parameters:

file - The file to read from.

Returns:

Implementation of AsyncRequestBody that reads data from the specified file.

fromFile

static AsyncRequestBody fromFile(FileRequestBodyConfiguration configuration)

Creates an AsyncRequestBody that produces data from the contents of a file.

Parameters:

configuration - configuration for how the SDK should read the file

Returns:

Implementation of AsyncRequestBody that reads data from the specified file.

fromFile

static AsyncRequestBody fromFile(Consumer<FileRequestBodyConfiguration.Builder> configuration)

Creates an AsyncRequestBody that produces data from the contents of a file.

This is a convenience method that creates an instance of the FileRequestBodyConfiguration builder, avoiding the need to create one manually via FileRequestBodyConfiguration.builder().

Parameters:

configuration - configuration for how the SDK should read the file

Returns:

Implementation of AsyncRequestBody that reads data from the specified file.

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:

ByteBuffersAsyncRequestBody

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 an AsyncRequestBody from a byte array. This will copy the contents of the byte array to prevent modifications to the provided byte array from being reflected in the AsyncRequestBody.

Parameters:

bytes - The bytes to send to the service.

Returns:

AsyncRequestBody instance.

fromBytesUnsafe

static AsyncRequestBody fromBytesUnsafe(byte[] bytes)

Creates an AsyncRequestBody from a byte array without copying the contents of the byte array. This introduces concurrency risks, allowing: (1) the caller to modify the byte array stored in this AsyncRequestBody implementation AND (2) any users of fromBytesUnsafe(byte[]) to modify the byte array passed into this AsyncRequestBody implementation.

As the method name implies, this is unsafe. Use fromBytes(byte[]) unless you're sure you know the risks.

Parameters:

bytes - The bytes to send to the service.

Returns:

AsyncRequestBody instance.

fromByteBuffer

static AsyncRequestBody fromByteBuffer(ByteBuffer byteBuffer)

Creates an AsyncRequestBody from a ByteBuffer. This will copy the contents of the ByteBuffer to prevent modifications to the provided ByteBuffer from being reflected in the AsyncRequestBody.

NOTE: This method ignores the current read position. Use fromRemainingByteBuffer(ByteBuffer) if you need it to copy only the remaining readable bytes.

Parameters:

byteBuffer - ByteBuffer to send to the service.

Returns:

AsyncRequestBody instance.

fromRemainingByteBuffer

static AsyncRequestBody fromRemainingByteBuffer(ByteBuffer byteBuffer)

Creates an AsyncRequestBody from the remaining readable bytes from a ByteBuffer. This will copy the remaining contents of the ByteBuffer to prevent modifications to the provided ByteBuffer from being reflected in the AsyncRequestBody.

Unlike fromByteBuffer(ByteBuffer), this method respects the current read position of the buffer and reads only the remaining bytes.

Parameters:

byteBuffer - ByteBuffer to send to the service.

Returns:

AsyncRequestBody instance.

fromByteBufferUnsafe

static AsyncRequestBody fromByteBufferUnsafe(ByteBuffer byteBuffer)

Creates an AsyncRequestBody from a ByteBuffer without copying the contents of the ByteBuffer. This introduces concurrency risks, allowing the caller to modify the ByteBuffer stored in this AsyncRequestBody implementation.

NOTE: This method ignores the current read position. Use fromRemainingByteBufferUnsafe(ByteBuffer) if you need it to copy only the remaining readable bytes.

As the method name implies, this is unsafe. Use fromByteBuffer(ByteBuffer)} unless you're sure you know the risks.

Parameters:

byteBuffer - ByteBuffer to send to the service.

Returns:

AsyncRequestBody instance.

fromRemainingByteBufferUnsafe

static AsyncRequestBody fromRemainingByteBufferUnsafe(ByteBuffer byteBuffer)

Creates an AsyncRequestBody from a ByteBuffer without copying the contents of the ByteBuffer. This introduces concurrency risks, allowing the caller to modify the ByteBuffer stored in this AsyncRequestBody implementation.

Unlike fromByteBufferUnsafe(ByteBuffer), this method respects the current read position of the buffer and reads only the remaining bytes.

As the method name implies, this is unsafe. Use fromByteBuffer(ByteBuffer)} unless you're sure you know the risks.

Parameters:

byteBuffer - ByteBuffer to send to the service.

Returns:

AsyncRequestBody instance.

fromByteBuffers

static AsyncRequestBody fromByteBuffers(ByteBuffer... byteBuffers)

Creates an AsyncRequestBody from a ByteBuffer array. This will copy the contents of each ByteBuffer to prevent modifications to any provided ByteBuffer from being reflected in the AsyncRequestBody.

NOTE: This method ignores the current read position of each ByteBuffer. Use fromRemainingByteBuffers(ByteBuffer...) if you need it to copy only the remaining readable bytes.

Parameters:

byteBuffers - ByteBuffer array to send to the service.

Returns:

AsyncRequestBody instance.

fromRemainingByteBuffers

static AsyncRequestBody fromRemainingByteBuffers(ByteBuffer... byteBuffers)

Creates an AsyncRequestBody from a ByteBuffer array. This will copy the remaining contents of each ByteBuffer to prevent modifications to any provided ByteBuffer from being reflected in the AsyncRequestBody.

Unlike fromByteBufferUnsafe(ByteBuffer), this method respects the current read position of each buffer and reads only the remaining bytes.

Parameters:

byteBuffers - ByteBuffer array to send to the service.

Returns:

AsyncRequestBody instance.

fromByteBuffersUnsafe

static AsyncRequestBody fromByteBuffersUnsafe(ByteBuffer... byteBuffers)

Creates an AsyncRequestBody from a ByteBuffer array without copying the contents of each ByteBuffer. This introduces concurrency risks, allowing the caller to modify any ByteBuffer stored in this AsyncRequestBody implementation.

NOTE: This method ignores the current read position of each ByteBuffer. Use fromRemainingByteBuffers(ByteBuffer...) if you need it to copy only the remaining readable bytes.

As the method name implies, this is unsafe. Use fromByteBuffers(ByteBuffer...) unless you're sure you know the risks.

Parameters:

byteBuffers - ByteBuffer array to send to the service.

Returns:

AsyncRequestBody instance.

fromRemainingByteBuffersUnsafe

static AsyncRequestBody fromRemainingByteBuffersUnsafe(ByteBuffer... byteBuffers)

Creates an AsyncRequestBody from a ByteBuffer array without copying the contents of each ByteBuffer. This introduces concurrency risks, allowing the caller to modify any ByteBuffer stored in this AsyncRequestBody implementation.

Unlike fromByteBuffersUnsafe(ByteBuffer...), this method respects the current read position of each buffer and reads only the remaining bytes.

As the method name implies, this is unsafe. Use fromByteBuffers(ByteBuffer...) unless you're sure you know the risks.

Parameters:

byteBuffers - ByteBuffer array to send to the service.

Returns:

AsyncRequestBody instance.

fromInputStream

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

Creates an AsyncRequestBody from an 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.

fromInputStream

static AsyncRequestBody fromInputStream(AsyncRequestBodyFromInputStreamConfiguration configuration)

Creates an AsyncRequestBody from an InputStream with the provided AsyncRequestBodySplitConfiguration.

fromInputStream

static AsyncRequestBody fromInputStream(Consumer<AsyncRequestBodyFromInputStreamConfiguration.Builder> configuration)

This is a convenience method that passes an instance of the AsyncRequestBodyFromInputStreamConfiguration builder, avoiding the need to create one manually via AsyncRequestBodyFromInputStreamConfiguration.builder().

See Also:

fromInputStream(AsyncRequestBodyFromInputStreamConfiguration)

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 BlockingOutputStreamAsyncRequestBody.outputStream() when writing is complete.

Example Usage

empty

static AsyncRequestBody empty()

Creates an AsyncRequestBody with no content.

Returns:

AsyncRequestBody instance.

split

default SdkPublisher<AsyncRequestBody> split(AsyncRequestBodySplitConfiguration splitConfiguration)

Converts this AsyncRequestBody to a publisher of AsyncRequestBodys, each of which publishes a specific portion of the original data, based on the provided AsyncRequestBodySplitConfiguration. The default chunk size is 2MB and the default buffer size is 8MB.

By default, if content length of this AsyncRequestBody is present, each divided AsyncRequestBody is delivered to the subscriber right after it's initialized. On the other hand, if content length is null, it is sent after the entire content for that chunk is buffered. In this case, the configured maxMemoryUsageInBytes must be larger than or equal to chunkSizeInBytes. Note that this behavior may be different if a specific implementation of this interface overrides this method.

See Also:

AsyncRequestBodySplitConfiguration

split

default SdkPublisher<AsyncRequestBody> split(Consumer<AsyncRequestBodySplitConfiguration.Builder> splitConfiguration)

This is a convenience method that passes an instance of the AsyncRequestBodySplitConfiguration builder, avoiding the need to create one manually via AsyncRequestBodySplitConfiguration.builder().

See Also:

split(AsyncRequestBodySplitConfiguration)