OpenJDK 27 · java.lang.classfile.attribute · APIdia, the JavaDoc alternative

Provides interfaces describing `class` file attributes for the `java.lang.classfile` library.

The java.lang.classfile.attribute package contains interfaces describing specific class file attributes, including predefined (JVMS 4.7) and JDK-specific nonstandard attributes, whose mappers are defined in Attributes. This package summary provides an overview to the class file attribute system, including Attribute, AttributedElement, AttributeMapper, and CustomAttribute, which do not reside in this package.

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

Reading Attributes

The general way to obtain attributes is through AttributedElement. In addition to that, many attributes implement ClassElement, FieldElement, MethodElement, or CodeElement, and these attributes are generally delivered when their enclosing elements are viewed as CompoundElements in streaming traversal, unless otherwise specified.

When read from class files, the attributes are lazily inflated; the contents of these attributes are not evaluated to speed up parsing, and user-defined attributes from AttributeMapper#readAttribute should be lazy too. Contents to users interest can be read on demand, so errors in one attribute does not prevent access to other attributes.

Attribute contents are represented with constant pool entries to closely represent the original class file. These entries provide conversion methods to view them as validated symbolic descriptors. Check java.lang.classfile.constantpool for effective reading of constant pool entries, which can affect attribute reading speed as well. See this example of checking the presence of a Deprecated annotation:

private static final String DEPRECATED_DESC = Deprecated.class.descriptorString();

    static boolean hasDeprecated(AttributedElement element) {
        var annotations = element.findAttribute(Attributes.runtimeVisibleAnnotations())
                .map(RuntimeVisibleAnnotationsAttribute::annotations)
                .orElse(List.of());
        for (var anno : annotations) {
            // equalsString reduces extra computations for raw UTF-8 entries
            if (anno.className().equalsString(DEPRECATED_DESC)) {
                return true;
            }
        }
        return false;
    }

Due to the lazy nature of class file parsing, IllegalArgumentException indicating malformed class file data can be thrown at any method invocation, either from the attribute itself due to structural corruption, or from a constant pool entry referred by the attribute. Some attributes, such as annotation attributes, must be ignored silently if they are malformed per JVMS; as a result, attribute processing code should anticipate IllegalArgumentException and skip, instead of propagating the failure, on such attributes.

Writing Attributes

Most attributes implement at least one of ClassElement, FieldElement, MethodElement, or CodeElement, so they can be sent to the respective ClassFileBuilder to be written as part of those structure. Attributes define if they can appear multiple times in one structure; if they cannot, the last attribute instance supplied to the builder is the one written to the final structure. Some attributes, such as BootstrapMethodsAttribute, implement none of those interfaces. They are created through other means, specified in the modeling interface for each of the attributes. Attributes for a RecordComponentInfo are supplied through its factory methods.

The attribute factories generally have two sets of factory methods: one that accepts symbolic information representing the uses, and another that accepts constant pool entries. Most of time, the symbolic factories are sufficent, but the constant pool entry ones can be used for fine-grained control over class file generation; see "Writing the constant pool entries" for more details.

Many attributes can be bulk-copied if the data it depends on does not change; this information is exposed in AttributeMapper#stability() and is documented for each attribute on its modeling interface. Ability to bulk-copy can massively speed up class file generation or transformation. In addition, in conjunction with ClassFile.AttributesProcessingOption, attributes read from other class files that cannot confirm its data is still valid for the currently building class file may be dropped.

Interface Summary

Modifier and Type	Interface and Description
public interface	AnnotationDefaultAttribute Models the `AnnotationDefault` attribute (JVMS 4.7.22), which records the default value (JLS 9.6.2) for the annotation interface element defined by this method.
public interface	BootstrapMethodsAttribute Models the `BootstrapMethods` attribute (JVMS 4.7.23), which stores symbolic information for the execution of bootstrap methods, used by dynamically-computed call sites and constants.
public interface	CharacterRangeInfo Models a single character range entry in the `CharacterRangeTableAttribute`.
public interface	CharacterRangeTableAttribute Models the `CharacterRangeTable` attribute, which is a bidirectional mapping from ranges of positions in the source file to ranges of indices into the `code` array.
public interface	CodeAttribute Models the `Code` attribute (JVMS 4.7.3), which contains the bytecode of this method.
public interface	CompilationIDAttribute Models the `CompilationID` attribute, which records the compilation time of the `class` file.
public interface	ConstantValueAttribute Models the `ConstantValue` attribute (JVMS 4.7.2), which indicates this field's value is a constant and that constant value.
public interface	DeprecatedAttribute Models the `Deprecated` attribute (JVMS 4.7.15), which indicates this structure has been superseded.
public interface	EnclosingMethodAttribute Models the `EnclosingMethod` attribute (JVMS 4.7.7), which indicates that this class is a local or anonymous class, and indicates the enclosing method or constructor of this class if this class is enclosed in exactly one method or constructor.
public interface	ExceptionsAttribute Models the `Exceptions` attribute (JVMS 4.7.5), which records the exceptions declared to be thrown by this method.
public interface	InnerClassesAttribute Models the `InnerClasses` attribute (JVMS 4.7.6), which records which classes referenced by this `class` file are nested classes.
public interface	InnerClassInfo Models a single entry in the `InnerClassesAttribute`.
public interface	LineNumberInfo Models a single line number entry in the `LineNumberTableAttribute`.
public interface	LineNumberTableAttribute Models the `LineNumberTable` attribute (JVMS 4.7.12), which records the mapping between indexes into the `code` array and line numbers in the source file.
public interface	LocalVariableInfo Models a single local variable in the `LocalVariableTableAttribute`.
public interface	LocalVariableTableAttribute Models the `LocalVariableTable` attribute (JVMS 4.7.13), which records debug information about local variables.
public interface	LocalVariableTypeInfo Models a single local variable in the `LocalVariableTypeTableAttribute`.
public interface	LocalVariableTypeTableAttribute Models the `LocalVariableTypeTable` attribute (JVMS 4.7.14), which records debug information about local variables with generic types.
public interface	MethodParameterInfo Models a single method parameter in the `MethodParametersAttribute`.
public interface	MethodParametersAttribute Models the `MethodParameters` attribute (JVMS 4.7.24), which records reflective information about this method's parameters such as access modifiers.
public interface	ModuleAttribute Models the `Module` attribute (JVMS 4.7.25), which always appears on classes that represent module descriptors.
public interface	ModuleExportInfo Models a single "exports" declaration in the `ModuleAttribute`.
public interface	ModuleHashesAttribute Models the `ModuleHashes` attribute, which appears on classes that represent module descriptors to capture the hashes of a set of co-delivered modules.
public interface	ModuleHashInfo Models hash information for a single module in the `ModuleHashesAttribute`.
public interface	ModuleMainClassAttribute Models the `ModuleMainClass` attribute (JVMS 4.7.27), which appears on classes that represent module descriptors to indicate the main class of the module.
public interface	ModuleOpenInfo Models a single "opens" declaration in the `ModuleAttribute`.
public interface	ModulePackagesAttribute Models the `ModulePackages` attribute (JVMS 4.7.26), which can appear on classes that represent module descriptors to indicate packages in the module used by the module descriptor.
public interface	ModuleProvideInfo Models a single "provides" declaration in the `ModuleAttribute`.
public interface	ModuleRequireInfo Models a single "requires" declaration in the `ModuleAttribute`.
public interface	ModuleResolutionAttribute Models the `ModuleResolution` attribute, which can appear on classes that represent module descriptors, to capture resolution metadata for modules.
public interface	ModuleTargetAttribute Models the `ModuleTarget` attribute, which can appear on classes that represent module descriptors, to represent constraints on the target platform.
public interface	NestHostAttribute Models the `NestHost` attribute (JVMS 4.7.28), which indicates this class is a member of a nest and the host class of the nest.
public interface	NestMembersAttribute Models the `NestMembers` attribute (JVMS 4.7.29), which indicates that this class is the host of a nest and the other nest members.
public interface	PermittedSubclassesAttribute Models the `PermittedSubclasses` attribute (JVMS 4.7.31), which indicates this class or interface is sealed, and which classes or interfaces may extend or implement this class or interface.
public interface	RecordAttribute Models the `Record` attribute (JVMS 4.7.30), which indicates that this class is a record class and the record components.
public interface	RecordComponentInfo Models a single record component in the `RecordAttribute`.
public interface	RuntimeInvisibleAnnotationsAttribute Models the `RuntimeInvisibleAnnotations` attribute (JVMS 4.7.17), which stores declaration annotations on this structure that are visible to `class` file consumers but are not visible to core reflection.
public interface	RuntimeInvisibleParameterAnnotationsAttribute Models the `RuntimeInvisibleParameterAnnotations` attribute (JVMS 4.7.19), which stores declaration annotations on the method parameters of this method that are visible to `class` file consumers but are not visible to core reflection.
public interface	RuntimeInvisibleTypeAnnotationsAttribute Models the `RuntimeInvisibleTypeAnnotations` attribute (JVMS 4.7.21), which stores type-use annotations for the annotated uses of types in this structure that are visible to `class` file consumers but are not visible to core reflection.
public interface	RuntimeVisibleAnnotationsAttribute Models the `RuntimeVisibleAnnotations` attribute (JVMS 4.7.16), which stores declaration annotations on this structure that are visible to both `class` file consumers and core reflection.
public interface	RuntimeVisibleParameterAnnotationsAttribute Models the `RuntimeVisibleParameterAnnotations` attribute (JVMS 4.7.18), which stores declaration annotations on the method parameters of this method that are visible to both `class` file consumers and core reflection.
public interface	RuntimeVisibleTypeAnnotationsAttribute Models the `RuntimeVisibleTypeAnnotations` attribute (JVMS 4.7.20), which stores type-use annotations for the annotated uses of types in this structure that are visible to both `class` file consumers and core reflection.
public interface	SignatureAttribute Models the `Signature` attribute (JVMS 4.7.9), which indicates the generic signature of this structure.
public interface	SourceDebugExtensionAttribute Models the `SourceDebugExtension` attribute (JVMS 4.7.11), which stores arbitrary modified UTF-8 data.
public interface	SourceFileAttribute Models the `SourceFile` attribute (JVMS 4.7.10), which indicates the name of the source file from which this `class` file was compiled.
public interface	SourceIDAttribute Models the `SourceID` attribute, which records the last modified time of the source file from which this `class` file was compiled.
public interface	StackMapFrameInfo Models a stack map frame in a `StackMapTable` attribute (JVMS 4.7.4).
public interface	StackMapTableAttribute Models the `StackMapTable` attribute (JVMS 4.7.4), which is used for verification by type checking (4.10.1).
public interface	SyntheticAttribute Models the `Synthetic` attribute (JVMS 4.7.8), which marks a class member as implementation-specific artifacts.
public interface	UnknownAttribute Models an unknown attribute read from a `class` file.

Package java.lang.classfile.attribute

Provides interfaces describing class file attributes for the java.lang.classfile library.

Reading Attributes

Writing Attributes

Interface Summary

Provides interfaces describing `class` file attributes for the `java.lang.classfile` library.