1 /*
 2  * Copyright (c) 2022, 2025, Oracle and/or its affiliates. All rights reserved.
 3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 4  *
 5  * This code is free software; you can redistribute it and/or modify it
 6  * under the terms of the GNU General Public License version 2 only, as
 7  * published by the Free Software Foundation.  Oracle designates this
 8  * particular file as subject to the "Classpath" exception as provided
 9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 package java.lang.classfile;
26 
27 import java.lang.classfile.attribute.*;
28 import java.lang.classfile.constantpool.Utf8Entry;
29 
30 import jdk.internal.classfile.impl.BoundAttribute;
31 import jdk.internal.classfile.impl.UnboundAttribute;
32 
33 /**
34  * Models an attribute (JVMS {@jvms 4.7}) in the {@code class} file format.
35  * Attributes exist on certain {@code class} file structures modeled by {@link
36  * AttributedElement}, which provides basic read access to the attributes.
37  * <p>
38  * This sealed interface hierarchy includes attributes predefined in the JVMS
39  * and JDK-specific nonstandard attributes.  Their {@linkplain #attributeMapper()
40  * mappers} are available in {@link Attributes}.  Two special subtypes of {@code
41  * Attribute} are {@link CustomAttribute}, which all user-defined attributes
42  * should extend from, and {@link UnknownAttribute}, representing attributes
43  * read from {@code class} file but are not recognized by the {@link
44  * ClassFile.AttributeMapperOption}.
45  * <p>
46  * Attributes are read through {@link AttributedElement} or element traversal of
47  * a {@link CompoundElement}; they are written through {@link ClassFileBuilder}.
48  * See {@linkplain java.lang.classfile.attribute##reading Reading Attributes}
49  * and {@linkplain java.lang.classfile.attribute##writing Writing Attributes}
50  * for more details.
51  *
52  * @param <A> the attribute type
53  * @see java.lang.classfile.attribute
54  * @see AttributeMapper
55  * @see AttributedElement
56  * @see CustomAttribute
57  * @see UnknownAttribute
58  * @jvms 4.7 Attributes
59  * @sealedGraph
60  * @since 24
61  */
62 public sealed interface Attribute<A extends Attribute<A>>
63         extends ClassFileElement
64         permits AnnotationDefaultAttribute, BootstrapMethodsAttribute,
65                 CharacterRangeTableAttribute, CodeAttribute, CompilationIDAttribute,
66                 ConstantValueAttribute, DeprecatedAttribute, EnclosingMethodAttribute,
67                 ExceptionsAttribute, InnerClassesAttribute, LineNumberTableAttribute,
68                 LocalVariableTableAttribute, LocalVariableTypeTableAttribute,
69                 MethodParametersAttribute, ModuleAttribute, ModuleHashesAttribute,
70                 ModuleMainClassAttribute, ModulePackagesAttribute, ModuleResolutionAttribute,
71                 ModuleTargetAttribute, NestHostAttribute, NestMembersAttribute,
72                 PermittedSubclassesAttribute,
73                 RecordAttribute, RuntimeInvisibleAnnotationsAttribute,
74                 RuntimeInvisibleParameterAnnotationsAttribute, RuntimeInvisibleTypeAnnotationsAttribute,
75                 RuntimeVisibleAnnotationsAttribute, RuntimeVisibleParameterAnnotationsAttribute,
76                 RuntimeVisibleTypeAnnotationsAttribute, SignatureAttribute,
77                 SourceDebugExtensionAttribute, SourceFileAttribute, SourceIDAttribute,
78                 StackMapTableAttribute, SyntheticAttribute,
79                 UnknownAttribute, BoundAttribute, UnboundAttribute, CustomAttribute {
80     /**
81      * {@return the name of the attribute}  The {@linkplain
82      * Utf8Entry#stringValue() string value} of the name is equivalent to the
83      * value of {@link AttributeMapper#name() attributeMapper().name()}.
84      * <p>
85      * If this attribute is read from a {@code class} file, this method returns
86      * the {@link Utf8Entry} indicating the attribute name in the {@code class}
87      * file.
88      */
89     Utf8Entry attributeName();
90 
91     /**
92      * {@return the {@link AttributeMapper} associated with this attribute}
93      */
94     AttributeMapper<A> attributeMapper();
95 }