Module java.base

# Package java.lang.classfile.attribute

≠
package java.lang.classfile.attribute
Comparing jdk-master and valhalla-csr-open

## 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` PREVIEW , `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` PREVIEW , `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` PREVIEW , `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` PREVIEW
  - `AttributeMapper`
  - `Attributes`

## Types

- ≠ AnnotationDefaultAttribute
- ≠ BootstrapMethodsAttribute
- ≠ CharacterRangeInfo
- ≠ CharacterRangeTableAttribute
- ≠ CodeAttribute
- ≠ CompilationIDAttribute
- ≠ ConstantValueAttribute
- ≠ DeprecatedAttribute
- ≠ EnclosingMethodAttribute
- ≠ ExceptionsAttribute
- = InnerClassInfo
- ≠ InnerClassesAttribute
- = LineNumberInfo
- ≠ LineNumberTableAttribute
- + LoadableDescriptorsAttribute
- = LocalVariableInfo
- ≠ LocalVariableTableAttribute
- = LocalVariableTypeInfo
- ≠ LocalVariableTypeTableAttribute
- = MethodParameterInfo
- ≠ MethodParametersAttribute
- ≠ ModuleAttribute
- = ModuleExportInfo
- = ModuleHashInfo
- ≠ ModuleHashesAttribute
- ≠ ModuleMainClassAttribute
- = ModuleOpenInfo
- ≠ ModulePackagesAttribute
- = ModuleProvideInfo
- = ModuleRequireInfo
- ≠ ModuleResolutionAttribute
- ≠ ModuleTargetAttribute
- ≠ NestHostAttribute
- ≠ NestMembersAttribute
- ≠ PermittedSubclassesAttribute
- ≠ RecordAttribute
- ≠ RecordComponentInfo
- ≠ RuntimeInvisibleAnnotationsAttribute
- ≠ RuntimeInvisibleParameterAnnotationsAttribute
- ≠ RuntimeInvisibleTypeAnnotationsAttribute
- ≠ RuntimeVisibleAnnotationsAttribute
- ≠ RuntimeVisibleParameterAnnotationsAttribute
- ≠ RuntimeVisibleTypeAnnotationsAttribute
- ≠ SignatureAttribute
- ≠ SourceDebugExtensionAttribute
- ≠ SourceFileAttribute
- ≠ SourceIDAttribute
- ≠ StackMapFrameInfo
- ≠ StackMapTableAttribute
- ≠ SyntheticAttribute
- ≠ UnknownAttribute

## Summary

Differences
| Elements | Comments | Descriptions | Total
Added | Changed | Removed | Added | Changed | Removed | Added | Changed | Removed
--- | --- | --- | --- | --- | --- | --- | --- | ---
java.lang.classfile.attribute |  |  |  |  |  |  | 4 |  |  | 4
AnnotationDefaultAttribute |  |  |  |  |  |  | 2 |  |  | 2
BootstrapMethodsAttribute |  |  |  |  |  |  | 2 |  |  | 2
CharacterRangeInfo |  |  |  |  |  |  | 2 |  |  | 2
CharacterRangeTableAttribute |  |  |  |  |  |  | 2 |  |  | 2
CodeAttribute |  |  |  |  |  |  | 2 |  |  | 2
CompilationIDAttribute |  |  |  |  |  |  | 4 |  |  | 4
ConstantValueAttribute |  |  |  |  |  |  | 2 |  |  | 2
DeprecatedAttribute |  |  |  |  |  |  | 4 |  |  | 4
EnclosingMethodAttribute |  |  |  |  |  |  | 4 |  |  | 4
ExceptionsAttribute |  |  |  |  |  |  | 2 |  |  | 2
InnerClassesAttribute |  |  |  |  |  |  | 4 |  |  | 4
LineNumberTableAttribute |  |  |  |  |  |  | 2 |  |  | 2
LoadableDescriptorsAttribute | 1 |  |  |  |  |  | 5 |  |  | 6
LocalVariableTableAttribute |  |  |  |  |  |  | 2 |  |  | 2
LocalVariableTypeTableAttribute |  |  |  |  |  |  | 2 |  |  | 2
MethodParametersAttribute |  |  |  |  |  |  | 2 |  |  | 2
ModuleAttribute |  |  |  |  |  |  | 4 |  |  | 4
ModuleHashesAttribute |  |  |  |  |  |  | 4 |  |  | 4
ModuleMainClassAttribute |  |  |  |  |  |  | 4 |  |  | 4
ModulePackagesAttribute |  |  |  |  |  |  | 4 |  |  | 4
ModuleResolutionAttribute |  |  |  |  |  |  | 4 |  |  | 4
ModuleTargetAttribute |  |  |  |  |  |  | 4 |  |  | 4
NestHostAttribute |  |  |  |  |  |  | 4 |  |  | 4
NestMembersAttribute |  |  |  |  |  |  | 4 |  |  | 4
PermittedSubclassesAttribute |  |  |  |  |  |  | 4 |  |  | 4
RecordAttribute |  |  |  |  |  |  | 4 |  |  | 4
RecordComponentInfo |  |  |  |  |  |  | 4 |  |  | 4
RuntimeInvisibleAnnotationsAttribute |  |  |  |  |  |  | 4 |  |  | 4
RuntimeInvisibleParameterAnnotationsAttribute |  |  |  |  |  |  | 2 |  |  | 2
RuntimeInvisibleTypeAnnotationsAttribute |  |  |  |  |  |  | 4 |  |  | 4
RuntimeVisibleAnnotationsAttribute |  |  |  |  |  |  | 4 |  |  | 4
RuntimeVisibleParameterAnnotationsAttribute |  |  |  |  |  |  | 2 |  |  | 2
RuntimeVisibleTypeAnnotationsAttribute |  |  |  |  |  |  | 4 |  |  | 4
SignatureAttribute |  |  |  |  |  |  | 4 |  |  | 4
SourceDebugExtensionAttribute |  |  |  |  |  |  | 4 |  |  | 4
SourceFileAttribute |  |  |  |  |  |  | 4 |  |  | 4
SourceIDAttribute |  |  |  |  |  |  | 4 |  |  | 4
StackMapFrameInfo | 2 |  |  |  |  |  | 2 |  |  | 4
StackMapTableAttribute |  |  |  |  |  |  | 2 |  |  | 2
SyntheticAttribute |  |  |  |  |  |  | 4 |  |  | 4
UnknownAttribute |  |  |  |  |  |  | 4 |  |  | 4
Total | 3 |  |  |  |  |  | 139 |  |  | 142