Interface ConstantPoolBuilder
- All Superinterfaces:
ConstantPool,Iterable<PoolEntry>
class file. Provides read and
write access to the constant pool that is being built. Writing is append-only (the index of new entries monotonically
increase) and idempotent (entry-bearing methods will return an existing entry
if there is a suitable one).
For class file building, an overload of ClassFile::build takes a
ConstantPoolBuilder. For class file transformations via
ClassFile::transformClass, the ClassFile.ConstantPoolSharingOption controls how the constant pool builder
of the resulting class is created.
Alien Constant Pool Entries
Inclass file building and constant pool building, some constant pool
entries supplied may be alien
to this constant pool builder of the active class file builder. For example,
classEntry(Utf8Entry) may be called with an
alien UTF8 entry. Alien entries will be converted to a pool entry in
this constant pool builder, reusing equivalent entries or adding new entries
if there is none. As a result, all pool entries returned by entry-bearing
methods in this constant pool builder belong to this constant pool.
Some ClassFileBuilder methods may have their outputs adjusted if they
receive pool entries alien to their constant pools. For example, if an ldc_w instruction with an alien entry is written to a CodeBuilder,
the CodeBuilder may emit a functionally equivalent ldc
instruction instead, if the converted entry can be encoded in such an
instruction.
To avoid the conversion of alien constant pool entries, such as for the
accuracy of the generated class file, users can always supply
constant pool entries obtained by calling the constant pool builder
entry-bearing methods of the constant pools associated with the
ClassFileBuilder. Otherwise, the conversions have no impact on the
behaviors of the generated class files.
- Since:
- 24
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionbsmEntry(MethodHandleEntry methodReference, List<LoadableConstantEntry> arguments) Returns aBootstrapMethodEntryreferring to aMethodHandleEntryand a list ofLoadableConstantEntry.default BootstrapMethodEntrybsmEntry(DirectMethodHandleDesc methodReference, List<ConstantDesc> arguments) Returns aBootstrapMethodEntrydescribing the provided bootstrap method and arguments.booleancanWriteDirect(ConstantPool constantPool) Returnstrueif the index of any entry in the given constant pool refers to the same entry in this builder.classEntry(Utf8Entry ne) Returns aClassEntryreferring to the providedUtf8Entry.default ClassEntryclassEntry(ClassDesc classDesc) Returns aClassEntrydescribing the same reference type as the providedClassDesc.constantDynamicEntry(BootstrapMethodEntry bootstrapMethodEntry, NameAndTypeEntry nameAndType) default ConstantDynamicEntryReturns aConstantDynamicEntrydescribing the dynamic constant as the providedDynamicConstantDesc.default ConstantValueEntrydoubleEntry(double value) Returns aDoubleEntrydescribing the provided value.fieldRefEntry(ClassEntry owner, NameAndTypeEntry nameAndType) default FieldRefEntryfieldRefEntry(ClassDesc owner, String name, ClassDesc type) Returns aFieldRefEntrydescribing a field of a class.floatEntry(float value) Returns aFloatEntrydescribing the provided value.intEntry(int value) Returns anIntegerEntrydescribing the provided value.interfaceMethodRefEntry(ClassEntry owner, NameAndTypeEntry nameAndType) default InterfaceMethodRefEntryinterfaceMethodRefEntry(ClassDesc owner, String name, MethodTypeDesc type) Returns anInterfaceMethodRefEntrydescribing a method of an interface.invokeDynamicEntry(BootstrapMethodEntry bootstrapMethodEntry, NameAndTypeEntry nameAndType) default InvokeDynamicEntryReturns anInvokeDynamicEntrydescribing the same dynamic call site as the providedDynamicCallSiteDesc.default LoadableConstantEntryReturns aLoadableConstantEntrydescribing the provided constant value.longEntry(long value) Returns aLongEntrydescribing the provided value.methodHandleEntry(int refKind, MemberRefEntry reference) Returns aMethodHandleEntryencoding a reference kind and referring to aMemberRefEntry.default MethodHandleEntrymethodHandleEntry(DirectMethodHandleDesc descriptor) Returns aMethodHandleEntrydescribing the same method handle as the givenDirectMethodHandleDesc.methodRefEntry(ClassEntry owner, NameAndTypeEntry nameAndType) default MethodRefEntrymethodRefEntry(ClassDesc owner, String name, MethodTypeDesc type) Returns aMethodRefEntrydescribing a method of a class.methodTypeEntry(Utf8Entry descriptor) Returns aMethodTypeEntryreferring to aUtf8Entry.methodTypeEntry(MethodTypeDesc descriptor) Returns aMethodTypeEntrydescribing the same method type as the providedMethodTypeDesc.moduleEntry(Utf8Entry moduleName) Returns aModuleEntryreferring to the providedUtf8Entry.default ModuleEntrymoduleEntry(ModuleDesc moduleDesc) Returns aModuleEntrydescribing the same module as the providedModuleDesc.nameAndTypeEntry(Utf8Entry nameEntry, Utf8Entry typeEntry) Returns aNameAndTypeEntryreferring to the provided name and typeUtf8Entry.default NameAndTypeEntrynameAndTypeEntry(String name, ClassDesc type) Returns aNameAndTypeEntrydescribing the provided unqualified name and field descriptor.default NameAndTypeEntrynameAndTypeEntry(String name, MethodTypeDesc type) Returns aNameAndTypeEntrydescribing the provided name and method descriptor.static ConstantPoolBuilderof()Returns a new constant pool builder.static ConstantPoolBuilderof(ClassModel classModel) Returns a new constant pool builder.packageEntry(Utf8Entry nameEntry) Returns aPackageEntryreferring to the providedUtf8Entry.default PackageEntrypackageEntry(PackageDesc packageDesc) Returns aPackageEntrydescribing the same package as the providedPackageDesc.stringEntry(Utf8Entry utf8) Returns aStringEntryreferring to aUtf8Entry.default StringEntrystringEntry(String value) Returns aStringEntrydescribing the provided value.default Utf8Entrydefault Utf8Entryutf8Entry(MethodTypeDesc desc) Methods declared in interface java.lang.classfile.constantpool.ConstantPool
bootstrapMethodCount, bootstrapMethodEntry, entryByIndex, entryByIndex, iterator, sizeMethods declared in interface java.lang.Iterable
forEach, spliterator
-
Method Details
-
of
Returns a new constant pool builder. The new constant pool builder will be pre-populated with the contents of the constant pool associated with the given class model. The index of new entries will start from thesize()of the source pool.- Parameters:
classModel- the class to copy from- Returns:
- a new constant pool builder
- See Also:
-
of
Returns a new constant pool builder. The new constant pool builder will be empty. The index of new entries will start from1.- Returns:
- a new constant pool builder
- See Also:
-
canWriteDirect
Returnstrueif the index of any entry in the given constant pool refers to the same entry in this builder. This may be because they are the same builder, or because this builder was pre-populated from the given constant pool.If the constant pool of an entry is not directly writable to this pool, it is alien to this pool, and a
ClassFileBuilderassociated with this constant pool will convert that alien constant pool entry.- Parameters:
constantPool- the given constant pool- Returns:
trueif the index of any entry in the given constant pool refers to the same entry in this builder- See Also:
-
utf8Entry
-
utf8Entry
- API Note:
- The resulting
Utf8Entryis usually not referable by aClassEntry, which uses internal form of binary names. - Parameters:
desc- the symbolic descriptor for the class- Returns:
- a
Utf8Entrydescribing the field descriptor string of the providedClassDesc
-
utf8Entry
- Parameters:
desc- the symbolic descriptor for the method type- Returns:
- a
Utf8Entrydescribing the method descriptor string of the providedMethodTypeDesc
-
classEntry
Returns aClassEntryreferring to the providedUtf8Entry. TheUtf8Entrydescribes the internal form of the binary name of a class or interface or the field descriptor string of an array type.- Parameters:
ne- theUtf8Entry- Returns:
- a
ClassEntryreferring to the providedUtf8Entry - See Also:
-
classEntry
Returns aClassEntrydescribing the same reference type as the providedClassDesc.- Parameters:
classDesc- the symbolic descriptor for the reference type- Returns:
- a
ClassEntrydescribing the same reference type as the providedClassDesc - Throws:
IllegalArgumentException- ifclassDescrepresents a primitive type- See Also:
-
packageEntry
Returns aPackageEntryreferring to the providedUtf8Entry. TheUtf8Entrydescribes the internal form of the name of a package.- Parameters:
nameEntry- theUtf8Entry- Returns:
- a
PackageEntryreferring to the providedUtf8Entry - See Also:
-
packageEntry
Returns aPackageEntrydescribing the same package as the providedPackageDesc.- Parameters:
packageDesc- the symbolic descriptor for the package- Returns:
- a
PackageEntrydescribing the same package as the providedPackageDesc - See Also:
-
moduleEntry
- Parameters:
moduleName- the constant pool entry describing the module name- Returns:
- a
ModuleEntryreferring to the providedUtf8Entry - See Also:
-
moduleEntry
Returns aModuleEntrydescribing the same module as the providedModuleDesc.- Parameters:
moduleDesc- the symbolic descriptor for the module- Returns:
- a
ModuleEntrydescribing the same module as the providedModuleDesc - See Also:
-
nameAndTypeEntry
Returns aNameAndTypeEntryreferring to the provided name and typeUtf8Entry. The nameUtf8Entrydescribes an unqualified name or the special name "<init>", and the typeUtf8Entrydescribes a field or method descriptor string.- Parameters:
nameEntry- the nameUtf8EntrytypeEntry- the typeUtf8Entry- Returns:
- a
NameAndTypeEntryreferring to the provided name and typeUtf8Entry - See Also:
-
nameAndTypeEntry
Returns aNameAndTypeEntrydescribing the provided unqualified name and field descriptor.- Parameters:
name- the unqualified nametype- the field descriptor- Returns:
- a
NameAndTypeEntrydescribing the provided unqualified name and field descriptor
-
nameAndTypeEntry
Returns aNameAndTypeEntrydescribing the provided name and method descriptor. The name can be an unqualified name or the special name "<init>".- Parameters:
name- the unqualified name, or "<init>"type- the method descriptor- Returns:
- a
NameAndTypeEntrydescribing the provided name and method descriptor
-
fieldRefEntry
Returns aFieldRefEntryreferring to aClassEntryand aNameAndTypeEntry. TheClassEntrydescribes a class or interface that has this field as a member, and theNameAndTypeEntrydescribes the unqualified name and the field descriptor for this field.- Parameters:
owner- theClassEntrynameAndType- theNameAndTypeEntry- Returns:
- a
FieldRefEntryreferring to aClassEntryand aNameAndTypeEntry - See Also:
-
fieldRefEntry
Returns aFieldRefEntrydescribing a field of a class.- Parameters:
owner- the class or interface the field is a member ofname- the unqualified name of the fieldtype- the field descriptor- Returns:
- a
FieldRefEntrydescribing a field of a class - Throws:
IllegalArgumentException- ifownerrepresents a primitive type- See Also:
-
methodRefEntry
Returns aMethodRefEntryreferring to aClassEntryand aNameAndTypeEntry. TheClassEntrydescribes a class that has this method as a member, and theNameAndTypeEntrydescribes the unqualified name or the special name "<init>" and the method descriptor for this method.- Parameters:
owner- theClassEntrynameAndType- theNameAndTypeEntry- Returns:
- a
MethodRefEntryreferring to aClassEntryand aNameAndTypeEntry - See Also:
-
methodRefEntry
Returns aMethodRefEntrydescribing a method of a class.- Parameters:
owner- the class the method is a member ofname- the unqualified name, or special name "<init>", of the methodtype- the method descriptor- Returns:
- a
MethodRefEntrydescribing a method of a class - Throws:
IllegalArgumentException- ifownerrepresents a primitive type- See Also:
-
interfaceMethodRefEntry
Returns anInterfaceMethodRefEntryreferring to aClassEntryand aNameAndTypeEntry. TheClassEntrydescribes an interface that has this method as a member, and theNameAndTypeEntrydescribes the unqualified name and the method descriptor for this method.- Parameters:
owner- theClassEntrynameAndType- theNameAndTypeEntry- Returns:
- an
InterfaceMethodRefEntryreferring to aClassEntryand aNameAndTypeEntry - See Also:
-
interfaceMethodRefEntry
default InterfaceMethodRefEntry interfaceMethodRefEntry(ClassDesc owner, String name, MethodTypeDesc type) Returns anInterfaceMethodRefEntrydescribing a method of an interface.- Parameters:
owner- the interface the method is a member ofname- the unqualified name of the methodtype- the method descriptor- Returns:
- an
InterfaceMethodRefEntrydescribing a method of an interface - Throws:
IllegalArgumentException- ifownerrepresents a primitive type- See Also:
-
methodTypeEntry
Returns aMethodTypeEntrydescribing the same method type as the providedMethodTypeDesc.- Parameters:
descriptor- the symbolic descriptor of the method type- Returns:
- a
MethodTypeEntrydescribing the same method type as the providedMethodTypeDesc - See Also:
-
methodTypeEntry
Returns aMethodTypeEntryreferring to aUtf8Entry. TheUtf8Entryrepresents a method descriptor string.- Parameters:
descriptor- theUtf8Entry- Returns:
- a
MethodTypeEntryreferring to aUtf8Entry - See Also:
-
methodHandleEntry
Returns aMethodHandleEntrydescribing the same method handle as the givenDirectMethodHandleDesc.- Parameters:
descriptor- the symbolic descriptor of the method handle- Returns:
- a
MethodHandleEntrydescribing the same method handle as the givenDirectMethodHandleDesc - See Also:
-
methodHandleEntry
Returns aMethodHandleEntryencoding a reference kind and referring to aMemberRefEntry. The reference kind must be in[1, 9], and theMemberRefEntryis subject to various restrictions based on the reference kind (JVMS 4.4.8).- Parameters:
refKind- the reference kind of the method handlereference- theMemberRefEntry- Returns:
- a
MethodHandleEntryencoding a reference kind and referring to aMemberRefEntry - See Also:
-
invokeDynamicEntry
Returns anInvokeDynamicEntrydescribing the same dynamic call site as the providedDynamicCallSiteDesc.- Parameters:
dcsd- the symbolic descriptor of the dynamic call site- Returns:
- an
InvokeDynamicEntrydescribing the same dynamic call site as the providedDynamicCallSiteDesc - See Also:
-
invokeDynamicEntry
InvokeDynamicEntry invokeDynamicEntry(BootstrapMethodEntry bootstrapMethodEntry, NameAndTypeEntry nameAndType) Returns anInvokeDynamicEntryreferring to aBootstrapMethodEntryand aNameAndTypeEntry. TheBootstrapMethodEntrydescribes the bootstrap method and its invocation arguments in addition to the name and type, and theNameAndTypeEntrya name and a method descriptor.- Parameters:
bootstrapMethodEntry- theBootstrapMethodEntrynameAndType- theNameAndTypeEntry- Returns:
- an
InvokeDynamicEntryreferring to aBootstrapMethodEntryand aNameAndTypeEntry - See Also:
-
constantDynamicEntry
Returns aConstantDynamicEntrydescribing the dynamic constant as the providedDynamicConstantDesc.- Parameters:
dcd- the symbolic descriptor of the constant- Returns:
- a
ConstantDynamicEntrydescribing the dynamic constant as the providedDynamicConstantDesc - See Also:
-
constantDynamicEntry
ConstantDynamicEntry constantDynamicEntry(BootstrapMethodEntry bootstrapMethodEntry, NameAndTypeEntry nameAndType) Returns aConstantDynamicEntryreferring to aBootstrapMethodEntryand aNameAndTypeEntry. TheBootstrapMethodEntrydescribes the bootstrap method and its invocation arguments in addition to the name and type, and theNameAndTypeEntrya name and a field descriptor.- Parameters:
bootstrapMethodEntry- theBootstrapMethodEntrynameAndType- theNameAndTypeEntry- Returns:
- a
ConstantDynamicEntryreferring to aBootstrapMethodEntryand aNameAndTypeEntry - See Also:
-
intEntry
Returns anIntegerEntrydescribing the provided value.- Parameters:
value- the value- Returns:
- an
IntegerEntrydescribing the provided value - See Also:
-
floatEntry
Returns aFloatEntrydescribing the provided value.All NaN values of the
floatmay or may not be collapsed into a single "canonical" NaN value.- Parameters:
value- the value- Returns:
- a
FloatEntrydescribing the provided value - See Also:
-
longEntry
-
doubleEntry
Returns aDoubleEntrydescribing the provided value.All NaN values of the
doublemay or may not be collapsed into a single "canonical" NaN value.- Parameters:
value- the value- Returns:
- a
DoubleEntrydescribing the provided value - See Also:
-
stringEntry
- Parameters:
utf8- theUtf8Entry- Returns:
- a
StringEntryreferring to aUtf8Entry - See Also:
-
stringEntry
Returns aStringEntrydescribing the provided value.- Parameters:
value- the value- Returns:
- a
StringEntrydescribing the provided value - See Also:
-
constantValueEntry
Returns aConstantValueEntrydescribing the provided constantInteger,Long,Float,Double, orStringvalue.- Parameters:
c- the provided constant value- Returns:
- a
ConstantValueEntrydescribing the provided constantInteger,Long,Float,Double, orStringvalue - Throws:
IllegalArgumentException- if the value is not one ofInteger,Long,Float,Double, orString- See Also:
-
loadableConstantEntry
Returns aLoadableConstantEntrydescribing the provided constant value.- Parameters:
c- the nominal descriptor for the constant- Returns:
- a
LoadableConstantEntrydescribing the provided constant value
-
bsmEntry
default BootstrapMethodEntry bsmEntry(DirectMethodHandleDesc methodReference, List<ConstantDesc> arguments) Returns aBootstrapMethodEntrydescribing the provided bootstrap method and arguments.- Parameters:
methodReference- the bootstrap methodarguments- the arguments- Returns:
- a
BootstrapMethodEntrydescribing the provided bootstrap method and arguments
-
bsmEntry
BootstrapMethodEntry bsmEntry(MethodHandleEntry methodReference, List<LoadableConstantEntry> arguments) Returns aBootstrapMethodEntryreferring to aMethodHandleEntryand a list ofLoadableConstantEntry. TheMethodHandleEntryis the bootstrap method, and the list ofLoadableConstantEntryis the arguments.- Parameters:
methodReference- theMethodHandleEntryarguments- the list ofLoadableConstantEntry- Returns:
- a
BootstrapMethodEntryreferring to aMethodHandleEntryand a list ofLoadableConstantEntry - See Also:
-