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

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

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

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.