Module io.smallrye.classfile

Package io.smallrye.classfile.constantpool

package io.smallrye.classfile.constantpool

Provides interfaces describing constant pool entries for the io.smallrye.classfile library.

The io.smallrye.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 equalsString(String) instead of checking equality against stringValue(). This avoids inflation of UTF-8 entries as much as possible:
invalid @snippet 
file not found on source path or snippet path: PackageSnippets.java

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.

Since:
24
  • 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.