java.lang.classfile.constantpool (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: java.lang.classfile.constantpool
Keywords: java.lang.classfile.constantpool package

# Package java.lang.classfile.constantpool

package java.lang.classfile.constantpool

## Provides interfaces describing constant pool entries for the `java.lang.classfile` library.

The `java.lang.classfile.constantpool` package contains interfaces describing constant pool entries in the `class` file format. Constant pool entries are low-level models to faithfully represent the exact structure of a `class` file.

APIs in this package perform null and unrepresentable argument checks, unless otherwise noted.

## Reading the constant pool entries

When read from `class` files, the pool entries are lazily inflated; the contents of these entries, besides the bare structure, are not evaluated to speed up parsing. Entries to users interest, usually accessed from other models and elements, have their contents read on demand. For example, to search for methods, a user should filter first by access flags and then by method name, and use `Utf8Entry.equalsString(String)` instead of checking equality against `Utf8Entry.stringValue()`. This avoids inflation of UTF-8 entries as much as possible:

    boolean isStaticWorkMethod(MethodModel method) {
        // check static flag first to avoid unnecessary evaluation of UTF-8 entry
        return (method.flags().flagsMask() & ClassFile.ACC_STATIC) != 0
                // use equalsString to avoid full conversion to String for comparison
                // the Utf8Entry can also act as a basic CharSequence without full conversion
                && method.methodName().equalsString("work");
    }

The entries also define accessors to validated symbolic information with nominal descriptor abstractions from the `java.lang.constant` package. These symbolic information accessors perform validation against the read `class` files, and throw `IllegalArgumentException` when the accessed constant pool entry contains invalid data. The nominal descriptors represent validated data, which saves users from extra validations in future processing.

Due to the lazy nature of `class` file parsing, `IllegalArgumentException` indicating malformed `class` file data can be thrown at any method invocation. For example, an exception may come from a `ClassEntry` when it is first read from the constant pool (referring to an invalid index or wrong type of entry), when its referred UTF-8 entry is expanded (malformed UTF-8 data), or when its symbolic information is accessed (the string is not valid for a class entry).

## Writing the constant pool entries

In general, users do not need to worry about working with the constant pool and its entries when writing `class` files. Most Class-File API models and elements have two sets of factory methods: one that accepts symbolic information representing the uses, and another that accepts constant pool entries. The constant pool builder associated with `class` file builders, `ClassFileBuilder.constantPool()`, automatically creates or reuses pool entries from the symbolic information. Validated data in symbolic information helps `class` file generation by avoiding extraneous parsing of raw constant pool entry data.

As always, users can use factories that accept constant pool entries if they already have them by hand, or if they desire fine-grained control over `class` file generation.

If many models and elements are reused from another `ClassModel` in class building, the class building process can use a constant pool builder that extends from the given `ClassModel`, available through `ConstantPoolBuilder::of(ClassModel)`, so that byte data with constant pool references can be copied in batch, speeding up class building. This is especially applicable to class transformations, and `ConstantPoolSharingOption` exists to control this behavior.

See Java Virtual Machine Specification:
  4.4 The Constant Pool
Since:
  24

- Related Packages
  Package
  Description
  java.lang.classfile
  Provides classfile parsing, generation, and transformation library.
  java.lang.classfile.attribute
  Provides interfaces describing `class` file attributes for the `java.lang.classfile` library.
  java.lang.classfile.instruction
  Provides interfaces describing code instructions for the `java.lang.classfile` library.
- Class
  Description
  AnnotationConstantValueEntry
  Marker interface for constant pool entries that can represent constant values associated with elements of annotations.
  ClassEntry
  Models a `CONSTANT_Class_info` structure, representing a reference type, in the constant pool of a `class` file.
  ConstantDynamicEntry
  Models a `CONSTANT_Dynamic_info` structure, representing a dynamically-computed constant, in the constant pool of a `class` file.
  ConstantPool
  Provides read access to the constant pool and the bootstrap method table of a `class` file.
  ConstantPoolBuilder
  Builder for the constant pool of a `class` file.
  ConstantPoolException
  Thrown to indicate that requested entry cannot be obtained from the constant pool or the bootstrap method table.
  ConstantValueEntry
  Marker interface for constant pool entries that can represent constant values in the `ConstantValue` attribute.
  DoubleEntry
  Models a `CONSTANT_Double_info` structure, representing a `double` constant, in the constant pool of a `class` file.
  DynamicConstantPoolEntry
  Superinterface modeling dynamically-computed constant pool entries, which include `ConstantDynamicEntry` and `InvokeDynamicEntry`, in the constant pool of a `class` file.
  FieldRefEntry
  Models a `CONSTANT_Fieldref_info` structure, or a symbolic reference to a field, in the constant pool of a `class` file.
  FloatEntry
  Models a `CONSTANT_Float_info` structure, or a `float` constant, in the constant pool of a `class` file.
  IntegerEntry
  Models a `CONSTANT_Integer_info` structure, or an `int` constant, in the constant pool of a `class` file.
  InterfaceMethodRefEntry
  Models a `CONSTANT_InterfaceMethodRef_info` structure, or a symbolic reference to an interface method, in the constant pool of a `class` file.
  InvokeDynamicEntry
  Models a `CONSTANT_InvokeDynamic_info` structure, or the symbolic reference to a dynamically-computed call site, in the constant pool of a `class` file.
  LoadableConstantEntry
  Marker interface for constant pool entries suitable for loading via the `ldc` instructions.
  LongEntry
  Models a `CONSTANT_Long_info` structure, or a `long` constant, in the constant pool of a `class` file.
  MemberRefEntry
  Superinterface modeling symbolic references to a member of a class or interface in the constant pool of a `class` file, which include references to fields, class methods, and interface methods.
  MethodHandleEntry
  Models a `CONSTANT_MethodHandle_info` structure, or a symbolic reference to a method handle, in the constant pool of a `class` file.
  MethodRefEntry
  Models a `CONSTANT_MethodRef_info` structure, or a symbolic reference to a class method, in the constant pool of a `class` file.
  MethodTypeEntry
  Models a `CONSTANT_MethodType_info` structure, or a symbolic reference to a method type, in the constant pool of a `class` file.
  ModuleEntry
  Models a `CONSTANT_Module_info` structure, denoting a module, in the constant pool of a `class` file.
  NameAndTypeEntry
  Models a `CONSTANT_NameAndType_info` structure, representing a field or method, in the constant pool of a `class` file.
  PackageEntry
  Models a `CONSTANT_Package_info`, representing a package, in the constant pool of a `class` file.
  PoolEntry
  Models an entry in the constant pool of a `class` file.
  StringEntry
  Models a `CONSTANT_String_info` structure, or a string constant, in the constant pool of a `class` file.
  Utf8Entry
  Models a `CONSTANT_UTF8_info` constant, representing strings, in the constant pool of a `class` file.