Class VarFieldWriter

java.lang.Object
express.mvp.roray.utils.memory.VarFieldWriter
public final class VarFieldWriter extends Object
A specialized writer for building messages with variable-length fields in a flyweight-compatible format.

Layout: 

[Fixed Header]
[Variable Field Headers: offset:int32, length:int32 pairs]
[Variable Field Data]

Zero-Copy Design: This writer produces data that can be read via flyweight accessors without any heap allocation or copying. Variable fields are accessed via offset/length pointers stored in the header section.

Usage Pattern: 

// Setup
VarFieldWriter writer = new VarFieldWriter(segment, fixedHeaderSize, maxVarFields);

// Write fixed header fields
writer.writeByte(0, messageType);
writer.writeIntLE(1, requestId);

// Reserve slots for variable fields
int keySlot = writer.reserveVarField();
int valueSlot = writer.reserveVarField();

// Write variable field data
writer.writeVarField(keySlot, keyBytes);
writer.writeVarField(valueSlot, valueBytes);

// Get final message segment
MemorySegment message = writer.finish();

Thread Safety: Not thread-safe. Use one instance per thread.

Zero-GC: All operations avoid heap allocation.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    VarFieldWriter.NestedFieldHandle
    A handle for writing nested or composite fields directly into the backing segment.

  • Constructor Summary

    Constructors
    Constructor
    Description
    VarFieldWriter(MemorySegment segment, long fixedHeaderSize, int maxVarFields)
    Creates a VarFieldWriter for building structured messages.

  • Method Summary

    Modifier and Type
    Method
    Description
    VarFieldWriter.NestedFieldHandle
    beginNestedField(int slot)
    Begin streaming bytes for a nested or composite field directly into the backing segment.
    long
    bytesWritten()
    Returns the total number of bytes written (headers + data).
    long
    dataOffset()
    Returns the offset where variable field data begins.
    static int
    encodeUtf8(String value, MemorySegment target)
    Encodes a string as UTF-8 directly into a memory segment.
    MemorySegment
    finish()
    Returns the final message segment with all data written.
    int
    reserveVarField()
    Reserves a slot for a variable-length field.
    void
    reset()
    Resets the writer to start building a new message.
    static int
    utf8Length(String value)
    Calculates the UTF-8 encoded byte length of a string.
    int
    varFieldCount()
    Returns the number of variable fields written.
    void
    writeBoolean(long offset, boolean value)
    Writes a boolean to the fixed header as a single byte (0 or 1).
    void
    writeByte(long offset, byte value)
    Writes a byte to the fixed header at the specified offset.
    void
    writeDoubleLE(long offset, double value)
    Writes a double to the fixed header in little-endian format.
    void
    writeFloatLE(long offset, float value)
    Writes a float to the fixed header in little-endian format.
    void
    writeIntLE(long offset, int value)
    Writes an int (32-bit) to the fixed header in little-endian format.
    void
    writeLongLE(long offset, long value)
    Writes a long (64-bit) to the fixed header in little-endian format.
    void
    writeShortLE(long offset, short value)
    Writes a short (16-bit) to the fixed header in little-endian format.
    void
    writeVarField(int slot, byte[] data)
    Writes data to a reserved variable field slot.
    void
    writeVarField(int slot, byte[] data, int offset, int length)
    Writes a portion of a byte array to a reserved variable field slot.
    void
    writeVarField(int slot, MemorySegment source)
    Writes a MemorySegment to a reserved variable field slot.
    void
    writeVarField(int slot, MemorySegment source, long offset, long length)
    Writes a portion of a MemorySegment to a reserved variable field slot.
    void
    writeVarField(int slot, String str, MemorySegment scratchBuffer)
    Writes a UTF-8 string to a reserved variable field slot using the provided scratch buffer for encoding.

    Methods inherited from class Object

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

  • Constructor Details

    • VarFieldWriter

      public VarFieldWriter(MemorySegment segment, long fixedHeaderSize, int maxVarFields)
      Creates a VarFieldWriter for building structured messages.
      Parameters:
      segment - The backing memory segment (must be large enough).
      fixedHeaderSize - Size of the fixed header in bytes.
      maxVarFields - Maximum number of variable-length fields.
      Throws:
      IllegalArgumentException - if parameters are invalid.

  • Method Details

    • writeByte

      public void writeByte(long offset, byte value)
      Writes a byte to the fixed header at the specified offset.
      Parameters:
      offset - Offset within the fixed header (0 to fixedHeaderSize-1).
      value - The byte value to write.
      Throws:
      IndexOutOfBoundsException - if offset is out of bounds.

    • writeShortLE

      public void writeShortLE(long offset, short value)
      Writes a short (16-bit) to the fixed header in little-endian format.

    • writeIntLE

      public void writeIntLE(long offset, int value)
      Writes an int (32-bit) to the fixed header in little-endian format.

    • writeLongLE

      public void writeLongLE(long offset, long value)
      Writes a long (64-bit) to the fixed header in little-endian format.

    • writeFloatLE

      public void writeFloatLE(long offset, float value)
      Writes a float to the fixed header in little-endian format.

    • writeDoubleLE

      public void writeDoubleLE(long offset, double value)
      Writes a double to the fixed header in little-endian format.

    • writeBoolean

      public void writeBoolean(long offset, boolean value)
      Writes a boolean to the fixed header as a single byte (0 or 1).

    • reserveVarField

      public int reserveVarField()
      Reserves a slot for a variable-length field.
      Returns:
      The slot index (use this with writeVarField).
      Throws:
      IllegalStateException - if all slots are exhausted.

    • writeVarField

      public void writeVarField(int slot, byte[] data)
      Writes data to a reserved variable field slot.
      Parameters:
      slot - The slot index from reserveVarField().
      data - The byte array containing the data.
      Throws:
      IllegalArgumentException - if slot is invalid or data is null.
      IndexOutOfBoundsException - if segment is too small.

    • writeVarField

      public void writeVarField(int slot, byte[] data, int offset, int length)
      Writes a portion of a byte array to a reserved variable field slot.
      Parameters:
      slot - The slot index from reserveVarField().
      data - The byte array containing the data.
      offset - Starting offset in the data array.
      length - Number of bytes to write.

    • writeVarField

      public void writeVarField(int slot, String str, MemorySegment scratchBuffer)
      Writes a UTF-8 string to a reserved variable field slot using the provided scratch buffer for encoding. The scratch buffer is reused, avoiding any heap allocation while encoding the string.
      Parameters:
      slot - The slot index from reserveVarField().
      str - The string to encode and write.
      scratchBuffer - A reusable off-heap buffer large enough to hold the UTF-8 bytes.

    • writeVarField

      public void writeVarField(int slot, MemorySegment source)
      Writes a MemorySegment to a reserved variable field slot.
      Parameters:
      slot - The slot index from reserveVarField().
      source - The source segment to copy from.

    • writeVarField

      public void writeVarField(int slot, MemorySegment source, long offset, long length)
      Writes a portion of a MemorySegment to a reserved variable field slot.
      Parameters:
      slot - The slot index from reserveVarField().
      source - The source segment to copy from.
      offset - Starting offset in the source segment.
      length - Number of bytes to copy.

    • beginNestedField

      public VarFieldWriter.NestedFieldHandle beginNestedField(int slot)
      Begin streaming bytes for a nested or composite field directly into the backing segment. Call VarFieldWriter.NestedFieldHandle.finish(long) once all bytes have been written so offsets and lengths can be committed to the header. The caller is responsible for ensuring bytes are written sequentially starting at the absolute offset provided by the handle and for never overlapping concurrent nested writes.

    • utf8Length

      public static int utf8Length(String value)
      Calculates the UTF-8 encoded byte length of a string.
      Parameters:
      value - the string to measure
      Returns:
      the number of bytes required for UTF-8 encoding

    • encodeUtf8

      public static int encodeUtf8(String value, MemorySegment target)
      Encodes a string as UTF-8 directly into a memory segment.
      Parameters:
      value - the string to encode
      target - the target segment to write to
      Returns:
      the number of bytes written
      Throws:
      IndexOutOfBoundsException - if the target is too small

    • finish

      public MemorySegment finish()
      Returns the final message segment with all data written. The returned segment is a slice from offset 0 to the end of the last written data.
      Returns:
      A MemorySegment view of the complete message.

    • bytesWritten

      public long bytesWritten()
      Returns the total number of bytes written (headers + data).
      Returns:
      The byte size of the complete message.

    • varFieldCount

      public int varFieldCount()
      Returns the number of variable fields written.
      Returns:
      The count of variable fields.

    • reset

      public void reset()
      Resets the writer to start building a new message. The backing segment is reused. Fixed header size and max var fields remain unchanged.

    • dataOffset

      public long dataOffset()
      Returns the offset where variable field data begins. Useful for debugging or advanced use cases.
      Returns:
      The data section offset.