Update JDK

src/main/java/io/github/dmlloyd/classfile/AccessFlags.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 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
@@ -30,37 +30,70 @@
 import io.github.dmlloyd.classfile.impl.AccessFlagsImpl;
 
 /**
- * Models the access flags for a class, method, or field.  Delivered as a
- * {@link ClassElement}, {@link FieldElement}, or {@link MethodElement}
- * when traversing the corresponding model type.
+ * Models the access flags for a class, method, or field.  The access flags
+ * appears exactly once in each class, method, or field; a {@link
+ * ClassBuilder} and a {@link FieldBuilder} chooses an unspecified default value
+ * if access flags are not provided, and a {@link MethodBuilder} is always
+ * created with access flags.
+ * <p>
+ * {@code AccessFlags} cannot be created via a factory method directly; it can
+ * be created with {@code withFlags} methods on the respective builders.
+ * <p>
+ * A {@link MethodBuilder} throws an {@link IllegalArgumentException} if it is
+ * supplied an {@code AccessFlags} object that changes the preexisting
+ * {@link ClassFile#ACC_STATIC ACC_STATIC} flag of the builder, because the
+ * access flag change may invalidate previously supplied data to the builder.
  *
+ * @apiNote
+ * The access flags of classes, methods, and fields are modeled as a standalone
+ * object to support streaming as elements for {@link ClassFileTransform}.
+ * Other access flags are not elements of a {@link CompoundElement} and thus not
+ * modeled by {@code AccessFlags}; they provide their own {@code flagsMask},
+ * {@code flags}, and {@code has} methods.
+ *
+ * @see ClassModel#flags()
+ * @see FieldModel#flags()
+ * @see MethodModel#flags()
+ * @see ClassBuilder#withFlags
+ * @see FieldBuilder#withFlags
+ * @see MethodBuilder#withFlags
  * @since 24
  */
 public sealed interface AccessFlags
         extends ClassElement, MethodElement, FieldElement
         permits AccessFlagsImpl {
 
     /**
-     * {@return the access flags, as a bit mask}
+     * {@return the access flags, as a bit mask}  It is in the range of unsigned
+     * short, {@code [0, 0xFFFF]}.
      */
     int flagsMask();
 
     /**
-     * {@return the access flags}
+     * {@return the access flags, as a set of flag enums}
+     *
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
+     * @see #location()
      */
     Set<AccessFlag> flags();
 
     /**
-     * {@return whether the specified flag is present}  The specified flag
-     * should be a valid flag for the classfile location associated with this
-     * element otherwise false is returned.
+     * {@return whether the specified flag is set}  If the specified flag
+     * is not available to this {@linkplain #location() location}, returns
+     * {@code false}.
+     *
      * @param flag the flag to test
+     * @see #location()
      */
     boolean has(AccessFlag flag);
 
     /**
-     * {@return the classfile location for this element, which is either class,
-     * method, or field}
+     * {@return the {@code class} file location for this element, which is
+     * either class, method, or field}
+     *
+     * @see AccessFlag.Location#CLASS
+     * @see AccessFlag.Location#FIELD
+     * @see AccessFlag.Location#METHOD
      */
     AccessFlag.Location location();
 }

src/main/java/io/github/dmlloyd/classfile/Annotation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 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
@@ -41,8 +41,9 @@
  * type_annotation} structure (JVMS {@jvms 4.7.20}). This model indicates the
  * interface of the annotation and a set of element-value pairs.
  * <p>
- * This model can reconstruct an annotation, given the location of the modeled structure
- * in the class file and the definition of the annotation interface.
+ * This model can reconstruct an annotation, given the location of the modeled
+ * structure in the {@code class} file and the definition of the annotation
+ * interface.
  * <p>
  * Two {@code Annotation} objects should be compared using the {@link
  * Object#equals(Object) equals} method.
@@ -54,8 +55,8 @@
  * elements with default values (JLS {@jls 9.6.2}), and whether the reconstructed annotation
  * is a container annotation for multiple annotations (JLS {@jls 9.7.5}).
  *
- * @see AnnotationElement
- * @see AnnotationValue
+ * @see java.lang.annotation.Annotation
+ * @see java.lang.reflect.AnnotatedElement Annotations in core reflection
  * @see TypeAnnotation
  * @see RuntimeVisibleAnnotationsAttribute
  * @see RuntimeInvisibleAnnotationsAttribute
@@ -70,11 +71,15 @@ public sealed interface Annotation
     /**
      * {@return the constant pool entry holding the {@linkplain Class#descriptorString
      * descriptor string} of the annotation interface}
+     *
+     * @see java.lang.annotation.Annotation#annotationType()
      */
     Utf8Entry className();
 
     /**
      * {@return the annotation interface, as a symbolic descriptor}
+     *
+     * @see java.lang.annotation.Annotation#annotationType()
      */
     default ClassDesc classSymbol() {
         return Util.fieldTypeSymbol(className());

src/main/java/io/github/dmlloyd/classfile/AnnotationElement.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 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
@@ -40,8 +40,8 @@
  * {@link Object#equals(Object) equals} method.
  *
  * @see Annotation
- * @see AnnotationValue
- *
+ * @see java.lang.reflect.AnnotatedElement Annotations in core reflection
+ * @jvms 4.7.16.1 The {@code element_value} structure
  * @since 24
  */
 public sealed interface AnnotationElement

src/main/java/io/github/dmlloyd/classfile/AnnotationValue.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 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
@@ -45,6 +45,7 @@
  *
  * @see Annotation
  * @see AnnotationElement
+ * @see java.lang.reflect.AnnotatedElement Annotations in core reflection
  *
  * @sealedGraph
  * @since 24
@@ -53,7 +54,7 @@ public sealed interface AnnotationValue {
 
     /**
      * Models an annotation value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_ANNOTATION}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_ANNOTATION}.
      *
      * @since 24
      */
@@ -65,7 +66,7 @@ sealed interface OfAnnotation extends AnnotationValue
 
     /**
      * Models an array value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_ARRAY}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_ARRAY}.
      *
      * @since 24
      */
@@ -121,7 +122,7 @@ sealed interface OfConstant extends AnnotationValue {
 
     /**
      * Models a string value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_STRING}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_STRING}.
      *
      * @since 24
      */
@@ -148,7 +149,7 @@ default String resolvedValue() {
 
     /**
      * Models a double value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_DOUBLE}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_DOUBLE}.
      *
      * @since 24
      */
@@ -175,7 +176,7 @@ default Double resolvedValue() {
 
     /**
      * Models a float value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_FLOAT}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_FLOAT}.
      *
      * @since 24
      */
@@ -202,7 +203,7 @@ default Float resolvedValue() {
 
     /**
      * Models a long value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_LONG}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_LONG}.
      *
      * @since 24
      */
@@ -229,7 +230,7 @@ default Long resolvedValue() {
 
     /**
      * Models an int value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_INT}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_INT}.
      *
      * @since 24
      */
@@ -256,7 +257,7 @@ default Integer resolvedValue() {
 
     /**
      * Models a short value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_SHORT}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_SHORT}.
      *
      * @since 24
      */
@@ -286,7 +287,7 @@ default Short resolvedValue() {
 
     /**
      * Models a char value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_CHAR}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_CHAR}.
      *
      * @since 24
      */
@@ -316,7 +317,7 @@ default Character resolvedValue() {
 
     /**
      * Models a byte value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_BYTE}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_BYTE}.
      *
      * @since 24
      */
@@ -346,7 +347,7 @@ default Byte resolvedValue() {
 
     /**
      * Models a boolean value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_BOOLEAN}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_BOOLEAN}.
      *
      * @since 24
      */
@@ -376,7 +377,7 @@ default Boolean resolvedValue() {
 
     /**
      * Models a class value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_CLASS}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_CLASS}.
      *
      * @since 24
      */
@@ -393,7 +394,7 @@ default ClassDesc classSymbol() {
 
     /**
      * Models an enum value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_ENUM}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_ENUM}.
      *
      * @since 24
      */

src/main/java/io/github/dmlloyd/classfile/Attribute.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 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
@@ -31,15 +31,31 @@
 import io.github.dmlloyd.classfile.impl.UnboundAttribute;
 
 /**
- * Models a classfile attribute (JVMS {@jvms 4.7}).  Many, though not all, subtypes of
- * {@linkplain Attribute} will implement {@link ClassElement}, {@link
- * MethodElement}, {@link FieldElement}, or {@link CodeElement}; attributes that
- * are also elements will be delivered when traversing the elements of the
- * corresponding model type. Additionally, all attributes are accessible
- * directly from the corresponding model type through {@link
- * AttributedElement#findAttribute(AttributeMapper)}.
- * @param <A> the attribute type
+ * Models an attribute (JVMS {@jvms 4.7}) in the {@code class} file format.
+ * Attributes exist on certain {@code class} file structures modeled by {@link
+ * AttributedElement}, which provides basic read access to the attributes.
+ * <p>
+ * This sealed interface hierarchy includes attributes predefined in the JVMS
+ * and JDK-specific nonstandard attributes.  Their {@linkplain #attributeMapper()
+ * mappers} are available in {@link Attributes}.  Two special subtypes of {@code
+ * Attribute} are {@link CustomAttribute}, which all user-defined attributes
+ * should extend from, and {@link UnknownAttribute}, representing attributes
+ * read from {@code class} file but are not recognized by the {@link
+ * ClassFile.AttributeMapperOption}.
+ * <p>
+ * Attributes are read through {@link AttributedElement} or element traversal of
+ * a {@link CompoundElement}; they are written through {@link ClassFileBuilder}.
+ * See {@linkplain io.github.dmlloyd.classfile.attribute##reading Reading Attributes}
+ * and {@linkplain io.github.dmlloyd.classfile.attribute##writing Writing Attributes}
+ * for more details.
  *
+ * @param <A> the attribute type
+ * @see io.github.dmlloyd.classfile.attribute
+ * @see AttributeMapper
+ * @see AttributedElement
+ * @see CustomAttribute
+ * @see UnknownAttribute
+ * @jvms 4.7 Attributes
  * @sealedGraph
  * @since 24
  */
@@ -62,7 +78,13 @@ public sealed interface Attribute<A extends Attribute<A>>
                 StackMapTableAttribute, SyntheticAttribute,
                 UnknownAttribute, BoundAttribute, UnboundAttribute, CustomAttribute {
     /**
-     * {@return the name of the attribute}
+     * {@return the name of the attribute}  The {@linkplain
+     * Utf8Entry#stringValue() string value} of the name is equivalent to the
+     * value of {@link AttributeMapper#name() attributeMapper().name()}.
+     * <p>
+     * If this attribute is read from a {@code class} file, this method returns
+     * the {@link Utf8Entry} indicating the attribute name in the {@code class}
+     * file.
      */
     Utf8Entry attributeName();