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 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(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 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: