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.
Unless otherwise specified, passing null
or an array or collection containing a null
element as an
argument to a constructor or method of any Class-File API class or interface will cause a NullPointerException
to be thrown.
Reading the constant pool entries
When read fromclass
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
-
ClassDescriptionMarker interface for constant pool entries that can represent constant values associated with elements of annotations.Models a
CONSTANT_Class_info
structure, representing a reference type, in the constant pool of aclass
file.Models aCONSTANT_Dynamic_info
structure, representing a dynamically-computed constant, in the constant pool of aclass
file.Provides read access to the constant pool and the bootstrap method table of aclass
file.Builder for the constant pool of aclass
file.Thrown to indicate that requested entry cannot be obtained from the constant pool or the bootstrap method table.Marker interface for constant pool entries that can represent constant values in theConstantValue
attribute.Models aCONSTANT_Double_info
structure, representing adouble
constant, in the constant pool of aclass
file.Superinterface modeling dynamically-computed constant pool entries, which includeConstantDynamicEntry
andInvokeDynamicEntry
, in the constant pool of aclass
file.Models aCONSTANT_Fieldref_info
structure, or a symbolic reference to a field, in the constant pool of aclass
file.Models aCONSTANT_Float_info
structure, or afloat
constant, in the constant pool of aclass
file.Models aCONSTANT_Integer_info
structure, or anint
constant, in the constant pool of aclass
file.Models aCONSTANT_InterfaceMethodRef_info
structure, or a symbolic reference to an interface method, in the constant pool of aclass
file.Models aCONSTANT_InvokeDynamic_info
structure, or the symbolic reference to a dynamically-computed call site, in the constant pool of aclass
file.Marker interface for constant pool entries suitable for loading via theldc
instructions.Models aCONSTANT_Long_info
structure, or along
constant, in the constant pool of aclass
file.Superinterface modeling symbolic references to a member of a class or interface in the constant pool of aclass
file, which include references to fields, class methods, and interface methods.Models aCONSTANT_MethodHandle_info
structure, or a symbolic reference to a method handle, in the constant pool of aclass
file.Models aCONSTANT_MethodRef_info
structure, or a symbolic reference to a class method, in the constant pool of aclass
file.Models aCONSTANT_MethodType_info
structure, or a symbolic reference to a method type, in the constant pool of aclass
file.Models aCONSTANT_Module_info
structure, denoting a module, in the constant pool of aclass
file.Models aCONSTANT_NameAndType_info
structure, representing a field or method, in the constant pool of aclass
file.Models aCONSTANT_Package_info
, representing a package, in the constant pool of aclass
file.Models an entry in the constant pool of aclass
file.Models aCONSTANT_String_info
structure, or a string constant, in the constant pool of aclass
file.Models aCONSTANT_UTF8_info
constant, representing strings, in the constant pool of aclass
file.