Class ReadBuffer

java.lang.Object
io.micronaut.core.io.buffer.ReadBuffer
All Implemented Interfaces:
AutoCloseable
public abstract class ReadBuffer extends Object implements AutoCloseable
A buffer of bytes. Can be read from exactly once. Must be either consumed fully, or closed.

Consuming operations

Certain operations on ReadBuffers are consuming, meaning that they read all the remaining bytes in the buffer. Those operations are called out in the javadoc. After such an operation, the buffer does not need to be closed (though it's still allowed to do so).

Since:
4.10.0
Author:
Jonas Konrad

  • Constructor Details

    • ReadBuffer

      @Internal protected ReadBuffer()
      Internal constructor. Extension is only allowed in micronaut-core.

  • Method Details

    • readable

      public abstract int readable()
      Returns the number of bytes that can be read from this buffer.
      Returns:
      The number of readable bytes
      Throws:
      IllegalStateException - If this buffer is already closed or consumed

    • duplicate

      public abstract ReadBuffer duplicate()
      Create a new independent buffer that reads the same data as this one. This buffer remains unchanged.
      Returns:
      A new, independent buffer
      Throws:
      IllegalStateException - If this buffer is already closed or consumed

    • split

      public abstract ReadBuffer split(int splitPosition) throws IndexOutOfBoundsException
      Split this buffer in two, returning the bytes up until splitPosition as a new buffer. Those bytes will be removed from this buffer. This is not a consuming operation, even if n == readable().
      Parameters:
      splitPosition - Position where to split the data
      Returns:
      A new, independent buffer that reads the first splitPosition bytes
      Throws:
      IllegalStateException - If this buffer is already closed or consumed
      IndexOutOfBoundsException - If n > readable()

    • move

      public abstract ReadBuffer move()
      Create a new buffer with the same content as this one, consuming this buffer in the process. If this buffer is later closed, the returned buffer remains usable.

      This is a consuming operation.

      Returns:
      a new ReadBuffer containing all the bytes that were previously in this ReadBuffer
      Throws:
      IllegalStateException - If this buffer is already closed or consumed

    • toArray

      public abstract void toArray(byte[] destination, int offset) throws IndexOutOfBoundsException
      Reads the contents of this ReadBuffer into the specified destination array, which must have enough space for this buffer.

      This is a consuming operation.

      Parameters:
      destination - the byte array to copy the contents into
      offset - the starting index in the destination array
      Throws:
      IllegalStateException - If this buffer is already closed or consumed
      IndexOutOfBoundsException - if the destination array is not large enough to hold the contents of this ReadBuffer, or if the offset is negative or exceeds the destination array's length

    • toArray

      public byte[] toArray()
      Returns the contents of this ReadBuffer as a byte array. Some implementations may share the array with other buffers, so the returned array should not be written to.

      This is a consuming operation.

      Returns:
      a byte array containing the contents of this ReadBuffer
      Throws:
      IllegalStateException - If this buffer is already closed or consumed

    • toString

      public String toString(Charset charset)
      Returns the contents of this ReadBuffer as a string.

      This is a consuming operation.

      Parameters:
      charset - the character encoding to use for converting the bytes to a string
      Returns:
      a string representation of the contents of this ReadBuffer
      Throws:
      IllegalStateException - If this buffer is already closed or consumed

    • toByteBuffer

      public ByteBuffer<?> toByteBuffer()
      Converts this ReadBuffer into a ByteBuffer. The returned ByteBuffer will contain all the readable bytes from this ReadBuffer.

      This is a consuming operation.

      Returns:
      a ByteBuffer containing the contents of this ReadBuffer
      Throws:
      IllegalStateException - If this buffer is already closed or consumed

    • toInputStream

      public InputStream toInputStream()
      Create a new InputStream that reads the data of this buffer. The returned stream must be closed.

      This is a consuming operation.

      Returns:
      A stream reading from this buffer
      Throws:
      IllegalStateException - If this buffer is already closed or consumed

    • useFastHeapBuffer

      public <R> @Nullable R useFastHeapBuffer(Function<ByteBuffer, R> function)
      Access the contents of this buffer as a ByteBuffer with ByteBuffer.hasArray(), if doing so is possible without copying the data. The lifetime of the buffer is limited to the function scope, user code must not keep it around. User code must also never modify the backing array of the buffer.

      This is useful for performing operations on the data that can take a (array, offset, length) parameter, such as OutputStream.write(byte[], int, int) or serialization.

      This is a consuming operation if the function is called.

      Type Parameters:
      R - The return type of the function
      Parameters:
      function - A function to call with a nio buffer view of this ReadBuffer, if possible
      Returns:
      The return value of the function, or null if this buffer cannot be accessed using a nio buffer
      Throws:
      IllegalStateException - If this buffer is already closed or consumed
      Since:
      5.0.0

    • transferTo

      public void transferTo(OutputStream stream) throws IOException
      Write this buffer to the given OutputStream.

      This is a consuming operation.

      Parameters:
      stream - The stream to write to
      Throws:
      IllegalStateException - If this buffer is already closed or consumed
      IOException - If the OutputStream throws an exception

    • close

      public abstract void close()
      Closes this ReadBuffer, releasing any system resources associated with it. May be called multiple times without effect. Note that consuming operations implicitly close the buffer as well.
      Specified by:
      close in interface AutoCloseable

    • isConsumed

      protected abstract boolean isConsumed()

    • peekArray

      protected abstract byte[] peekArray(int n)

    • toString

      public String toString()
      Overrides:
      toString in class Object