Interface BufWriter


public sealed interface BufWriter
Advanced class file writing support for AttributeMappers. Supports writing portions of a class file to a growable buffer, such as writing various numerical types (e.g., u2, u4), to the end of the buffer, as well as to create constant pool entries.

All numeric values in the class file format are big endian. Writing larger numeric values to smaller numeric values are always done with truncation, that the least significant bytes are kept and the other bytes are silently dropped. As a result, numeric value writing methods can write both signed and unsigned values, and users should validate their values before writing if silent dropping of most significant bytes is not the intended behavior.

Since:
24
See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    Returns whether the provided constant pool is index-compatible with the constant pool of this buffer.
    Returns the constant pool builder associated with this buffer.
    void
    patchInt(int offset, int size, int value)
    Patches a previously written integer value.
    void
    reserveSpace(int freeBytes)
    Ensures that the buffer has at least freeBytes bytes of free space in the end of the buffer.
    int
    Returns the number of bytes that have been written to the buffer.
    void
    writeBytes(byte[] arr)
    Writes the contents of a byte array to the buffer.
    void
    writeBytes(byte[] arr, int start, int length)
    Writes a range of a byte array to the buffer.
    void
    writeDouble(double x)
    Writes a double value, of 8 bytes, to the buffer.
    void
    writeFloat(float x)
    Writes a float value, of 4 bytes, to the buffer.
    void
    Writes the index of the specified constant pool entry as a u2.
    void
    Writes the index of the specified constant pool entry, or the value 0 if the specified entry is null, as a u2.
    void
    writeInt(int x)
    Writes 4 bytes, or an int, to the buffer.
    void
    writeIntBytes(int intSize, long intValue)
    Writes a multibyte value to the buffer.
    void
    writeLong(long x)
    Writes 8 bytes, or a long, to the buffer.
    void
    writeU1(int x)
    Writes a byte to the buffer.
    void
    writeU2(int x)
    Writes 2 bytes, or a short, to the buffer.
  • Method Details

    • constantPool

      ConstantPoolBuilder constantPool()
      Returns the constant pool builder associated with this buffer.
      Returns:
      the constant pool builder associated with this buffer
      See Also:
    • canWriteDirect

      boolean canWriteDirect(ConstantPool other)
      Returns whether the provided constant pool is index-compatible with the constant pool of this buffer.

      This is a shortcut for constantPool().canWriteDirect(other).

      Parameters:
      other - the other constant pool
      Returns:
      whether the provided constant pool is index-compatible with the constant pool of this buffer
      See Also:
    • reserveSpace

      void reserveSpace(int freeBytes)
      Ensures that the buffer has at least freeBytes bytes of free space in the end of the buffer.

      The writing result is the same without calls to this method, but the writing process may be slower.

      API Note:
      This is a hint that changes no visible state of the buffer; it helps to reduce reallocation of the underlying storage by allocating sufficient space at once.
      Parameters:
      freeBytes - the number of bytes to reserve
    • writeU1

      void writeU1(int x)
      Writes a byte to the buffer. x is truncated to a byte and written.
      Parameters:
      x - the value to truncate to a byte
    • writeU2

      void writeU2(int x)
      Writes 2 bytes, or a short, to the buffer. x is truncated to two bytes and written.
      Parameters:
      x - the value to truncate to a short
    • writeInt

      void writeInt(int x)
      Writes 4 bytes, or an int, to the buffer.
      Parameters:
      x - the int value
    • writeFloat

      void writeFloat(float x)
      Writes a float value, of 4 bytes, to the buffer.

      In the conversions, all NaN values of the float may or may not be collapsed into a single "canonical" NaN value.

      Parameters:
      x - the float value
    • writeLong

      void writeLong(long x)
      Writes 8 bytes, or a long, to the buffer.
      Parameters:
      x - the long value
    • writeDouble

      void writeDouble(double x)
      Writes a double value, of 8 bytes, to the buffer.

      In the conversions, all NaN values of the double may or may not be collapsed into a single "canonical" NaN value.

      Parameters:
      x - the double value
    • writeBytes

      void writeBytes(byte[] arr)
      Writes the contents of a byte array to the buffer.
      Parameters:
      arr - the byte array
    • writeBytes

      void writeBytes(byte[] arr, int start, int length)
      Writes a range of a byte array to the buffer.
      Parameters:
      arr - the byte array
      start - the start offset of the range within the byte array
      length - the length of the range
      Throws:
      IndexOutOfBoundsException - if range is outside the array bounds
    • patchInt

      void patchInt(int offset, int size, int value)
      Patches a previously written integer value. value is truncated to the given size number of bytes and written at the given offset. The end of this buffer stays unchanged.
      API Note:
      The offset can be obtained by calling size() before writing the previous integer value.
      Parameters:
      offset - the offset in this buffer at which to patch
      size - the size of the integer value being written, in bytes
      value - the integer value to be truncated
      Throws:
      IndexOutOfBoundsException - if patched int is outside of bounds
      See Also:
    • writeIntBytes

      void writeIntBytes(int intSize, long intValue)
      Writes a multibyte value to the buffer. intValue is truncated to the given intSize number of bytes and written.
      Parameters:
      intSize - the size of the integer value being written, in bytes
      intValue - the value to be truncated
    • writeIndex

      void writeIndex(PoolEntry entry)
      Writes the index of the specified constant pool entry as a u2. If the entry does not belong to the constant pool of this buffer, it will be converted, and the index of the converted pool entry is written instead.
      Parameters:
      entry - the constant pool entry
      Throws:
      IllegalArgumentException - if the entry has invalid index
    • writeIndexOrZero

      void writeIndexOrZero(PoolEntry entry)
      Writes the index of the specified constant pool entry, or the value 0 if the specified entry is null, as a u2. If the entry does not belong to the constant pool of this buffer, it will be converted, and the index of the converted pool entry is written instead.
      Parameters:
      entry - the constant pool entry, may be null
      Throws:
      IllegalArgumentException - if the entry is not null and has invalid index
    • size

      int size()
      Returns the number of bytes that have been written to the buffer.
      Returns:
      the number of bytes that have been written to the buffer
      See Also: