Module java.base
Package java.lang.classfilePREVIEW

# Interface ClassReader

All Superinterfaces:
  `ConstantPoolPREVIEW`, `Iterable<PoolEntryPREVIEW>`

public sealed interface ClassReader extends ConstantPoolPREVIEW
`ClassReader` is a preview API of the Java platform.
Programs can only use `ClassReader` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
Supports reading from a classfile. Methods are provided to read data of various numeric types (e.g., `u2`, `u4`) at a given offset within the classfile, copying raw bytes, and reading constant pool entries. Encapsulates additional reading context such as mappers for custom attributes and processing options.

Since:
  22

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `classfileLength()`
  Returns the length of the classfile, in bytes.
  `boolean`
  `compare(BufWriterPREVIEW bufWriter, int bufWriterOffset, int classReaderOffset, int length)`
  Compare a range of bytes from the classfile to a range of bytes within a `BufWriter`PREVIEW.
  `void`
  `copyBytesTo(BufWriterPREVIEW buf, int offset, int len)`
  Copy a range of bytes from the classfile to a `BufWriter`PREVIEW
  `Function<Utf8EntryPREVIEW,AttributeMapperPREVIEW<?>>`
  `customAttributes()`
  Returns the table of custom attribute mappers.
  `int`
  `flags()`
  Returns the access flags for the class, as a bit mask.
  `byte[]`
  `readBytes(int offset, int len)`
  Returns a copy of the bytes at the specified range in the classfile.
  `ClassEntryPREVIEW`
  `readClassEntry(int offset)`
  Returns the class entry whose index is given at the specified offset within the classfile.
  `double`
  `readDouble(int offset)`
  Returns the double value at the specified offset within the classfile.
  `PoolEntryPREVIEW`
  `readEntry(int offset)`
  Returns the constant pool entry whose index is given at the specified offset within the classfile.
  `<T extends PoolEntryPREVIEW>
  T`
  `readEntry(int offset, Class<T> cls)`
  Returns the constant pool entry of a given type whose index is given at the specified offset within the classfile.
  `PoolEntryPREVIEW`
  `readEntryOrNull(int offset)`
  Returns the constant pool entry whose index is given at the specified offset within the classfile, or null if the index at the specified offset is zero.
  `float`
  `readFloat(int offset)`
  Returns the float value at the specified offset within the classfile.
  `int`
  `readInt(int offset)`
  Returns the signed int at the specified offset within the classfile.
  `long`
  `readLong(int offset)`
  Returns the signed long at the specified offset within the classfile.
  `MethodHandleEntryPREVIEW`
  `readMethodHandleEntry(int offset)`
  Returns the method handle entry whose index is given at the specified offset within the classfile.
  `ModuleEntryPREVIEW`
  `readModuleEntry(int offset)`
  Returns the module entry whose index is given at the specified offset within the classfile.
  `NameAndTypeEntryPREVIEW`
  `readNameAndTypeEntry(int offset)`
  Returns the name-and-type entry whose index is given at the specified offset within the classfile.
  `PackageEntryPREVIEW`
  `readPackageEntry(int offset)`
  Returns the package entry whose index is given at the specified offset within the classfile.
  `int`
  `readS1(int offset)`
  Returns the signed byte at the specified offset within the classfile.
  `int`
  `readS2(int offset)`
  Returns the signed byte at the specified offset within the classfile.
  `int`
  `readU1(int offset)`
  Returns the unsigned byte at the specified offset within the classfile.
  `int`
  `readU2(int offset)`
  Returns the unsigned short at the specified offset within the classfile.
  `Utf8EntryPREVIEW`
  `readUtf8Entry(int offset)`
  Returns the UTF8 entry whose index is given at the specified offset within the classfile.
  `Utf8EntryPREVIEW`
  `readUtf8EntryOrNull(int offset)`
  Returns the UTF8 entry whose index is given at the specified offset within the classfile, or null if the index at the specified offset is zero.
  `int`
  `skipAttributeHolder(int offset)`
  Returns the offset following the block of attributes starting at the specified position.
  `Optional<ClassEntryPREVIEW>`
  `superclassEntry()`
  Returns the constant pool entry describing the name of the superclass, if any.
  `ClassEntryPREVIEW`
  `thisClassEntry()`
  Returns the constant pool entry describing the name of class.
  `int`
  `thisClassPos()`
  Returns the offset into the classfile of the `this_class` field.
  `Utf8EntryPREVIEW`
  `utf8EntryByIndex(int index)`
  Returns the UTF8 constant pool entry at the given index of the constant pool.

  ### Methods declared in interface java.lang.classfile.constantpool.ConstantPoolPREVIEW

  `bootstrapMethodCount, bootstrapMethodEntry, entryByIndex, iterator, size`

  ### Methods declared in interface java.lang.Iterable

  `forEach, spliterator`

- ## Method Details

  - ### customAttributes

    Function<Utf8EntryPREVIEW,AttributeMapperPREVIEW<?>> customAttributes()
    Returns the table of custom attribute mappers. This is derived from the processing option `ClassFile.AttributeMapperOption`PREVIEW.
    Returns:
      the table of custom attribute mappers

  - ### flags

    int flags()
    Returns the access flags for the class, as a bit mask .
    Returns:
      the access flags for the class, as a bit mask

  - ### thisClassEntry

    ClassEntryPREVIEW thisClassEntry()
    Returns the constant pool entry describing the name of class.
    Returns:
      the constant pool entry describing the name of class

  - ### superclassEntry

    Optional<ClassEntryPREVIEW> superclassEntry()
    Returns the constant pool entry describing the name of the superclass, if any.
    Returns:
      the constant pool entry describing the name of the superclass, if any

  - ### thisClassPos

    int thisClassPos()
    Returns the offset into the classfile of the `this_class` field.
    Returns:
      the offset into the classfile of the `this_class` field

  - ### classfileLength

    int classfileLength()
    Returns the length of the classfile, in bytes.
    Returns:
      the length of the classfile, in bytes

  - ### skipAttributeHolder

    int skipAttributeHolder(int offset)
    Returns the offset following the block of attributes starting at the specified position.
    Parameters:
      `offset` - the offset into the classfile at which the attribute block starts
    Returns:
      the offset following the block of attributes starting at the specified position

  - ### utf8EntryByIndex

    Utf8EntryPREVIEW utf8EntryByIndex(int index)
    Returns the UTF8 constant pool entry at the given index of the constant pool. The given index must correspond to a valid constant pool index whose slot holds a UTF8 constant.
    Parameters:
      `index` - the index into the constant pool
    Returns:
      the UTF8 constant pool entry at the given index of the constant pool

  - ### readEntry

    PoolEntryPREVIEW readEntry(int offset)
    Returns the constant pool entry whose index is given at the specified offset within the classfile.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the constant pool entry whose index is given at the specified offset within the classfile
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or zero

  - ### readEntry

    <T extends PoolEntryPREVIEW> T readEntry(int offset, Class<T> cls)
    Returns the constant pool entry of a given type whose index is given at the specified offset within the classfile.
    Type Parameters:
      `T` - the entry type
    Parameters:
      `offset` - the offset of the index within the classfile
      `cls` - the entry type
    Returns:
      the constant pool entry of a given type whose index is given at the specified offset within the classfile
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or zero, or the entry is not of the given type

  - ### readEntryOrNull

    PoolEntryPREVIEW readEntryOrNull(int offset)
    Returns the constant pool entry whose index is given at the specified offset within the classfile, or null if the index at the specified offset is zero.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the constant pool entry whose index is given at the specified offset within the classfile, or null if the index at the specified offset is zero
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size

  - ### readUtf8Entry

    Utf8EntryPREVIEW readUtf8Entry(int offset)
    Returns the UTF8 entry whose index is given at the specified offset within the classfile.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the UTF8 entry whose index is given at the specified offset within the classfile
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or zero, or the index does not correspond to a UTF8 entry

  - ### readUtf8EntryOrNull

    Utf8EntryPREVIEW readUtf8EntryOrNull(int offset)
    Returns the UTF8 entry whose index is given at the specified offset within the classfile, or null if the index at the specified offset is zero.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the UTF8 entry whose index is given at the specified offset within the classfile, or null if the index at the specified offset is zero
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or the index does not correspond to a UTF8 entry

  - ### readModuleEntry

    ModuleEntryPREVIEW readModuleEntry(int offset)
    Returns the module entry whose index is given at the specified offset within the classfile.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the module entry whose index is given at the specified offset within the classfile
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or zero, or the index does not correspond to a module entry

  - ### readPackageEntry

    PackageEntryPREVIEW readPackageEntry(int offset)
    Returns the package entry whose index is given at the specified offset within the classfile.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the package entry whose index is given at the specified offset within the classfile
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or zero, or the index does not correspond to a package entry

  - ### readClassEntry

    ClassEntryPREVIEW readClassEntry(int offset)
    Returns the class entry whose index is given at the specified offset within the classfile.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the class entry whose index is given at the specified offset within the classfile
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or zero, or the index does not correspond to a class entry

  - ### readNameAndTypeEntry

    NameAndTypeEntryPREVIEW readNameAndTypeEntry(int offset)
    Returns the name-and-type entry whose index is given at the specified offset within the classfile.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the name-and-type entry whose index is given at the specified offset within the classfile
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or zero, or the index does not correspond to a name-and-type entry

  - ### readMethodHandleEntry

    MethodHandleEntryPREVIEW readMethodHandleEntry(int offset)
    Returns the method handle entry whose index is given at the specified offset within the classfile.
    Parameters:
      `offset` - the offset of the index within the classfile
    Returns:
      the method handle entry whose index is given at the specified offset within the classfile
    Throws:
      `ConstantPoolExceptionPREVIEW` - if the index is out of range of the constant pool size, or zero, or the index does not correspond to a method handle entry

  - ### readU1

    int readU1(int offset)
    Returns the unsigned byte at the specified offset within the classfile.
    Parameters:
      `offset` - the offset within the classfile
    Returns:
      the unsigned byte at the specified offset within the classfile

  - ### readU2

    int readU2(int offset)
    Returns the unsigned short at the specified offset within the classfile.
    Parameters:
      `offset` - the offset within the classfile
    Returns:
      the unsigned short at the specified offset within the classfile

  - ### readS1

    int readS1(int offset)
    Returns the signed byte at the specified offset within the classfile.
    Parameters:
      `offset` - the offset within the classfile
    Returns:
      the signed byte at the specified offset within the classfile

  - ### readS2

    int readS2(int offset)
    Returns the signed byte at the specified offset within the classfile.
    Parameters:
      `offset` - the offset within the classfile
    Returns:
      the signed byte at the specified offset within the classfile

  - ### readInt

    int readInt(int offset)
    Returns the signed int at the specified offset within the classfile.
    Parameters:
      `offset` - the offset within the classfile
    Returns:
      the signed int at the specified offset within the classfile

  - ### readLong

    long readLong(int offset)
    Returns the signed long at the specified offset within the classfile.
    Parameters:
      `offset` - the offset within the classfile
    Returns:
      the signed long at the specified offset within the classfile

  - ### readFloat

    float readFloat(int offset)
    Returns the float value at the specified offset within the classfile.
    Parameters:
      `offset` - the offset within the classfile
    Returns:
      the float value at the specified offset within the classfile

  - ### readDouble

    double readDouble(int offset)
    Returns the double value at the specified offset within the classfile.
    Parameters:
      `offset` - the offset within the classfile
    Returns:
      the double value at the specified offset within the classfile

  - ### readBytes

    byte[] readBytes(int offset, int len)
    Returns a copy of the bytes at the specified range in the classfile.
    Parameters:
      `offset` - the offset within the classfile
      `len` - the length of the range
    Returns:
      a copy of the bytes at the specified range in the classfile

  - ### copyBytesTo

    void copyBytesTo(BufWriterPREVIEW buf, int offset, int len)
    Copy a range of bytes from the classfile to a `BufWriter`PREVIEW
    Parameters:
      `buf` - the BufWriterPREVIEW
      `offset` - the offset within the classfile
      `len` - the length of the range

  - ### compare

    boolean compare(BufWriterPREVIEW bufWriter, int bufWriterOffset, int classReaderOffset, int length)
    Compare a range of bytes from the classfile to a range of bytes within a `BufWriter`PREVIEW.
    Parameters:
      `bufWriter` - the BufWriterPREVIEW
      `bufWriterOffset` - the offset within the BufWriterPREVIEW
      `classReaderOffset` - the offset within the classfile
      `length` - the length of the range
    Returns:
      whether the two ranges were identical