Interface ClassFile
public sealed interface ClassFile
Provides ability to parse, transform, and generate
class files.
A ClassFile is a context with a set of options that condition how
parsing and generation are done.- Since:
- 24
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceThe option describing user-defined attributes for parsingclassfiles.static enumThe option describing whether to retain or discard attributes that cannot verify their correctness after a transformation.static interfaceThe option describing the class hierarchy resolver to use when generating stack maps or verifying classes.static enumOption describing whether to extend from the original constant pool when transforming aclassfile.static enumThe option describing whether to patch out unreachable code for stack map generation.static enumThe option describing whether to filter unbound labels and drop their enclosing structures if possible.static enumThe option describing whether to process or discard debugPseudoInstructions in the traversal of aCodeModelor aCodeBuilder.static enumThe option describing whether to process or discardLineNumbers in the traversal of aCodeModelor aCodeBuilder.static interfaceAn option that affects the parsing or writing ofclassfiles.static enumThe option describing whether to automatically rewrite short jumps to equivalent instructions when necessary.static enumThe option describing whether to generate stack maps. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intThe bit mask ofAccessFlag.ABSTRACTaccess and property modifier.static final intThe bit mask ofAccessFlag.ANNOTATIONaccess and property modifier.static final intThe bit mask ofAccessFlag.BRIDGEaccess and property modifier.static final intThe bit mask ofAccessFlag.ENUMaccess and property modifier.static final intThe bit mask ofAccessFlag.FINALaccess and property modifier.static final intThe bit mask ofAccessFlag.INTERFACEaccess and property modifier.static final intThe bit mask ofAccessFlag.MANDATEDaccess and property modifier.static final intThe bit mask ofAccessFlag.MODULEaccess and property modifier.static final intThe bit mask ofAccessFlag.NATIVEaccess and property modifier.static final intThe bit mask ofAccessFlag.OPENaccess and property modifier.static final intThe bit mask ofAccessFlag.PRIVATEaccess and property modifier.static final intThe bit mask ofAccessFlag.PROTECTEDaccess and property modifier.static final intThe bit mask ofAccessFlag.PUBLICaccess and property modifier.static final intThe bit mask ofAccessFlag.STATICaccess and property modifier.static final intThe bit mask ofAccessFlag.STATIC_PHASEaccess and property modifier.static final intThe bit mask ofAccessFlag.STRICTaccess and property modifier.static final intThe bit mask ofAccessFlag.SUPERaccess and property modifier.static final intThe bit mask ofAccessFlag.SYNCHRONIZEDaccess and property modifier.static final intThe bit mask ofAccessFlag.SYNTHETICaccess and property modifier.static final intThe bit mask ofAccessFlag.TRANSIENTaccess and property modifier.static final intThe bit mask ofAccessFlag.TRANSITIVEaccess and property modifier.static final intThe bit mask ofAccessFlag.VARARGSaccess and property modifier.static final intThe bit mask ofAccessFlag.VOLATILEaccess and property modifier.static final intThe class major version of the initial version of Java, 45.static final intThe class major version introduced by Java SE 10, 54.static final intThe class major version introduced by Java SE 11, 55.static final intThe class major version introduced by Java SE 12, 56.static final intThe class major version introduced by Java SE 13, 57.static final intThe class major version introduced by Java SE 14, 58.static final intThe class major version introduced by Java SE 15, 59.static final intThe class major version introduced by Java SE 16, 60.static final intThe class major version introduced by Java SE 17, 61.static final intThe class major version introduced by Java SE 18, 62.static final intThe class major version introduced by Java SE 19, 63.static final intThe class major version introduced by Java 2 SE 1.2, 46.static final intThe class major version introduced by Java SE 20, 64.static final intThe class major version introduced by Java SE 21, 65.static final intThe class major version introduced by Java SE 22, 66.static final intThe class major version introduced by Java SE 23, 67.static final intThe class major version introduced by Java SE 24, 68.static final intThe class major version introduced by Java 2 SE 1.3, 47.static final intThe class major version introduced by Java 2 SE 1.4, 48.static final intThe class major version introduced by Java 2 SE 5.0, 49.static final intThe class major version introduced by Java SE 6, 50.static final intThe class major version introduced by Java SE 7, 51.static final intThe class major version introduced by Java SE 8, 52.static final intThe class major version introduced by Java SE 9, 53.static final intThe magic number identifying theclassfile format, 0xcafebabe.static final intA minor version number 65535 indicating a class uses preview features of a Java SE release since 12, for major versions 56 and above. -
Method Summary
Modifier and TypeMethodDescriptionbyte[]build(ClassEntry thisClassEntry, ConstantPoolBuilder constantPool, Consumer<? super ClassBuilder> handler) Builds aclassfile into a byte array using the provided constant pool builder.default byte[]build(ClassDesc thisClass, Consumer<? super ClassBuilder> handler) Builds aclassfile into a byte array.default byte[]buildModule(ModuleAttribute moduleAttribute) Builds a module descriptor into a byte array.default byte[]buildModule(ModuleAttribute moduleAttribute, Consumer<? super ClassBuilder> handler) Builds a module descriptor into a byte array.default voidbuildModuleTo(Path path, ModuleAttribute moduleAttribute) Builds a module descriptor into a file in a file system.default voidbuildModuleTo(Path path, ModuleAttribute moduleAttribute, Consumer<? super ClassBuilder> handler) Builds a module descriptor into a file in a file system.default voidbuildTo(Path path, ClassEntry thisClassEntry, ConstantPoolBuilder constantPool, Consumer<? super ClassBuilder> handler) Builds aclassfile into a file in a file system using the provided constant pool builder.default voidbuildTo(Path path, ClassDesc thisClass, Consumer<ClassBuilder> handler) Builds aclassfile into a file in a file system.static intReturns the latest class major version supported by the current runtime.static intReturns the latest class minor version supported by the current runtime.static ClassFileof()Returns a context with default options.static ClassFileof(ClassFile.Option... options) Returns a context with options altered from the default.parse(byte[] bytes) Parses aclassfile into aClassModel.default ClassModelParses aclassinto aClassModel.default byte[]transformClass(ClassModel model, ClassTransform transform) byte[]transformClass(ClassModel model, ClassEntry newClassName, ClassTransform transform) default byte[]transformClass(ClassModel model, ClassDesc newClassName, ClassTransform transform) verify(byte[] bytes) Verify aclassfile.verify(ClassModel model) Verify aclassfile.default List<VerifyError> Verify aclassfile.withOptions(ClassFile.Option... options) Returns a context with altered options from this context.
-
Field Details
-
MAGIC_NUMBER
static final int MAGIC_NUMBERThe magic number identifying theclassfile format, 0xcafebabe. It is a big-endian 4-byte value.- See Also:
-
ACC_PUBLIC
static final int ACC_PUBLICThe bit mask ofAccessFlag.PUBLICaccess and property modifier.- See Also:
-
ACC_PROTECTED
static final int ACC_PROTECTEDThe bit mask ofAccessFlag.PROTECTEDaccess and property modifier.- See Also:
-
ACC_PRIVATE
static final int ACC_PRIVATEThe bit mask ofAccessFlag.PRIVATEaccess and property modifier.- See Also:
-
ACC_INTERFACE
static final int ACC_INTERFACEThe bit mask ofAccessFlag.INTERFACEaccess and property modifier.- See Also:
-
ACC_ENUM
-
ACC_ANNOTATION
static final int ACC_ANNOTATIONThe bit mask ofAccessFlag.ANNOTATIONaccess and property modifier.- See Also:
-
ACC_SUPER
-
ACC_ABSTRACT
static final int ACC_ABSTRACTThe bit mask ofAccessFlag.ABSTRACTaccess and property modifier.- See Also:
-
ACC_VOLATILE
static final int ACC_VOLATILEThe bit mask ofAccessFlag.VOLATILEaccess and property modifier.- See Also:
-
ACC_TRANSIENT
static final int ACC_TRANSIENTThe bit mask ofAccessFlag.TRANSIENTaccess and property modifier.- See Also:
-
ACC_SYNTHETIC
static final int ACC_SYNTHETICThe bit mask ofAccessFlag.SYNTHETICaccess and property modifier.- See Also:
-
ACC_STATIC
static final int ACC_STATICThe bit mask ofAccessFlag.STATICaccess and property modifier.- See Also:
-
ACC_FINAL
-
ACC_SYNCHRONIZED
static final int ACC_SYNCHRONIZEDThe bit mask ofAccessFlag.SYNCHRONIZEDaccess and property modifier.- See Also:
-
ACC_BRIDGE
static final int ACC_BRIDGEThe bit mask ofAccessFlag.BRIDGEaccess and property modifier.- See Also:
-
ACC_VARARGS
static final int ACC_VARARGSThe bit mask ofAccessFlag.VARARGSaccess and property modifier.- See Also:
-
ACC_NATIVE
static final int ACC_NATIVEThe bit mask ofAccessFlag.NATIVEaccess and property modifier.- See Also:
-
ACC_STRICT
static final int ACC_STRICTThe bit mask ofAccessFlag.STRICTaccess and property modifier.- See Also:
-
ACC_MODULE
static final int ACC_MODULEThe bit mask ofAccessFlag.MODULEaccess and property modifier.- See Also:
-
ACC_OPEN
-
ACC_MANDATED
static final int ACC_MANDATEDThe bit mask ofAccessFlag.MANDATEDaccess and property modifier.- See Also:
-
ACC_TRANSITIVE
static final int ACC_TRANSITIVEThe bit mask ofAccessFlag.TRANSITIVEaccess and property modifier.- See Also:
-
ACC_STATIC_PHASE
static final int ACC_STATIC_PHASEThe bit mask ofAccessFlag.STATIC_PHASEaccess and property modifier.- See Also:
-
JAVA_1_VERSION
static final int JAVA_1_VERSIONThe class major version of the initial version of Java, 45.- See Also:
-
JAVA_2_VERSION
static final int JAVA_2_VERSIONThe class major version introduced by Java 2 SE 1.2, 46.- See Also:
-
JAVA_3_VERSION
static final int JAVA_3_VERSIONThe class major version introduced by Java 2 SE 1.3, 47.- See Also:
-
JAVA_4_VERSION
static final int JAVA_4_VERSIONThe class major version introduced by Java 2 SE 1.4, 48.- See Also:
-
JAVA_5_VERSION
static final int JAVA_5_VERSIONThe class major version introduced by Java 2 SE 5.0, 49.- See Also:
-
JAVA_6_VERSION
static final int JAVA_6_VERSIONThe class major version introduced by Java SE 6, 50.- See Also:
-
JAVA_7_VERSION
static final int JAVA_7_VERSIONThe class major version introduced by Java SE 7, 51.- See Also:
-
JAVA_8_VERSION
static final int JAVA_8_VERSIONThe class major version introduced by Java SE 8, 52.- See Also:
-
JAVA_9_VERSION
static final int JAVA_9_VERSIONThe class major version introduced by Java SE 9, 53.- See Also:
-
JAVA_10_VERSION
static final int JAVA_10_VERSIONThe class major version introduced by Java SE 10, 54.- See Also:
-
JAVA_11_VERSION
static final int JAVA_11_VERSIONThe class major version introduced by Java SE 11, 55.- See Also:
-
JAVA_12_VERSION
static final int JAVA_12_VERSIONThe class major version introduced by Java SE 12, 56.- See Also:
-
JAVA_13_VERSION
static final int JAVA_13_VERSIONThe class major version introduced by Java SE 13, 57.- See Also:
-
JAVA_14_VERSION
static final int JAVA_14_VERSIONThe class major version introduced by Java SE 14, 58.- See Also:
-
JAVA_15_VERSION
static final int JAVA_15_VERSIONThe class major version introduced by Java SE 15, 59.- See Also:
-
JAVA_16_VERSION
static final int JAVA_16_VERSIONThe class major version introduced by Java SE 16, 60.- See Also:
-
JAVA_17_VERSION
static final int JAVA_17_VERSIONThe class major version introduced by Java SE 17, 61.- See Also:
-
JAVA_18_VERSION
static final int JAVA_18_VERSIONThe class major version introduced by Java SE 18, 62.- See Also:
-
JAVA_19_VERSION
static final int JAVA_19_VERSIONThe class major version introduced by Java SE 19, 63.- See Also:
-
JAVA_20_VERSION
static final int JAVA_20_VERSIONThe class major version introduced by Java SE 20, 64.- See Also:
-
JAVA_21_VERSION
static final int JAVA_21_VERSIONThe class major version introduced by Java SE 21, 65.- See Also:
-
JAVA_22_VERSION
static final int JAVA_22_VERSIONThe class major version introduced by Java SE 22, 66.- See Also:
-
JAVA_23_VERSION
static final int JAVA_23_VERSIONThe class major version introduced by Java SE 23, 67.- See Also:
-
JAVA_24_VERSION
static final int JAVA_24_VERSIONThe class major version introduced by Java SE 24, 68.- See Also:
-
PREVIEW_MINOR_VERSION
static final int PREVIEW_MINOR_VERSIONA minor version number 65535 indicating a class uses preview features of a Java SE release since 12, for major versions 56 and above.- See Also:
-
-
Method Details
-
of
Returns a context with default options. Each subtype ofClassFile.Optionspecifies its default.The default
ClassFile.AttributeMapperOptionandClassFile.ClassHierarchyResolverOptionmay be unsuitable for someclassfiles and result in parsing or generation errors.- Returns:
- a context with default options
-
of
Returns a context with options altered from the default. Equivalent toClassFile.of().withOptions(options).- Parameters:
options- the desired processing options- Returns:
- a context with options altered from the default
-
withOptions
Returns a context with altered options from this context.- Parameters:
options- the desired processing options- Returns:
- a context with altered options from this context
-
parse
Parses aclassfile into aClassModel.Due to the on-demand nature of
classfile parsing, anIllegalArgumentExceptionmay be thrown on any accessor method invocation on the returned model or any structure returned by the accessors in the structure hierarchy.- Parameters:
bytes- the bytes of theclassfile- Returns:
- the class model
- Throws:
IllegalArgumentException- if theclassfile is malformed or of a version not supported by the current runtime
-
parse
Parses aclassinto aClassModel.Due to the on-demand nature of
classfile parsing, anIllegalArgumentExceptionmay be thrown on any accessor method invocation on the returned model or any structure returned by the accessors in the structure hierarchy.- Parameters:
path- the path to theclassfile- Returns:
- the class model
- Throws:
IOException- if an I/O error occursIllegalArgumentException- if theclassfile is malformed or of a version not supported by the current runtime- See Also:
-
build
Builds aclassfile into a byte array.- Parameters:
thisClass- the name of the class to buildhandler- a handler that receives aClassBuilder- Returns:
- the
classfile bytes - Throws:
IllegalArgumentException- ifthisClassrepresents a primitive type or building encounters a failure
-
build
byte[] build(ClassEntry thisClassEntry, ConstantPoolBuilder constantPool, Consumer<? super ClassBuilder> handler) Builds aclassfile into a byte array using the provided constant pool builder.- Parameters:
thisClassEntry- the name of the class to buildconstantPool- the constant pool builderhandler- a handler that receives aClassBuilder- Returns:
- the
classfile bytes - Throws:
IllegalArgumentException- if building encounters a failure
-
buildTo
default void buildTo(Path path, ClassDesc thisClass, Consumer<ClassBuilder> handler) throws IOException Builds aclassfile into a file in a file system.- Parameters:
path- the path to the file to writethisClass- the name of the class to buildhandler- a handler that receives aClassBuilder- Throws:
IOException- if an I/O error occursIllegalArgumentException- if building encounters a failure
-
buildTo
default void buildTo(Path path, ClassEntry thisClassEntry, ConstantPoolBuilder constantPool, Consumer<? super ClassBuilder> handler) throws IOException Builds aclassfile into a file in a file system using the provided constant pool builder.- Parameters:
path- the path to the file to writethisClassEntry- the name of the class to buildconstantPool- the constant pool builderhandler- a handler that receives aClassBuilder- Throws:
IOException- if an I/O error occursIllegalArgumentException- if building encounters a failure
-
buildModule
Builds a module descriptor into a byte array.- Parameters:
moduleAttribute- theModuleattribute- Returns:
- the
classfile bytes - Throws:
IllegalArgumentException- if building encounters a failure
-
buildModule
Builds a module descriptor into a byte array.- Parameters:
moduleAttribute- theModuleattributehandler- a handler that receives aClassBuilder- Returns:
- the
classfile bytes - Throws:
IllegalArgumentException- if building encounters a failure
-
buildModuleTo
Builds a module descriptor into a file in a file system.- Parameters:
path- the file to writemoduleAttribute- theModuleattribute- Throws:
IOException- if an I/O error occursIllegalArgumentException- if building encounters a failure
-
buildModuleTo
default void buildModuleTo(Path path, ModuleAttribute moduleAttribute, Consumer<? super ClassBuilder> handler) throws IOException Builds a module descriptor into a file in a file system.- Parameters:
path- the file to writemoduleAttribute- theModuleattributehandler- a handler that receives aClassBuilder- Throws:
IOException- if an I/O error occursIllegalArgumentException- if building encounters a failure
-
transformClass
Transform oneclassfile into a newclassfile according to aClassTransform. The transform will receive each element of this class, as well as aClassBuilderfor building the new class. The transform is free to preserve, remove, or replace elements as it sees fit.This method behaves as if:
whereConstantPoolBuilder cpb = ... this.build(model.thisClass(), cpb, clb -> clb.transform(model, transform));cpbis determined byClassFile.ConstantPoolSharingOption.- API Note:
- This is named
transformClassinstead oftransformfor consistency withClassBuilder.transformField(java.lang.classfile.FieldModel, java.lang.classfile.FieldTransform),ClassBuilder.transformMethod(java.lang.classfile.MethodModel, java.lang.classfile.MethodTransform), andMethodBuilder.transformCode(java.lang.classfile.CodeModel, java.lang.classfile.CodeTransform), and to distinguish fromClassFileBuilder.transform(java.lang.classfile.CompoundElement<E>, java.lang.classfile.ClassFileTransform<?, E, B>), which is more generic and powerful. - Parameters:
model- the class model to transformtransform- the transform- Returns:
- the bytes of the new class
- Throws:
IllegalArgumentException- if building encounters a failure- See Also:
-
transformClass
Transform oneclassfile into a newclassfile according to aClassTransform. The transform will receive each element of this class, as well as aClassBuilderfor building the new class. The transform is free to preserve, remove, or replace elements as it sees fit.- API Note:
- This is named
transformClassinstead oftransformfor consistency withClassBuilder.transformField(java.lang.classfile.FieldModel, java.lang.classfile.FieldTransform),ClassBuilder.transformMethod(java.lang.classfile.MethodModel, java.lang.classfile.MethodTransform), andMethodBuilder.transformCode(java.lang.classfile.CodeModel, java.lang.classfile.CodeTransform), and to distinguish fromClassFileBuilder.transform(java.lang.classfile.CompoundElement<E>, java.lang.classfile.ClassFileTransform<?, E, B>), which is more generic and powerful. - Parameters:
model- the class model to transformnewClassName- new class nametransform- the transform- Returns:
- the bytes of the new class
- Throws:
IllegalArgumentException- if building encounters a failure- See Also:
-
transformClass
Transform oneclassfile into a newclassfile according to aClassTransform. The transform will receive each element of this class, as well as aClassBuilderfor building the new class. The transform is free to preserve, remove, or replace elements as it sees fit.This method behaves as if:
whereConstantPoolBuilder cpb = ... this.build(newClassName, cpb, clb -> clb.transform(model, transform));cpbis determined byClassFile.ConstantPoolSharingOption.- API Note:
- This is named
transformClassinstead oftransformfor consistency withClassBuilder.transformField(java.lang.classfile.FieldModel, java.lang.classfile.FieldTransform),ClassBuilder.transformMethod(java.lang.classfile.MethodModel, java.lang.classfile.MethodTransform), andMethodBuilder.transformCode(java.lang.classfile.CodeModel, java.lang.classfile.CodeTransform), and to distinguish fromClassFileBuilder.transform(java.lang.classfile.CompoundElement<E>, java.lang.classfile.ClassFileTransform<?, E, B>), which is more generic and powerful. - Parameters:
model- the class model to transformnewClassName- new class nametransform- the transform- Returns:
- the bytes of the new class
- Throws:
IllegalArgumentException- if building encounters a failure- See Also:
-
verify
Verify aclassfile. All verification errors found will be returned.- Parameters:
model- the class model to verify- Returns:
- a list of verification errors, or an empty list if no error is found
-
verify
Verify aclassfile. All verification errors found will be returned.- Parameters:
bytes- theclassfile bytes to verify- Returns:
- a list of verification errors, or an empty list if no error is found
-
verify
Verify aclassfile. All verification errors found will be returned.- Parameters:
path- theclassfile path to verify- Returns:
- a list of verification errors, or an empty list if no error is found
- Throws:
IOException- if an I/O error occurs
-
latestMajorVersion
static int latestMajorVersion()Returns the latest class major version supported by the current runtime.- Returns:
- the latest class major version supported by the current runtime
-
latestMinorVersion
static int latestMinorVersion()Returns the latest class minor version supported by the current runtime.- API Note:
- This does not report the
PREVIEW_MINOR_VERSIONwhen the current runtime has preview feature enabled, asclassfiles with a major version other thanlatestMajorVersion()and the preview minor version are not supported. - Returns:
- the latest class minor version supported by the current runtime
-