com.ibm.cos.v2.core.sync

Class RequestBody

java.lang.Object

com.ibm.cos.v2.core.sync.RequestBody

public class RequestBody
extends Object

Represents the body of an HTTP request. Must be provided for operations that have a streaming input. Offers various convenience factory methods from common sources of data (File, String, byte[], etc).

This class is NOT intended to be overridden.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RequestBody(ContentStreamProvider contentStreamProvider, Long contentLength, String contentType)

Method Summary

Modifier and Type	Method and Description
long	contentLength() Deprecated. by optionalContentLength()
ContentStreamProvider	contentStreamProvider()
String	contentType()
static RequestBody	empty() Creates a RequestBody with no content.
static RequestBody	fromByteBuffer(ByteBuffer byteBuffer) Creates a RequestBody from a ByteBuffer.
static RequestBody	fromBytes(byte[] bytes) Creates a RequestBody from a byte array.
static RequestBody	fromContentProvider(ContentStreamProvider provider, long contentLength, String mimeType) Creates a RequestBody from the given ContentStreamProvider.
static RequestBody	fromContentProvider(ContentStreamProvider provider, String mimeType) Creates a RequestBody from the given ContentStreamProvider when the content length is unknown.
static RequestBody	fromFile(File file) Create a RequestBody using the full contents of the specified file.
static RequestBody	fromFile(Path path) Create a RequestBody using the full contents of the specified file.
static RequestBody	fromInputStream(InputStream inputStream, long contentLength) Creates a RequestBody from an input stream.
static RequestBody	fromRemainingByteBuffer(ByteBuffer byteBuffer) Creates a RequestBody from the remaining readable bytes from a ByteBuffer.
static RequestBody	fromString(String contents) Creates a RequestBody from a string.
static RequestBody	fromString(String contents, Charset cs) Creates a RequestBody from a string.
Optional<Long>	optionalContentLength()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RequestBody

protected RequestBody(ContentStreamProvider contentStreamProvider,
                      Long contentLength,
                      String contentType)

Method Detail

contentStreamProvider

public final ContentStreamProvider contentStreamProvider()

Returns:

RequestBody as an InputStream.

contentLength

@Deprecated
public final long contentLength()

Deprecated. by optionalContentLength()

Returns:

Content length of RequestBody.

optionalContentLength

public final Optional<Long> optionalContentLength()

Returns:

Optional object of content length of RequestBody.

contentType

public final String contentType()

Returns:

Content type of RequestBody.

fromFile

public static RequestBody fromFile(Path path)

Create a RequestBody using the full contents of the specified file.

Parameters:

path - File to send to the service.

Returns:

RequestBody instance.

fromFile

public static RequestBody fromFile(File file)

Create a RequestBody using the full contents of the specified file.

Parameters:

file - File to send to the service.

Returns:

RequestBody instance.

fromInputStream

public static RequestBody fromInputStream(InputStream inputStream,
                                          long contentLength)

Creates a RequestBody from an input stream. must be provided so that the SDK does not have to make two passes of the data.

The stream will not be closed by the SDK. It is up to to caller of this method to close the stream. The stream should not be read outside of the SDK (by another thread) as it will change the state of the InputStream and could tamper with the sending of the request.

To support resetting via ContentStreamProvider, this uses InputStream.reset() and uses a read limit of 128 KiB. If you need more control, use fromContentProvider(ContentStreamProvider, long, String) or fromContentProvider(ContentStreamProvider, String).

Parameters:

inputStream - Input stream to send to the service. The stream will not be closed by the SDK.

contentLength - Content length of data in input stream. If a content length smaller than the actual size of the object is set, the client will truncate the stream to the specified content length and only send exactly the number of bytes equal to the content length.

Returns:

RequestBody instance.

fromString

public static RequestBody fromString(String contents,
                                     Charset cs)

Creates a RequestBody from a string. String is sent using the provided encoding.

Parameters:

contents - String to send to the service.

cs - The Charset to use.

Returns:

RequestBody instance.

fromString

public static RequestBody fromString(String contents)

Creates a RequestBody from a string. String is sent as UTF-8 encoded bytes.

Parameters:

contents - String to send to the service.

Returns:

RequestBody instance.

fromBytes

public static RequestBody fromBytes(byte[] bytes)

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

Parameters:

bytes - The bytes to send to the service.

Returns:

RequestBody instance.

fromByteBuffer

public static RequestBody fromByteBuffer(ByteBuffer byteBuffer)

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

NOTE: This method always copies the entire contents of the buffer, ignoring 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:

RequestBody instance.

fromRemainingByteBuffer

public static RequestBody fromRemainingByteBuffer(ByteBuffer byteBuffer)

Creates a RequestBody from the remaining readable bytes from a ByteBuffer. Unlike fromByteBuffer(ByteBuffer), this method respects the current read position of the buffer and reads only the remaining bytes. The buffer is copied before reading so no changes are made to original buffer.

Parameters:

byteBuffer - ByteBuffer to send to the service.

Returns:

RequestBody instance.

empty

public static RequestBody empty()

Creates a RequestBody with no content.

Returns:

RequestBody instance.

fromContentProvider

public static RequestBody fromContentProvider(ContentStreamProvider provider,
                                              long contentLength,
                                              String mimeType)

Creates a RequestBody from the given ContentStreamProvider.

If you are using this in conjunction with S3 and want to upload a stream with an unknown content length, you can refer S3's documentation for alternative methods.

If a content length smaller than the actual size of the object is set, the client will truncate the stream to the specified content length and only send exactly the number of bytes equal to the content length.

Parameters:

provider - The content provider.

contentLength - The content length. If a content length smaller than the actual size of the object is set, the client will truncate the stream to the specified content length and only send exactly the number of bytes equal to the content length.

mimeType - The MIME type of the content.

Returns:

The created RequestBody.

fromContentProvider

public static RequestBody fromContentProvider(ContentStreamProvider provider,
                                              String mimeType)

Creates a RequestBody from the given ContentStreamProvider when the content length is unknown.

Important: Be aware that this implementation requires buffering the contents for ContentStreamProvider, which can cause increased memory usage.

If you are using this in conjunction with S3 and want to upload a stream with an unknown content length, you can refer S3's documentation for alternative methods.

Parameters:

provider - The content provider.

mimeType - The MIME type of the content.

Returns:

The created RequestBody.