# 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.

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 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(java.lang.classfile.AttributedElement, java.lang.classfile.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 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.

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.
  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.