BufWriter (Java SE 25 & JDK 25)
Description: declaration: module: java.base, package: java.lang.classfile, interface: BufWriter
Keywords: java.lang.classfile.BufWriter interface

# Interface BufWriter

public sealed interface BufWriter
Advanced `class` file writing support for `AttributeMapper`s. 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:
  - `AttributeMapper.writeAttribute(BufWriter, Attribute)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `canWriteDirect(ConstantPool other)`
  Returns whether the provided constant pool is index-compatible with the constant pool of this buffer.
  `ConstantPoolBuilder`
  `constantPool()`
  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`
  `size()`
  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`
  `writeIndex(PoolEntry entry)`
  Writes the index of the specified constant pool entry as a `u2`.
  `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`.
  `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:
      - `ClassFileBuilder.constantPool()`

  - ### 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:
      - `ConstantPoolBuilder.canWriteDirect(ConstantPool)`

  - ### 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:
      - `size()`

  - ### 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:
      - `patchInt(int, int, int)`