/* * Copyright (c) 2023, 2025, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /** *

Provides interfaces describing {@code class} file attributes for the {@link java.lang.classfile} library.

* * The {@code java.lang.classfile.attribute} package contains interfaces describing specific {@code class} file * attributes, including predefined (JVMS {@jvms 4.7}) and JDK-specific nonstandard attributes, whose mappers are * defined in {@link Attributes}. This package summary provides an overview to the {@code class} file attribute system, * including {@link Attribute}, {@link AttributedElement}, {@link AttributeMapper}, and {@link CustomAttribute}, which * do not reside in this package. *

* Unless otherwise specified, passing {@code null} or an array or collection containing a {@code null} element as an * argument to a constructor or method of any Class-File API class or interface will cause a {@link NullPointerException} * to be thrown. * *

Reading Attributes

* The general way to obtain attributes is through {@link AttributedElement}. In addition to that, many attributes * implement {@link ClassElement}, {@link FieldElement}, {@link MethodElement}, or {@link CodeElement}, and these * attributes are generally delivered when their enclosing elements are viewed as {@link CompoundElement}s in streaming * traversal, unless otherwise specified. *

* When read from {@code class} files, the attributes are lazily inflated; the contents of these attributes are not * evaluated to speed up parsing, and user-defined attributes from {@link AttributeMapper#readAttribute} 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 {@code class} file. * These entries provide conversion methods to view them as validated symbolic descriptors. Check {@link * 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 {@link Deprecated} annotation: * {@snippet lang="java" class="PackageSnippets" region="hasDeprecated"} *

* Due to the lazy nature of {@code class} file parsing, {@link IllegalArgumentException} indicating malformed * {@code 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 * {@link IllegalArgumentException} and skip, instead of propagating the failure, on such attributes. * *

Writing Attributes

* Most attributes implement at least one of {@link ClassElement}, {@link FieldElement}, {@link MethodElement}, or * {@link CodeElement}, so they can be sent to the respective {@link ClassFileBuilder} to be written as part of those * structure. Attributes define if they can {@linkplain AttributeMapper#allowMultiple() 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 {@link 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 {@link * 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 {@code class} file generation; * see "{@linkplain java.lang.classfile.constantpool##writing 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 {@link * AttributeMapper#stability()} and is documented for each attribute on its modeling interface. Ability to bulk-copy * can massively speed up {@code class} file generation or transformation. In addition, in conjunction with {@link * ClassFile.AttributesProcessingOption}, attributes read from other {@code class} files that cannot confirm its data * is still valid for the currently building {@code class} file may be dropped. * * @see Attribute * @see AttributeMapper * @see Attributes * @jvms 4.7 Attributes * @since 24 */ package java.lang.classfile.attribute; import java.lang.classfile.Attribute; import java.lang.classfile.AttributeMapper; import java.lang.classfile.AttributedElement; import java.lang.classfile.Attributes; import java.lang.classfile.ClassElement; import java.lang.classfile.ClassFile; import java.lang.classfile.ClassFileBuilder; import java.lang.classfile.ClassModel; import java.lang.classfile.CodeElement; import java.lang.classfile.CompoundElement; import java.lang.classfile.CustomAttribute; import java.lang.classfile.FieldElement; import java.lang.classfile.MethodElement;