# Package java.lang.classfile.attribute

package java.lang.classfile.attribute

## 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 `CompoundElement`s 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(AttributedElement, ClassReader, int)` 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 structures. 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 sufficient, 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.

See Java Virtual Machine Specification:
  4.7 Attributes
Since:
  24
See Also:
  - `Attribute`
  - `AttributeMapper`
  - `Attributes`

Related Packages
Package
Description
java.lang.classfile
Provides classfile parsing, generation, and transformation library.
java.lang.classfile.constantpool
Provides interfaces describing constant pool entries for the `java.lang.classfile` library.
java.lang.classfile.instruction
Provides interfaces describing code instructions for the `java.lang.classfile` library.
Class
Description
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.
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.
CharacterRangeInfo
Models a single character range entry in the `CharacterRangeTableAttribute`.
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.
CodeAttribute
Models the `Code` attribute (JVMS §4.7.3), which contains the bytecode of this method.
CompilationIDAttribute
Models the `CompilationID` attribute, which records the compilation time of the `class` file.
ConstantValueAttribute
Models the `ConstantValue` attribute (JVMS §4.7.2), which indicates this field's value is a constant and that constant value.
DeprecatedAttribute
Models the `Deprecated` attribute (JVMS §4.7.15), which indicates this structure has been superseded.
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.
ExceptionsAttribute
Models the `Exceptions` attribute (JVMS §4.7.5), which records the exceptions declared to be thrown by this method.
InnerClassesAttribute
Models the `InnerClasses` attribute (JVMS §4.7.6), which records which classes referenced by this `class` file are nested classes.
InnerClassInfo
Models a single entry in the `InnerClassesAttribute`.
LineNumberInfo
Models a single line number entry in the `LineNumberTableAttribute`.
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.
LoadableDescriptorsAttributePREVIEW
Preview.
Models the `LoadableDescriptors`PREVIEW attribute (JVMS §4.7.32PREVIEW), which permits the JVM to load mentioned classes and interfaces before the `class` file carrying this attribute is loaded.
LocalVariableInfo
Models a single local variable in the `LocalVariableTableAttribute`.
LocalVariableTableAttribute
Models the `LocalVariableTable` attribute (JVMS §4.7.13), which records debug information about local variables.
LocalVariableTypeInfo
Models a single local variable in the `LocalVariableTypeTableAttribute`.
LocalVariableTypeTableAttribute
Models the `LocalVariableTypeTable` attribute (JVMS §4.7.14), which records debug information about local variables with generic types.
MethodParameterInfo
Models a single method parameter in the `MethodParametersAttribute`.
MethodParametersAttribute
Models the `MethodParameters` attribute (JVMS §4.7.24), which records reflective information about this method's parameters such as access modifiers.
ModuleAttribute
Models the `Module` attribute (JVMS §4.7.25), which always appears on classes that represent module descriptors.
ModuleAttribute.ModuleAttributeBuilder
A builder for `Module` attributes.
ModuleExportInfo
Models a single "exports" declaration in the `ModuleAttribute`.
ModuleHashesAttribute
Models the `ModuleHashes` attribute, which appears on classes that represent module descriptors to capture the hashes of a set of co-delivered modules.
ModuleHashInfo
Models hash information for a single module in the `ModuleHashesAttribute`.
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.
ModuleOpenInfo
Models a single "opens" declaration in the `ModuleAttribute`.
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.
ModuleProvideInfo
Models a single "provides" declaration in the `ModuleAttribute`.
ModuleRequireInfo
Models a single "requires" declaration in the `ModuleAttribute`.
ModuleResolutionAttribute
Models the `ModuleResolution` attribute, which can appear on classes that represent module descriptors, to capture resolution metadata for modules.
ModuleTargetAttribute
Models the `ModuleTarget` attribute, which can appear on classes that represent module descriptors, to represent constraints on the target platform.
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.
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.
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.
RecordAttribute
Models the `Record` attribute (JVMS §4.7.30), which indicates that this class is a record class and the record components.
RecordComponentInfo
Models a single record component in the `RecordAttribute`.
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.
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.
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.
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.
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.
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.
SignatureAttribute
Models the `Signature` attribute (JVMS §4.7.9), which indicates the generic signature of this structure.
SourceDebugExtensionAttribute
Models the `SourceDebugExtension` attribute (JVMS §4.7.11), which stores arbitrary modified UTF-8 data.
SourceFileAttribute
Models the `SourceFile` attribute (JVMS §4.7.10), which indicates the name of the source file from which this `class` file was compiled.
SourceIDAttribute
Models the `SourceID` attribute, which records the last modified time of the source file from which this `class` file was compiled.
StackMapFrameInfo
Models a stack map frame in a `StackMapTable` attribute (JVMS §4.7.4).
StackMapFrameInfo.ObjectVerificationTypeInfo
A stack value for an object type.
StackMapFrameInfo.SimpleVerificationTypeInfo
A simple stack value.
StackMapFrameInfo.UninitializedVerificationTypeInfo
An uninitialized stack value.
StackMapFrameInfo.VerificationTypeInfo
The type of a stack or local variable value.
StackMapTableAttribute
Models the `StackMapTable` attribute (JVMS §4.7.4), which is used for verification by type checking (§4.10.1).
SyntheticAttribute
Models the `Synthetic` attribute (JVMS §4.7.8), which marks a class member as implementation-specific artifacts.
UnknownAttribute
Models an unknown attribute read from a `class` file.