Module io.helidon.common.http
Package io.helidon.common.http

Interface DataChunk

All Superinterfaces:
Iterable<ByteBuffer>
All Known Implementing Classes:
ByteBufDataChunk
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 extends Iterable<ByteBuffer>
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 array 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
    Description
    default byte[]
    bytes()
    Gets the content of the underlying byte buffers as an array of bytes.
    static DataChunk
    create(boolean flush, boolean readOnly, Runnable releaseCallback, ByteBuffer... byteBuffers)
    Creates a reusable byteBuffers chunk.
    static DataChunk
    create(boolean flush, boolean readOnly, ByteBuffer... byteBuffers)
    Creates a reusable data chunk.
    static DataChunk
    create(boolean flush, Runnable releaseCallback, ByteBuffer... byteBuffers)
    Creates a reusable byteBuffers chunk.
    static DataChunk
    create(boolean flush, ByteBuffer... byteBuffers)
    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.
    static DataChunk
    create(ByteBuffer... byteBuffers)
    Creates a data chunk backed by one or more ByteBuffer.
    ByteBuffer[]
    data()
    Returns a representation of this chunk as an array of ByteBuffer.
    default <T> T[]
    data(Class<T> clazz)
    Returns a representation of this chunk as an array of T's.
    default DataChunk
    duplicate()
    Makes a copy of this data chunk including its underlying 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 <T> boolean
    isBackedBy(Class<T> clazz)
    Checks if this instance is backed by buffers of a certain kind.
    default boolean
    isFlushChunk()
    An empty data chunk with a flush flag can be used to force a connection flush without actually writing any bytes.
    default boolean
    isReadOnly()
    Returns true if the underlying byte buffer of this chunk is read only or false otherwise.
    default boolean
    isReleased()
    Whether this chunk is released and the associated data structures returned by methods (such as iterator() or bytes()) should not be used.
    default Iterator<ByteBuffer>
    iterator()
     
    default void
    release()
    Releases this chunk.
    default int
    remaining()
    Returns the sum of elements between the current position and the limit of each of the underlying ByteBuffer.
    default Optional<CompletableFuture<DataChunk>>
    writeFuture()
    Returns a write future associated with this chunk.
    default void
    writeFuture(CompletableFuture<DataChunk> writeFuture)
    Set a write future that will complete when data chunk has been written to a connection.

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Method Details

    • 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 data 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 data chunk

    • create

      static DataChunk create(ByteBuffer... byteBuffers)
      Creates a data chunk backed by one or more ByteBuffer. The resulting instance doesn't have any kind of a lifecycle and as such, it doesn't need to be released.
      Parameters:
      byteBuffers - the data for the chunk
      Returns:
      a data chunk

    • create

      static DataChunk create(boolean flush, ByteBuffer... byteBuffers)
      Creates a reusable data chunk.
      Parameters:
      flush - a signal that this chunk should be written and flushed from any cache if possible
      byteBuffers - the data for this chunk. Should not be reused until releaseCallback is used
      Returns:
      a reusable data chunk with no release callback

    • create

      static DataChunk create(boolean flush, boolean readOnly, ByteBuffer... byteBuffers)
      Creates a reusable data chunk.
      Parameters:
      flush - a signal that this chunk should be written and flushed from any cache if possible
      readOnly - indicates underlying buffers are not reused
      byteBuffers - the data for this chunk. Should not be reused until releaseCallback is used
      Returns:
      a reusable data chunk with no release callback

    • create

      static DataChunk create(boolean flush, Runnable releaseCallback, ByteBuffer... byteBuffers)
      Creates a reusable byteBuffers chunk.
      Parameters:
      flush - a signal that this chunk should be written and flushed from any cache if possible
      releaseCallback - a callback which is called when this chunk is completely processed and instance is free for reuse
      byteBuffers - the data for this chunk. Should not be reused until releaseCallback is used
      Returns:
      a reusable data chunk with a release callback

    • create

      static DataChunk create(boolean flush, boolean readOnly, Runnable releaseCallback, ByteBuffer... byteBuffers)
      Creates a reusable byteBuffers chunk.
      Parameters:
      flush - a signal that this chunk should be written and flushed from any cache if possible
      readOnly - indicates underlying buffers are not reused
      byteBuffers - the data for this 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 an array of ByteBuffer.

      It is expected the returned byte buffers hold references 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 ByteBuffer representing the data of this chunk that are guarantied to stay immutable as long as method release() is not called

    • data

      default <T> T[] data(Class<T> clazz)
      Returns a representation of this chunk as an array of T's.
      Type Parameters:
      T - the buffer type
      Parameters:
      clazz - class of return type
      Returns:
      an array of T's

    • isBackedBy

      default <T> boolean isBackedBy(Class<T> clazz)
      Checks if this instance is backed by buffers of a certain kind.
      Type Parameters:
      T - the buffer type
      Parameters:
      clazz - a buffer class instance
      Returns:
      outcome of test

    • remaining

      default int remaining()
      Returns the sum of elements between the current position and the limit of each of the underlying ByteBuffer.
      Returns:
      The number of elements remaining in all underlying buffers

    • iterator

      default Iterator<ByteBuffer> iterator()
      Specified by:
      iterator in interface Iterable<ByteBuffer>

    • 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 byte buffers as an array of bytes. The returned array contains only the part of data that wasn't read yet. Calling this method doesn't cause the underlying byte buffers 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 iterator() 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 iterator() 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.

    • duplicate

      default DataChunk duplicate()
      Makes a copy of this data chunk including its underlying ByteBuffer. This may be necessary for caching in case ByteBuffer.rewind() is called to reuse a byte buffer. Note that only the actual bytes used in the data chunk are copied, the resulting data chunk's capacity may be less than the original.
      Returns:
      A copy of this data chunk.

    • isReadOnly

      default boolean isReadOnly()
      Returns true if the underlying byte buffer of this chunk is read only or false otherwise.
      Returns:
      Immutability outcome.

    • isFlushChunk

      default boolean isFlushChunk()
      An empty data chunk with a flush flag can be used to force a connection flush without actually writing any bytes. This method determines if this chunk is used for that purpose.
      Returns:
      Outcome of test.

    • writeFuture

      default void writeFuture(CompletableFuture<DataChunk> writeFuture)
      Set a write future that will complete when data chunk has been written to a connection.
      Parameters:
      writeFuture - Write future.

    • writeFuture

      default Optional<CompletableFuture<DataChunk>> writeFuture()
      Returns a write future associated with this chunk.
      Returns:
      Write future if one has ben set.