Package io.helidon.common.http

Interface DataChunk

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 DataChunk

The DataChunk represents a part of the HTTP body content.

The DataChunk and the content it carries stay immutable as long as method release() is not called. After that, the given instance and the associated data structure instances (e.g., the ByteBuffer obtained by data()) should not be used. The idea behind this class is to be able to minimize data copying; ideally, in order to achieve the best performance, to not copy them at all. However, the implementations may choose otherwise.

The instances of this class are expected to be accessed by a single thread. Calling the methods of this class (such as data(), release() from different threads may result in a race condition unless an external synchronization is used.

Method Summary

Modifier and Type	Method and Description
default byte[]	bytes() Gets the content of the underlying ByteBuffer as an array of bytes.
static DataChunk	create(boolean flush, ByteBuffer data) Creates a reusable data chunk.
static DataChunk	create(boolean flush, ByteBuffer data, Runnable releaseCallback) Creates a reusable data chunk.
static DataChunk	create(byte[] bytes) Creates a simple byte array backed data chunk.
static DataChunk	create(ByteBuffer byteBuffer) Creates a simple ByteBuffer backed data chunk.
ByteBuffer	data() Returns a representation of this chunk as a ByteBuffer.
default boolean	flush() Returns true if all caches are requested to flush when this chunk is written.
default long	id() The tracing ID of this chunk.
default boolean	isReleased() Whether this chunk is released and the associated data structures returned by methods (such as data() or bytes()) should not be used.
default void	release() Releases this chunk.

Method Detail

create

static DataChunk create(ByteBuffer byteBuffer)

Creates a simple ByteBuffer backed data chunk. The resulting instance doesn't have any kind of a lifecycle and as such, it doesn't need to be released.

Parameters:

byteBuffer - a byte buffer to create the request chunk from

Returns:

a request chunk

create

static DataChunk create(byte[] bytes)

Creates a simple byte array backed data chunk. The resulting instance doesn't have any kind of a lifecycle and as such, it doesn't need to be released.

Parameters:

bytes - a byte array to create the request chunk from

Returns:

a request chunk

create

static DataChunk create(boolean flush,
                        ByteBuffer data)

Creates a reusable data chunk.

Parameters:

flush - a signal that chunk should be written and flushed from any cache if possible

data - a data chunk. Should not be reused until releaseCallback is used

Returns:

a reusable data chunk with no release callback

create

static DataChunk create(boolean flush,
                        ByteBuffer data,
                        Runnable releaseCallback)

Creates a reusable data chunk.

Parameters:

flush - a signal that chunk should be written and flushed from any cache if possible

data - a data chunk. Should not be reused until releaseCallback is used

releaseCallback - a callback which is called when this chunk is completely processed and instance is free for reuse

Returns:

a reusable data chunk with a release callback

data

ByteBuffer data()

Returns a representation of this chunk as a ByteBuffer. Multiple calls of this method always return the same ByteBuffer instance. As such, when the buffer is read, the subsequent call of the data() returns a buffer that is also already read.

It is expected the returned ByteBuffer holds a reference to data that will become stale upon calling method release(). (For instance, the memory segment is pooled by the underlying TCP server and is reused for a subsequent request chunk.) The idea behind this class is to be able to minimize data copying; ideally, in order to achieve the best performance, to not copy them at all. However, the implementations may choose otherwise.

Note that the methods of this instance are expected to be called by a single thread; if not, external synchronization must be used.

Returns:

a ByteBuffer representation of this chunk that is guarantied to stay immutable as long as method release() is not called

id

default long id()

The tracing ID of this chunk.

Returns:

the tracing ID of this chunk

bytes

default byte[] bytes()

Gets the content of the underlying ByteBuffer as an array of bytes. If the the ByteBuffer was read, the returned array contains only the part of data that wasn't read yet. On the other hand, calling this method doesn't cause the underlying ByteBuffer to be read.

It is expected the returned byte array holds a reference to data that will become stale upon calling method release(). (For instance, the memory segment is pooled by the underlying TCP server and is reused for a subsequent request chunk.) The idea behind this class is to be able to minimize data copying; ideally, in order to achieve the best performance, to not copy them at all. However, the implementations may choose otherwise.

Note that the methods of this instance are expected to be called by a single thread; if not, external synchronization must be used.

Returns:

an array of bytes that is guarantied to stay immutable as long as method release() is not called

isReleased

default boolean isReleased()

Whether this chunk is released and the associated data structures returned by methods (such as data() or bytes()) should not be used. The implementations may choose to not implement this optimization and to never mutate the underlying memory; in such case this method does no-op.

Note that the methods of this instance are expected to be called by a single thread; if not, external synchronization must be used.

Returns:

whether this chunk has been released, defaults to false

release

default void release()

Releases this chunk. The underlying data as well as the data structure instances returned by methods bytes() and data() may become stale and should not be used anymore. The implementations may choose to not implement this optimization and to never mutate the underlying memory; in such case this method does no-op.

Note that the methods of this instance are expected to be called by a single thread; if not, external synchronization must be used.

flush

default boolean flush()

Returns true if all caches are requested to flush when this chunk is written. This method is only meaningful when handing data over to Helidon APIs (e.g. for server response and client requests).

Returns:

true if it is requested to flush all caches after this chunk is written, defaults to false.