Package com.linecorp.armeria.common

Interface HttpData

All Superinterfaces:

AutoCloseable, HttpObject, SafeCloseable

public interface HttpData
extends HttpObject, SafeCloseable

HTTP/2 data that contains a chunk of bytes.

Method Summary

Modifier and Type	Method	Description
byte[]	array()	Returns the underlying byte array of this data.
default ByteBuf	byteBuf()	(Advanced users only) Returns a new duplicate of the underlying ByteBuf of this data.
ByteBuf	byteBuf(int offset, int length, ByteBufAccessMode mode)	(Advanced users only) Returns a new slice, retained slice or direct copy of the underlying ByteBuf of this data based on the specified ByteBufAccessMode.
ByteBuf	byteBuf(ByteBufAccessMode mode)	(Advanced users only) Returns a new duplicate, retained duplicate or direct copy of the underlying ByteBuf of this data based on the specified ByteBufAccessMode.
void	close()	Releases the underlying ByteBuf if this data was created via wrap(ByteBuf).
static HttpData	copyOf(byte[] data)	Creates a new instance from the specified byte array by first copying it.
static HttpData	copyOf(byte[] data, int offset, int length)	Creates a new instance from the specified byte array, offset and length by first copying it.
static HttpData	copyOf(ByteBuf data)	Creates a new instance from the specified ByteBuf by first copying its content.
static HttpData	empty()	Returns an empty HttpData.
default boolean	isEmpty()	Returns whether the length() of this data is 0.
boolean	isPooled()	(Advanced users only) Returns whether this data is pooled.
int	length()	Returns the length of this data.
static HttpData	of(Charset charset, CharSequence text)	Converts the specified text into an HttpData.
static HttpData	of(Charset charset, String text)	Converts the specified text into an HttpData.
static HttpData	of(Charset charset, String format, Object... args)	Converts the specified formatted string into an HttpData.
static HttpData	ofAscii(CharSequence text)	Converts the specified text into a US-ASCII HttpData.
static HttpData	ofAscii(String text)	Converts the specified text into a US-ASCII HttpData.
static HttpData	ofAscii(String format, Object... args)	Converts the specified formatted string into a US-ASCII HttpData.
static HttpData	ofUtf8(CharSequence text)	Converts the specified text into a UTF-8 HttpData.
static HttpData	ofUtf8(String text)	Converts the specified text into a UTF-8 HttpData.
static HttpData	ofUtf8(String format, Object... args)	Converts the specified formatted string into a UTF-8 HttpData.
InputStream	toInputStream()	Returns a new InputStream that is sourced from this data.
default Reader	toReader(Charset charset)	Returns a new Reader that is sourced from this data and decoded using the specified Charset.
default Reader	toReaderAscii()	Returns a new Reader that is sourced from this data and decoded using StandardCharsets.US_ASCII.
default Reader	toReaderUtf8()	Returns a new Reader that is sourced from this data and decoded using StandardCharsets.UTF_8.
String	toString(Charset charset)	Decodes this data into a String.
default String	toStringAscii()	Decodes this data into a String using US-ASCII encoding.
default String	toStringUtf8()	Decodes this data into a String using UTF-8 encoding.
default void	touch(@Nullable Object hint)	(Advanced users only) Records the current access location of this data for debugging purposes.
default HttpData	withEndOfStream()	Returns the HttpData that has the same content with this data and its HTTP/2 endOfStream flag set.
HttpData	withEndOfStream(boolean endOfStream)	Returns the HttpData that has the same content with this data and its HTTP/2 endOfStream flag set with the specified value.
static HttpData	wrap(byte[] data)	Creates a new instance from the specified byte array.
static HttpData	wrap(byte[] data, int offset, int length)	Creates a new instance from the specified byte array, offset and length.
static HttpData	wrap(ByteBuf buf)	(Advanced users only) Converts the specified Netty ByteBuf into a pooled HttpData.

Methods inherited from interface com.linecorp.armeria.common.HttpObject

isEndOfStream

Method Details

empty

static HttpData empty()

Returns an empty HttpData.

wrap

static HttpData wrap(byte[] data)

Creates a new instance from the specified byte array. The array is not copied; any changes made in the array later will be visible to HttpData.

Returns:

a new HttpData. empty() if the length of the specified array is 0.

wrap

static HttpData wrap(byte[] data,
 int offset,
 int length)

Creates a new instance from the specified byte array, offset and length. The array is not copied; any changes made in the array later will be visible to HttpData.

Returns:

a new HttpData. empty() if length is 0.

Throws:

IndexOutOfBoundsException - if offset and length are out of bounds

wrap

@UnstableApi
static HttpData wrap(ByteBuf buf)

(Advanced users only) Converts the specified Netty ByteBuf into a pooled HttpData. The buffer is not copied; any changes made to it will be visible to HttpData. The ownership of the buffer is transferred to the HttpData. If you still need to use it after calling this method, make sure to call ByteBuf.retain() first.

Returns:

a new HttpData. empty() if the readable bytes of buf is 0.

See Also:

PooledObjects

copyOf

static HttpData copyOf(byte[] data)

Creates a new instance from the specified byte array by first copying it.

Returns:

a new HttpData. empty() if the length of the specified array is 0.

copyOf

static HttpData copyOf(byte[] data,
 int offset,
 int length)

Creates a new instance from the specified byte array, offset and length by first copying it.

Returns:

a new HttpData. empty() if length is 0.

Throws:

ArrayIndexOutOfBoundsException - if offset and length are out of bounds

copyOf

static HttpData copyOf(ByteBuf data)

Creates a new instance from the specified ByteBuf by first copying its content. The reference count of ByteBuf will not be changed.

Returns:

a new HttpData. empty() if the length of the specified array is 0.

of

static HttpData of(Charset charset,
 CharSequence text)

Converts the specified text into an HttpData.

Parameters:

charset - the Charset to use for encoding text

text - the String to convert

Returns:

a new HttpData. empty() if the length of text is 0.

of

static HttpData of(Charset charset,
 String text)

Converts the specified text into an HttpData.

Parameters:

charset - the Charset to use for encoding text

text - the String to convert

Returns:

a new HttpData. empty() if the length of text is 0.

of

@FormatMethod
static HttpData of(Charset charset,
 @FormatString
 String format,
 Object... args)

Converts the specified formatted string into an HttpData. The string is formatted by String.format(Locale, String, Object...) with English locale.

Parameters:

charset - the Charset to use for encoding string

format - the format string of the response content

args - the arguments referenced by the format specifiers in the format string

Returns:

a new HttpData. empty() if format is empty.

ofUtf8

static HttpData ofUtf8(CharSequence text)

Converts the specified text into a UTF-8 HttpData.

Parameters:

text - the String to convert

Returns:

a new HttpData. empty() if the length of text is 0.

ofUtf8

static HttpData ofUtf8(String text)

Converts the specified text into a UTF-8 HttpData.

Parameters:

text - the String to convert

Returns:

a new HttpData. empty() if the length of text is 0.

ofUtf8

@FormatMethod
static HttpData ofUtf8(@FormatString
 String format,
 Object... args)

Converts the specified formatted string into a UTF-8 HttpData. The string is formatted by String.format(Locale, String, Object...) with English locale.

Parameters:

format - the format string of the response content

args - the arguments referenced by the format specifiers in the format string

Returns:

a new HttpData. empty() if format is empty.

ofAscii

static HttpData ofAscii(CharSequence text)

Converts the specified text into a US-ASCII HttpData.

Parameters:

text - the String to convert

Returns:

a new HttpData. empty() if the length of text is 0.

ofAscii

static HttpData ofAscii(String text)

Converts the specified text into a US-ASCII HttpData.

Parameters:

text - the String to convert

Returns:

a new HttpData. empty() if the length of text is 0.

ofAscii

@FormatMethod
static HttpData ofAscii(@FormatString
 String format,
 Object... args)

Converts the specified formatted string into a US-ASCII HttpData. The string is formatted by String.format(Locale, String, Object...) with English locale.

Parameters:

format - the format string of the response content

args - the arguments referenced by the format specifiers in the format string

Returns:

a new HttpData. empty() if format is empty.

array

byte[] array()

Returns the underlying byte array of this data. Any changes made in the returned array affects the content of this data.

length

int length()

Returns the length of this data.

isEmpty

default boolean isEmpty()

Returns whether the length() of this data is 0.

toString

String toString(Charset charset)

Decodes this data into a String.

Parameters:

charset - the Charset to use for decoding this data

Returns:

the decoded String

toStringUtf8

default String toStringUtf8()

Decodes this data into a String using UTF-8 encoding.

Returns:

the decoded String

toStringAscii

default String toStringAscii()

Decodes this data into a String using US-ASCII encoding.

Returns:

the decoded String

toInputStream

InputStream toInputStream()

Returns a new InputStream that is sourced from this data.

toReader

default Reader toReader(Charset charset)

Returns a new Reader that is sourced from this data and decoded using the specified Charset.

toReaderUtf8

default Reader toReaderUtf8()

Returns a new Reader that is sourced from this data and decoded using StandardCharsets.UTF_8.

toReaderAscii

default Reader toReaderAscii()

Returns a new Reader that is sourced from this data and decoded using StandardCharsets.US_ASCII.

withEndOfStream

default HttpData withEndOfStream()

Returns the HttpData that has the same content with this data and its HTTP/2 endOfStream flag set. If this data already has endOfStream set, this will be returned.

withEndOfStream

HttpData withEndOfStream(boolean endOfStream)

Returns the HttpData that has the same content with this data and its HTTP/2 endOfStream flag set with the specified value. If this data already has the same endOfStream value set, this will be returned.

isPooled

@UnstableApi
boolean isPooled()

(Advanced users only) Returns whether this data is pooled. Note, if this method returns true, you must call close() once you no longer need this data, because its underlying ByteBuf will not be released automatically.

See Also:

PooledObjects

byteBuf

@UnstableApi
default ByteBuf byteBuf()

(Advanced users only) Returns a new duplicate of the underlying ByteBuf of this data. This method does not transfer the ownership of the underlying ByteBuf, i.e. the reference count of the ByteBuf does not change. If this data is not pooled, the returned ByteBuf is not pooled, either, which means you need to worry about releasing it only when you created this data with wrap(ByteBuf). Any changes made in the content of the returned ByteBuf affects the content of this data.

See Also:

PooledObjects

byteBuf

@UnstableApi
ByteBuf byteBuf(ByteBufAccessMode mode)

(Advanced users only) Returns a new duplicate, retained duplicate or direct copy of the underlying ByteBuf of this data based on the specified ByteBufAccessMode. This method does not transfer the ownership of the underlying ByteBuf, i.e. the reference count of the ByteBuf does not change. If this data is not pooled, the returned ByteBuf is not pooled, either, which means you need to worry about releasing it only when you created this data with wrap(ByteBuf). Any changes made in the content of the returned ByteBuf affects the content of this data.

See Also:

PooledObjects

byteBuf

@UnstableApi
ByteBuf byteBuf(int offset,
 int length,
 ByteBufAccessMode mode)

(Advanced users only) Returns a new slice, retained slice or direct copy of the underlying ByteBuf of this data based on the specified ByteBufAccessMode. This method does not transfer the ownership of the underlying ByteBuf, i.e. the reference count of the ByteBuf does not change. If this data is not pooled, the returned ByteBuf is not pooled, either, which means you need to worry about releasing it only when you created this data with wrap(ByteBuf). Any changes made in the content of the returned ByteBuf affects the content of this data.

See Also:

PooledObjects

touch

@UnstableApi
default void touch(@Nullable
 @Nullable Object hint)

(Advanced users only) Records the current access location of this data for debugging purposes. If this data is determined to be leaked, the information recorded by this operation will be provided to you via ResourceLeakDetector.

close

void close()

Releases the underlying ByteBuf if this data was created via wrap(ByteBuf). Otherwise, this method does nothing. You may want to call this method to reclaim the underlying ByteBuf when using operations that return pooled objects, such as:

• StreamMessage.subscribe(Subscriber, SubscriptionOption...) with SubscriptionOption.WITH_POOLED_OBJECTS
• HttpRequest.aggregateWithPooledObjects(ByteBufAllocator)
• HttpResponse.aggregateWithPooledObjects(ByteBufAllocator)
• HttpFile.aggregateWithPooledObjects(Executor, ByteBufAllocator)

If you don't use such operations, you don't need to call this method.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface SafeCloseable

See Also:

PooledObjects