> {
/**
- * Attribute stability indicator
+ * Indicates the data dependency of the {@code class} file representation
+ * of an attribute. Whether an attribute can be bulk-copied by its binary
+ * representation to a new {@code class} file depends on if its data refers
+ * to other parts of its enclosing {@code class} file.
*
+ * @apiNote
+ * This dependency is called "stability" because it indicates the conditions
+ * for a {@code class} file attribute to be eligible for bulk-copying to
+ * another {@code class} file.
+ *
+ * @see AttributeMapper#stability()
* @since 24
*/
enum AttributeStability {
/**
- * The attribute contains only pure data, such as timestamps, and can always be bulk-copied.
+ * The attribute contains only standalone data, and has no reference to
+ * other parts of its enclosing {@code class} file, besides the name of
+ * the attribute. Thus, its contents can always be bulk-copied to
+ * another {@code class} file.
+ *
+ * For example, a bit mask is standalone data.
*/
STATELESS,
/**
- * The attribute contains only pure data and CP refs, so can be bulk-copied when CP sharing is in effect,
- * and need to be exploded and rewritten when CP sharing is not in effect.
+ * In addition to standalone data, the attribute refers to the constant
+ * pool, including the {@link BootstrapMethodsAttribute BootstrapMethods}
+ * attribute, of its enclosing {@code class} file. Thus, it can be
+ * bulk-copied when the destination {@code class} file extends its
+ * constant pool from that of the original {@code class}. It must be
+ * expanded to translate constant pool references and rewritten when
+ * constant pool indices are not compatible.
+ *
+ * For example, a {@link Utf8Entry} is a reference to the constant pool.
+ *
+ * @see ConstantPoolBuilder#of(ClassModel)
+ * @see ClassFile.ConstantPoolSharingOption
*/
CP_REFS,
/**
- * The attribute may contain labels, so need to be exploded and rewritten when the Code array is perturbed.
+ * In addition to standalone data and references to the constant pool,
+ * the attribute refers to positions into the {@code code} array of a
+ * {@link CodeAttribute Code} attribute. Thus, it can be bulked-copied
+ * when the {@code code} array is unchanged, which requires that the
+ * destination {@code class} file extends its constant pool from that of
+ * the original {@code class}. It must be expanded to translate {@link
+ * Label}s or constant pool references and rewritten if the {@code code}
+ * array is perturbed, including when constant pool indices are not
+ * compatible.
+ *
+ * For example, a bci value, modeled by a {@link Label}, is a reference
+ * to a position in the {@code code} array.
*/
LABELS,
/**
- * The attribute may contain indexes into structured not managed by the library (type variable lists, etc)
- * and so we consult the {@link ClassFile.AttributesProcessingOption} option to determine whether to preserve
- * or drop it during transformation.
+ * The attribute refers to structures not managed by the library (type
+ * variable lists, etc.). As a result, even when the attribute is
+ * expanded, those references may not be correctly translated, and the
+ * rewritten results may be incorrect.
+ *
+ * If the attribute is read from a {@code class} file, {@link
+ * ClassFile.AttributesProcessingOption} determines whether to preserve
+ * or drop the attribute during transformation.
+ *
+ * @see ClassFile.AttributesProcessingOption#DROP_UNSTABLE_ATTRIBUTES
*/
UNSTABLE,
/**
- * The attribute is completely unknown and so we consult the {@link ClassFile.AttributesProcessingOption} option
- * to determine whether to preserve or drop it during transformation.
+ * The attribute is completely unknown. As a result, expanding and
+ * rewriting is not possible, and any difference between the destination
+ * {@code class} file and its enclosing {@code class} file may make the
+ * attribute incorrect.
+ *
+ * {@link ClassFile.AttributesProcessingOption} determines whether to
+ * preserve or drop the attribute during transformation.
+ *
+ * @see UnknownAttribute
+ * @see ClassFile.AttributesProcessingOption#DROP_UNSTABLE_ATTRIBUTES
+ * @see ClassFile.AttributesProcessingOption#DROP_UNKNOWN_ATTRIBUTES
*/
UNKNOWN
}
@@ -82,35 +146,104 @@ enum AttributeStability {
String name();
/**
- * Create an {@link Attribute} instance from a classfile.
+ * Creates an {@link Attribute} instance from a {@code class} file for the
+ * Class-File API.
+ *
+ * This method is called by the Class-File API to support reading of
+ * attributes. Users should never call this method.
+ *
+ * The Class-File API makes these promises about the call to this method:
+ *
+ * - The {@link Utf8Entry} for the name of the attribute is accessible
+ * with {@code cf.readEntry(pos - 6, Utf8Entry.class)}, and is validated;
+ *
- The length of the attribute is accessible with {@code cf.readInt(pos
+ * - 4)}, and is validated to be positive and not beyond the length of the
+ * {@code class} file;
+ *
- The {@link AttributedElement} attribute access functionalities on the
+ * {@code enclosing} model may not be accessed when this method is called,
+ * but can be accessed later by the returned attribute when it is accessible
+ * to users.
+ *
+ *
+ * The returned {@code Attribute} must fulfill these requirements:
+ *
+ * - {@link Attribute#attributeMapper()} returns this mapper;
+ *
- {@link Attribute#attributeName()} returns the attribute name in the
+ * {@code class} file.
+ *
+ *
+ * @apiNote
+ * Implementations of this method should perform minimal work to return an
+ * attribute, as this method is called even if the resulting attribute is
+ * never used. In particular, the implementation should avoid checking the
+ * validity of the attribute {@code class} file data or performing actions
+ * that may throw exceptions.
*
- * @param enclosing The class, method, field, or code attribute in which
- * this attribute appears
- * @param cf The {@link ClassReader} describing the classfile to read from
- * @param pos The offset into the classfile at which the attribute starts
- * @return the new attribute
+ * @param enclosing the structure in which this attribute appears
+ * @param cf provides access to the {@code class} file to read from
+ * @param pos the offset into the {@code class} file at which the contents
+ * of the attribute starts
+ * @return the read attribute
*/
A readAttribute(AttributedElement enclosing, ClassReader cf, int pos);
/**
- * Write an {@link Attribute} instance to a classfile.
+ * Writes an {@link Attribute} instance to a {@code class} file for the
+ * Class-File API.
+ *
+ * This method is called by the Class-File API to support writing of
+ * attributes. Users should never call this method.
+ *
+ * The Class-File API makes these promises about the call to this method:
+ *
+ * - {@link Attribute#attributeMapper() attr.attributeMapper()} returns
+ * this mapper;
+ *
- The {@code buf} may already have data written, that its {@link
+ * BufWriter#size() size} may not be {@code 0}.
+ *
+ *
+ * The {@code class} file writing must fulfill these requirements:
+ *
+ * - The attribute name {@code u2} and attribute length {@code u4} must
+ * be written to the {@code buf};
+ *
- {@link Attribute#attributeName() attr.attributeName()} is written as
+ * if with {@code buf.writeIndex(attr.attributeName())};
+ *
- The attribute length is the length, in bytes, of attribute contents
+ * written to the {@code buf}, not including the 6 bytes used by the name
+ * and the length;
+ *
- If any information in the API model of the attribute, {@code attr},
+ * cannot be represented in the {@code class} file format of the attribute,
+ * an {@link IllegalArgumentException} is thrown.
+ *
+ *
+ * @apiNote
+ * {@link BufWriter#patchInt} can be used to update the attribute length
+ * after the attribute contents are written to the {@code buf}.
*
- * @param buf The {@link BufWriter} to which the attribute should be written
- * @param attr The attribute to write
+ * @param buf the {@link BufWriter} to which the attribute should be written
+ * @param attr the attribute to write
+ * @throws IllegalArgumentException if some data in the API model of the
+ * attribute is invalid for the {@code class} file format
*/
void writeAttribute(BufWriter buf, A attr);
/**
- * {@return whether this attribute may appear more than once in a given location}
+ * {@return whether this attribute may appear more than once in one
+ * structure}
+ *
+ * If an attribute does not allow multiple instances in one structure,
+ * can be supplied to a {@link ClassFileBuilder}, and multiple instances of
+ * the attribute are supplied to the builder, the last supplied attribute
+ * appears on the built structure.
*
- * @implSpec The default implementation returns {@code false}
+ * @implSpec The default implementation returns {@code false}.
*/
default boolean allowMultiple() {
return false;
}
/**
- * {@return attribute stability indicator}
+ * {@return the data dependency of this attribute on the {@code class} file}
*/
AttributeStability stability();
}
diff --git a/src/java.base/share/classes/java/lang/classfile/AttributedElement.java b/src/java.base/share/classes/java/lang/classfile/AttributedElement.java
index 478ad1e3f0a..0edb79a863d 100644
--- a/src/java.base/share/classes/java/lang/classfile/AttributedElement.java
+++ b/src/java.base/share/classes/java/lang/classfile/AttributedElement.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
@@ -24,6 +24,7 @@
*/
package java.lang.classfile;
+import java.lang.classfile.attribute.CodeAttribute;
import java.lang.classfile.attribute.RecordComponentInfo;
import java.util.ArrayList;
import java.util.Collections;
@@ -35,9 +36,11 @@
import static java.util.Objects.requireNonNull;
/**
- * A {@link ClassFileElement} describing an entity that has attributes, such
- * as a class, field, method, code attribute, or record component.
+ * A {@link ClassFileElement} describing a {@code class} file structure that has
+ * attributes, such as a {@code class} file, a field, a method, a {@link
+ * CodeAttribute Code} attribute, or a record component.
*
+ * @jvms 4.7 Attributes
* @sealedGraph
* @since 24
*/
@@ -46,15 +49,28 @@ public sealed interface AttributedElement extends ClassFileElement
RecordComponentInfo, AbstractUnboundModel {
/**
- * {@return the attributes of this element}
+ * {@return the attributes of this structure}
*/
List> attributes();
/**
- * Finds an attribute by name.
+ * Finds an attribute by name. This is suitable to find attributes that
+ * {@linkplain AttributeMapper#allowMultiple() allow at most one instance}
+ * in one structure. If this is used to find attributes that allow multiple
+ * instances in one structure, the first matching instance is returned.
+ *
+ * @apiNote
+ * This can easily find an attribute and send it to another {@link
+ * ClassFileBuilder}, which is a {@code Consumer}:
+ * {@snippet lang=java :
+ * MethodModel method = null; // @replace substring=null; replacement=...
+ * MethodBuilder mb = null; // @replace substring=null; replacement=...
+ * method.findAttribute(Attributes.code()).ifPresent(mb);
+ * }
+ *
* @param attr the attribute mapper
* @param the type of the attribute
- * @return the attribute, or an empty {@linkplain Optional} if the attribute
+ * @return the attribute, or {@code Optional.empty()} if the attribute
* is not present
*/
default > Optional findAttribute(AttributeMapper attr) {
@@ -70,10 +86,13 @@ default > Optional findAttribute(AttributeMapper at
}
/**
- * Finds one or more attributes by name.
+ * Finds attributes by name. This is suitable to find attributes that
+ * {@linkplain AttributeMapper#allowMultiple() allow multiple instances}
+ * in one structure.
+ *
* @param attr the attribute mapper
* @param the type of the attribute
- * @return the attributes, or an empty {@linkplain List} if the attribute
+ * @return the attributes, or an empty {@code List} if the attribute
* is not present
*/
default > List findAttributes(AttributeMapper attr) {
diff --git a/src/java.base/share/classes/java/lang/classfile/Attributes.java b/src/java.base/share/classes/java/lang/classfile/Attributes.java
index 24684a36b02..eaa0fec5a4e 100644
--- a/src/java.base/share/classes/java/lang/classfile/Attributes.java
+++ b/src/java.base/share/classes/java/lang/classfile/Attributes.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,64 +30,20 @@
import jdk.internal.classfile.impl.AbstractAttributeMapper.*;
/**
- * Attribute mappers for standard classfile attributes.
+ * Attribute mappers for predefined (JVMS {@jvms 4.7}) and JDK-specific
+ * nonstandard attributes.
*
- * Unless otherwise specified, mappers returned by each method
- * do not permit multiple attribute instances in a given location.
- *
- * The most stable {@link AttributeStability#STATELESS STATELESS} mappers are:
- *
- * - {@link #deprecated()}
- *
- {@link #moduleResolution()}
- *
- {@link #sourceDebugExtension()}
- *
- {@link #synthetic()}
- *
- *
- * The mappers with {@link AttributeStability#CP_REFS CP_REFS} stability are:
- *
- * - {@link #annotationDefault()}
- *
- {@link #bootstrapMethods()}
- *
- {@link #code()}
- *
- {@link #compilationId()}
- *
- {@link #constantValue()}
- *
- {@link #enclosingMethod()}
- *
- {@link #exceptions()}
- *
- {@link #innerClasses()}
- *
- {@link #methodParameters()}
- *
- {@link #module()}
- *
- {@link #moduleHashes()}
- *
- {@link #moduleMainClass()}
- *
- {@link #modulePackages()}
- *
- {@link #moduleTarget()}
- *
- {@link #nestHost()}
- *
- {@link #nestMembers()}
- *
- {@link #permittedSubclasses()}
- *
- {@link #record()}
- *
- {@link #runtimeInvisibleAnnotations()}
- *
- {@link #runtimeInvisibleParameterAnnotations()}
- *
- {@link #runtimeVisibleAnnotations()}
- *
- {@link #runtimeVisibleParameterAnnotations()}
- *
- {@link #signature()}
- *
- {@link #sourceFile()}
- *
- {@link #sourceId()}
- *
- *
- * The mappers with {@link AttributeStability#LABELS LABELS} stability are:
+ * Unless otherwise specified, each mapper returned by methods in this class:
*
- * - {@link #characterRangeTable()}
- *
- {@link #lineNumberTable()}
- *
- {@link #localVariableTable()}
- *
- {@link #localVariableTypeTable()}
- *
- *
- * The {@link AttributeStability#UNSTABLE UNSTABLE} mappers are:
- *
- * - {@link #runtimeInvisibleTypeAnnotations()}
- *
- {@link #runtimeVisibleTypeAnnotations()}
+ *
- is predefined in the JVMS instead of JDK-specific;
+ *
- does not permit {@linkplain AttributeMapper#allowMultiple() multiple
+ * attribute instances} in the same structure;
+ *
- the attribute has a {@linkplain AttributeMapper#stability() data
+ * dependency} on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
*
* @see AttributeMapper
- *
+ * @see java.lang.classfile.attribute
* @since 24
*/
public final class Attributes {
@@ -204,258 +160,278 @@ private Attributes() {
}
/**
- * {@return Attribute mapper for the {@code AnnotationDefault} attribute}
+ * {@return the mapper for the {@code AnnotationDefault} attribute}
*/
public static AttributeMapper annotationDefault() {
return AnnotationDefaultMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code BootstrapMethods} attribute}
+ * {@return the mapper for the {@code BootstrapMethods} attribute}
*/
public static AttributeMapper bootstrapMethods() {
return BootstrapMethodsMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code CharacterRangeTable} attribute}
- * The mapper permits multiple instances in a given location.
+ * {@return the mapper for the {@code CharacterRangeTable} attribute}
+ * This is a JDK-specific attribute.
+ * The mapper permits multiple instances in a {@code Code} attribute, but this
+ * attribute should be only emitted once.
+ * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
*/
public static AttributeMapper characterRangeTable() {
return CharacterRangeTableMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code Code} attribute}
+ * {@return the mapper for the {@code Code} attribute}
*/
public static AttributeMapper code() {
return CodeMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code CompilationID} attribute}
+ * {@return the mapper for the {@code CompilationID} attribute}
+ * This is a JDK-specific attribute.
*/
public static AttributeMapper compilationId() {
return CompilationIDMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code ConstantValue} attribute}
+ * {@return the mapper for the {@code ConstantValue} attribute}
*/
public static AttributeMapper constantValue() {
return ConstantValueMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code Deprecated} attribute}
+ * {@return the mapper for the {@code Deprecated} attribute}
* The mapper permits multiple instances in a given location.
+ * This has {@linkplain AttributeStability#STATELESS no data dependency}.
*/
public static AttributeMapper deprecated() {
return DeprecatedMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code EnclosingMethod} attribute}
+ * {@return the mapper for the {@code EnclosingMethod} attribute}
*/
public static AttributeMapper enclosingMethod() {
return EnclosingMethodMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code Exceptions} attribute}
+ * {@return the mapper for the {@code Exceptions} attribute}
*/
public static AttributeMapper exceptions() {
return ExceptionsMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code InnerClasses} attribute}
+ * {@return the mapper for the {@code InnerClasses} attribute}
*/
public static AttributeMapper innerClasses() {
return InnerClassesMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code LineNumberTable} attribute}
- * The mapper permits multiple instances in a given location.
+ * {@return the mapper for the {@code LineNumberTable} attribute}
+ * The mapper permits multiple instances in a {@code Code} attribute.
+ * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
*/
public static AttributeMapper lineNumberTable() {
return LineNumberTableMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code LocalVariableTable} attribute}
- * The mapper permits multiple instances in a given location.
+ * {@return the mapper for the {@code LocalVariableTable} attribute}
+ * The mapper permits multiple instances in a {@code Code} attribute.
+ * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
*/
public static AttributeMapper localVariableTable() {
return LocalVariableTableMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code LocalVariableTypeTable} attribute}
+ * {@return the mapper for the {@code LocalVariableTypeTable} attribute}
* The mapper permits multiple instances in a given location.
+ * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
*/
public static AttributeMapper localVariableTypeTable() {
return LocalVariableTypeTableMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code MethodParameters} attribute}
+ * {@return the mapper for the {@code MethodParameters} attribute}
*/
public static AttributeMapper methodParameters() {
return MethodParametersMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code Module} attribute}
+ * {@return the mapper for the {@code Module} attribute}
*/
public static AttributeMapper module() {
return ModuleMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code ModuleHashes} attribute}
+ * {@return the mapper for the {@code ModuleHashes} attribute}
+ * This is a JDK-specific attribute.
*/
public static AttributeMapper moduleHashes() {
return ModuleHashesMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code ModuleMainClass} attribute}
+ * {@return the mapper for the {@code ModuleMainClass} attribute}
*/
public static AttributeMapper moduleMainClass() {
return ModuleMainClassMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code ModulePackages} attribute}
+ * {@return the mapper for the {@code ModulePackages} attribute}
*/
public static AttributeMapper modulePackages() {
return ModulePackagesMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code ModuleResolution} attribute}
+ * {@return the mapper for the {@code ModuleResolution} attribute}
+ * This is a JDK-specific attribute.
+ * This has {@linkplain AttributeStability#STATELESS no data dependency}.
*/
public static AttributeMapper moduleResolution() {
return ModuleResolutionMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code ModuleTarget} attribute}
+ * {@return the mapper for the {@code ModuleTarget} attribute}
+ * This is a JDK-specific attribute.
*/
public static AttributeMapper moduleTarget() {
return ModuleTargetMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code NestHost} attribute}
+ * {@return the mapper for the {@code NestHost} attribute}
*/
public static AttributeMapper nestHost() {
return NestHostMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code NestMembers} attribute}
+ * {@return the mapper for the {@code NestMembers} attribute}
*/
public static AttributeMapper nestMembers() {
return NestMembersMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code PermittedSubclasses} attribute}
+ * {@return the mapper for the {@code PermittedSubclasses} attribute}
*/
public static AttributeMapper permittedSubclasses() {
return PermittedSubclassesMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code Record} attribute}
+ * {@return the mapper for the {@code Record} attribute}
*/
public static AttributeMapper record() {
return RecordMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code RuntimeInvisibleAnnotations} attribute}
+ * {@return the mapper for the {@code RuntimeInvisibleAnnotations} attribute}
*/
public static AttributeMapper runtimeInvisibleAnnotations() {
return RuntimeInvisibleAnnotationsMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code RuntimeInvisibleParameterAnnotations} attribute}
+ * {@return the mapper for the {@code RuntimeInvisibleParameterAnnotations} attribute}
*/
public static AttributeMapper runtimeInvisibleParameterAnnotations() {
return RuntimeInvisibleParameterAnnotationsMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code RuntimeInvisibleTypeAnnotations} attribute}
+ * {@return the mapper for the {@code RuntimeInvisibleTypeAnnotations} attribute}
+ * This has a data dependency on {@linkplain AttributeStability#UNSTABLE
+ * arbitrary indices} in the {@code class} file format.
*/
public static AttributeMapper runtimeInvisibleTypeAnnotations() {
return RuntimeInvisibleTypeAnnotationsMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code RuntimeVisibleAnnotations} attribute}
+ * {@return the mapper for the {@code RuntimeVisibleAnnotations} attribute}
*/
public static AttributeMapper runtimeVisibleAnnotations() {
return RuntimeVisibleAnnotationsMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code RuntimeVisibleParameterAnnotations} attribute}
+ * {@return the mapper for the {@code RuntimeVisibleParameterAnnotations} attribute}
*/
public static AttributeMapper runtimeVisibleParameterAnnotations() {
return RuntimeVisibleParameterAnnotationsMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code RuntimeVisibleTypeAnnotations} attribute}
+ * {@return the mapper for the {@code RuntimeVisibleTypeAnnotations} attribute}
+ * This has a data dependency on {@linkplain AttributeStability#UNSTABLE
+ * arbitrary indices} in the {@code class} file format.
*/
public static AttributeMapper runtimeVisibleTypeAnnotations() {
return RuntimeVisibleTypeAnnotationsMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code Signature} attribute}
+ * {@return the mapper for the {@code Signature} attribute}
*/
public static AttributeMapper signature() {
return SignatureMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code SourceDebugExtension} attribute}
+ * {@return the mapper for the {@code SourceDebugExtension} attribute}
+ * This has {@linkplain AttributeStability#STATELESS no data dependency}.
*/
public static AttributeMapper sourceDebugExtension() {
return SourceDebugExtensionMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code SourceFile} attribute}
+ * {@return the mapper for the {@code SourceFile} attribute}
*/
public static AttributeMapper sourceFile() {
return SourceFileMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code SourceID} attribute}
+ * {@return the mapper for the {@code SourceID} attribute}
+ * This is a JDK-specific attribute.
*/
public static AttributeMapper sourceId() {
return SourceIDMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code StackMapTable} attribute}
+ * {@return the mapper for the {@code StackMapTable} attribute}
+ * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
*/
public static AttributeMapper stackMapTable() {
return StackMapTableMapper.INSTANCE;
}
/**
- * {@return Attribute mapper for the {@code Synthetic} attribute}
+ * {@return the mapper for the {@code Synthetic} attribute}
* The mapper permits multiple instances in a given location.
+ * This has {@linkplain AttributeStability#STATELESS no data dependency}.
*/
public static AttributeMapper synthetic() {
return SyntheticMapper.INSTANCE;
diff --git a/src/java.base/share/classes/java/lang/classfile/BufWriter.java b/src/java.base/share/classes/java/lang/classfile/BufWriter.java
index c6779583eb1..81528401d77 100644
--- a/src/java.base/share/classes/java/lang/classfile/BufWriter.java
+++ b/src/java.base/share/classes/java/lang/classfile/BufWriter.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
@@ -27,120 +27,163 @@
import java.lang.classfile.constantpool.ConstantPool;
import java.lang.classfile.constantpool.ConstantPoolBuilder;
import java.lang.classfile.constantpool.PoolEntry;
+import java.nio.ByteOrder;
import jdk.internal.classfile.impl.BufWriterImpl;
/**
- * Supports writing portions of a classfile to a growable buffer. Methods
- * are provided to write various standard entities (e.g., {@code u2}, {@code u4})
- * to the end of the buffer, as well as to create constant pool entries.
+ * Advanced {@code class} file writing support for {@link AttributeMapper}s.
+ * Supports writing portions of a {@code class} file to a growable buffer, such
+ * as writing various numerical types (e.g., {@code u2}, {@code u4}), to the end
+ * of the buffer, as well as to create constant pool entries.
+ *
+ * All numeric values in the {@code class} file format are {@linkplain
+ * ByteOrder#BIG_ENDIAN big endian}. Writing larger numeric values to smaller
+ * numeric values are always done with truncation, that the least significant
+ * bytes are kept and the other bytes are silently dropped. As a result,
+ * numeric value writing methods can write both signed and unsigned values, and
+ * users should validate their values before writing if silent dropping of most
+ * significant bytes is not the intended behavior.
*
+ * @see AttributeMapper#writeAttribute(BufWriter, Attribute)
* @since 24
*/
public sealed interface BufWriter
permits BufWriterImpl {
- /** {@return the constant pool builder associated with this buffer} */
+ /**
+ * {@return the constant pool builder associated with this buffer}
+ *
+ * @see ClassFileBuilder#constantPool()
+ */
ConstantPoolBuilder constantPool();
/**
- * {@return whether the provided constant pool is index-compatible with this
- * one} This may be because they are the same constant pool, or because this
- * constant pool was copied from the other.
+ * {@return whether the provided constant pool is index-compatible with the
+ * constant pool of this buffer}
+ *
+ * This is a shortcut for {@code constantPool().canWriteDirect(other)}.
*
* @param other the other constant pool
+ * @see ConstantPoolBuilder#canWriteDirect(ConstantPool)
*/
boolean canWriteDirect(ConstantPool other);
/**
- * Ensure that the buffer has at least {@code freeBytes} bytes of unused space
+ * Ensures that the buffer has at least {@code freeBytes} bytes of free space
+ * in the end of the buffer.
+ *
+ * The writing result is the same without calls to this method, but the
+ * writing process may be slower.
+ *
+ * @apiNote
+ * This is a hint that changes no visible state of the buffer; it helps to
+ * reduce reallocation of the underlying storage by allocating sufficient
+ * space at once.
+ *
* @param freeBytes the number of bytes to reserve
*/
void reserveSpace(int freeBytes);
/**
- * Write an unsigned byte to the buffer
+ * Writes a byte to the buffer. {@code x} is truncated to a byte and
+ * written.
*
- * @param x the byte value
+ * @param x the value to truncate to a byte
*/
void writeU1(int x);
/**
- * Write an unsigned short to the buffer
+ * Writes 2 bytes, or a short, to the buffer. {@code x} is truncated to two
+ * bytes and written.
*
- * @param x the short value
+ * @param x the value to truncate to a short
*/
void writeU2(int x);
/**
- * Write a signed int to the buffer
+ * Writes 4 bytes, or an int, to the buffer.
*
* @param x the int value
*/
void writeInt(int x);
/**
- * Write a float value to the buffer
+ * Writes a float value, of 4 bytes, to the buffer.
+ *
+ * In the conversions, all NaN values of the {@code float} may or may not be
+ * collapsed into a single {@linkplain Float#NaN "canonical" NaN value}.
*
* @param x the float value
*/
void writeFloat(float x);
/**
- * Write a long value to the buffer
+ * Writes 8 bytes, or a long, to the buffer.
*
* @param x the long value
*/
void writeLong(long x);
/**
- * Write a double value to the buffer
+ * Writes a double value, of 8 bytes, to the buffer.
+ *
+ * In the conversions, all NaN values of the {@code double} may or may not
+ * be collapsed into a single {@linkplain Double#NaN "canonical" NaN value}.
*
- * @param x the int value
+ * @param x the double value
*/
void writeDouble(double x);
/**
- * Write the contents of a byte array to the buffer
+ * Writes the contents of a byte array to the buffer.
*
* @param arr the byte array
*/
void writeBytes(byte[] arr);
/**
- * Write a range of a byte array to the buffer
+ * Writes a range of a byte array to the buffer.
*
* @param arr the byte array
- * @param start the offset within the byte array of the range
+ * @param start the start offset of the range within the byte array
* @param length the length of the range
- * @throws IndexOutOfBoundsException if range is outside of the array bounds
+ * @throws IndexOutOfBoundsException if range is outside the array bounds
*/
void writeBytes(byte[] arr, int start, int length);
/**
- * Patch a previously written integer value. Depending on the specified
- * size, the entire value, or the low 1 or 2 bytes, may be written.
+ * Patches a previously written integer value. {@code value} is truncated
+ * to the given {@code size} number of bytes and written at the given {@code
+ * offset}. The end of this buffer stays unchanged.
+ *
+ * @apiNote
+ * The {@code offset} can be obtained by calling {@link #size()} before
+ * writing the previous integer value.
*
- * @param offset the offset at which to patch
+ * @param offset the offset in this buffer at which to patch
* @param size the size of the integer value being written, in bytes
- * @param value the integer value
+ * @param value the integer value to be truncated
* @throws IndexOutOfBoundsException if patched int is outside of bounds
+ * @see #size()
*/
void patchInt(int offset, int size, int value);
/**
- * Write a 1, 2, 4, or 8 byte integer value to the buffer. Depending on
- * the specified size, the entire value, or the low 1, 2, or 4 bytes, may
- * be written.
+ * Writes a multibyte value to the buffer. {@code intValue} is truncated
+ * to the given {@code intSize} number of bytes and written.
*
* @param intSize the size of the integer value being written, in bytes
- * @param intValue the integer value
+ * @param intValue the value to be truncated
*/
void writeIntBytes(int intSize, long intValue);
/**
- * Write the index of the specified constant pool entry, as a {@code u2},
- * to the buffer
+ * Writes the index of the specified constant pool entry as a {@link
+ * #writeU2 u2}. If the {@code entry} does not belong to the {@linkplain
+ * #constantPool() constant pool} of this buffer, it will be {@linkplain
+ * ConstantPoolBuilder##alien converted}, and the index of the converted
+ * pool entry is written instead.
*
* @param entry the constant pool entry
* @throws IllegalArgumentException if the entry has invalid index
@@ -148,16 +191,23 @@ public sealed interface BufWriter
void writeIndex(PoolEntry entry);
/**
- * Write the index of the specified constant pool entry, as a {@code u2},
- * to the buffer, or zero if the entry is null
+ * Writes the index of the specified constant pool entry, or the value
+ * {@code 0} if the specified entry is {@code null}, as a {@link #writeU2
+ * u2}. If the {@code entry} does not belong to the {@linkplain
+ * #constantPool() constant pool} of this buffer, it will be {@linkplain
+ * ConstantPoolBuilder##alien converted}, and the index of the converted
+ * pool entry is written instead.
*
- * @param entry the constant pool entry
- * @throws IllegalArgumentException if the entry has invalid index
+ * @param entry the constant pool entry, may be {@code null}
+ * @throws IllegalArgumentException if the entry is not {@code null} and has
+ * invalid index
*/
void writeIndexOrZero(PoolEntry entry);
/**
* {@return the number of bytes that have been written to the buffer}
+ *
+ * @see #patchInt(int, int, int)
*/
int size();
}
diff --git a/src/java.base/share/classes/java/lang/classfile/ClassReader.java b/src/java.base/share/classes/java/lang/classfile/ClassReader.java
index 93f2ac5c810..3de188af8b3 100644
--- a/src/java.base/share/classes/java/lang/classfile/ClassReader.java
+++ b/src/java.base/share/classes/java/lang/classfile/ClassReader.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
@@ -35,12 +35,21 @@
import jdk.internal.classfile.impl.ClassReaderImpl;
/**
- * Supports reading from a classfile. Methods are provided to read data of
- * various numeric types (e.g., {@code u2}, {@code u4}) at a given offset within
- * the classfile, copying raw bytes, and reading constant pool entries.
- * Encapsulates additional reading context such as mappers for custom attributes
- * and processing options.
+ * Advanced {@code class} file reading support for {@link AttributeMapper}s.
+ * Supports reading arbitrary offsets within a {@code class} file and reading
+ * data of various numeric types (e.g., {@code u2}, {@code u4}) in addition to
+ * constant pool access.
+ *
+ * All numeric values in the {@code class} file format are {@linkplain
+ * java.nio.ByteOrder#BIG_ENDIAN big endian}.
+ *
+ * Unless otherwise specified, all out-of-bounds access result in an {@link
+ * IllegalArgumentException} to indicate the {@code class} file data is
+ * malformed. Since the {@code class} file data is arbitrary, users should
+ * sanity-check the structural integrity of the data before attempting to
+ * interpret the potentially malformed data.
*
+ * @see AttributeMapper#readAttribute(AttributedElement, ClassReader, int)
* @since 24
*/
public sealed interface ClassReader extends ConstantPool
@@ -56,29 +65,41 @@ public sealed interface ClassReader extends ConstantPool
// Class context
- /** {@return the access flags for the class, as a bit mask } */
+ /**
+ * {@return the access flags for the class, as a bit mask}
+ *
+ * @see ClassModel#flags()
+ */
int flags();
- /** {@return the constant pool entry describing the name of class} */
+ /**
+ * {@return the constant pool entry describing the name of class}
+ *
+ * @see ClassModel#thisClass()
+ */
ClassEntry thisClassEntry();
- /** {@return the constant pool entry describing the name of the superclass, if any} */
+ /**
+ * {@return the constant pool entry describing the name of the superclass, if any}
+ *
+ * @see ClassModel#superclass()
+ */
Optional superclassEntry();
- /** {@return the length of the classfile, in bytes} */
+ /** {@return the length of the {@code class} file, in number of bytes} */
int classfileLength();
// Constant pool
/**
* {@return the constant pool entry whose index is given at the specified
- * offset within the classfile}
+ * offset within the {@code class} file}
*
* @apiNote
* If only a particular type of entry is expected, use {@link #readEntry(
* int, Class) readEntry(int, Class)}.
*
- * @param offset the offset of the index within the classfile
+ * @param offset the offset of the index within the {@code class} file
* @throws ConstantPoolException if the index is out of range of the
* constant pool size, or zero
*/
@@ -86,9 +107,9 @@ public sealed interface ClassReader extends ConstantPool
/**
* {@return the constant pool entry of a given type whose index is given
- * at the specified offset within the classfile}
+ * at the specified offset within the {@code class} file}
* @param the entry type
- * @param offset the offset of the index within the classfile
+ * @param offset the offset of the index within the {@code class} file
* @param cls the entry type
* @throws ConstantPoolException if the index is out of range of the
* constant pool size, or zero, or the entry is not of the given type
@@ -97,14 +118,14 @@ public sealed interface ClassReader extends ConstantPool
/**
* {@return the constant pool entry whose index is given at the specified
- * offset within the classfile, or null if the index at the specified
- * offset is zero}
+ * offset within the {@code class} file, or {@code null} if the index at the
+ * specified offset is zero}
*
* @apiNote
* If only a particular type of entry is expected, use {@link #readEntryOrNull(
* int, Class) readEntryOrNull(int, Class)}.
*
- * @param offset the offset of the index within the classfile
+ * @param offset the offset of the index within the {@code class} file
* @throws ConstantPoolException if the index is out of range of the
* constant pool size
*/
@@ -112,11 +133,11 @@ public sealed interface ClassReader extends ConstantPool
/**
* {@return the constant pool entry of a given type whose index is given
- * at the specified offset within the classfile, or null if the index at
- * the specified offset is zero}
+ * at the specified offset within the {@code class} file, or {@code null} if
+ * the index at the specified offset is zero}
*
* @param the entry type
- * @param offset the offset of the index within the classfile
+ * @param offset the offset of the index within the {@code class} file
* @param cls the entry type
* @throws ConstantPoolException if the index is out of range of the
* constant pool size, or zero, or the entry is not of the given type
@@ -124,65 +145,89 @@ public sealed interface ClassReader extends ConstantPool
T readEntryOrNull(int offset, Class cls);
/**
- * {@return the unsigned byte at the specified offset within the classfile}
- * @param offset the offset within the classfile
+ * {@return the unsigned byte at the specified offset within the {@code
+ * class} file} Reads a byte and zero-extends it to an {@code int}.
+ *
+ * @param offset the offset within the {@code class} file
*/
int readU1(int offset);
/**
- * {@return the unsigned short at the specified offset within the classfile}
- * @param offset the offset within the classfile
+ * {@return the unsigned short at the specified offset within the {@code
+ * class} file} Reads a 2-byte value and zero-extends it to an {@code int}.
+ *
+ * @param offset the offset within the {@code class} file
*/
int readU2(int offset);
/**
- * {@return the signed byte at the specified offset within the classfile}
- * @param offset the offset within the classfile
+ * {@return the signed byte at the specified offset within the {@code class}
+ * file} Reads a byte and sign-extends it to an {@code int}.
+ *
+ * @param offset the offset within the {@code class} file
*/
int readS1(int offset);
/**
- * {@return the signed byte at the specified offset within the classfile}
- * @param offset the offset within the classfile
+ * {@return the signed byte at the specified offset within the {@code class}
+ * file} Reads a 2-byte value and sign-extends it to an {@code int}.
+ *
+ * @param offset the offset within the {@code class} file
*/
int readS2(int offset);
/**
- * {@return the signed int at the specified offset within the classfile}
- * @param offset the offset within the classfile
+ * {@return the signed int at the specified offset within the {@code class}
+ * file} Reads 4 bytes of value.
+ *
+ * @param offset the offset within the {@code class} file
*/
int readInt(int offset);
/**
- * {@return the signed long at the specified offset within the classfile}
- * @param offset the offset within the classfile
+ * {@return the signed long at the specified offset within the {@code class}
+ * file} Reads 8 bytes of value.
+ *
+ * @param offset the offset within the {@code class} file
*/
long readLong(int offset);
/**
- * {@return the float value at the specified offset within the classfile}
- * @param offset the offset within the classfile
+ * {@return the float value at the specified offset within the {@code class}
+ * file} Reads 4 bytes of value.
+ *
+ * In the conversions, all NaN values of the {@code float} may or may not be
+ * collapsed into a single {@linkplain Float#NaN "canonical" NaN value}.
+ *
+ * @param offset the offset within the {@code class} file
*/
float readFloat(int offset);
/**
- * {@return the double value at the specified offset within the classfile}
- * @param offset the offset within the classfile
+ * {@return the double value at the specified offset within the {@code
+ * class} file} Reads 8 bytes of value.
+ *
+ * In the conversions, all NaN values of the {@code double} may or may not
+ * be collapsed into a single {@linkplain Double#NaN "canonical" NaN value}.
+ *
+ * @param offset the offset within the {@code class} file
*/
double readDouble(int offset);
/**
- * {@return a copy of the bytes at the specified range in the classfile}
- * @param offset the offset within the classfile
+ * {@return a copy of the bytes at the specified range in the {@code class}
+ * file}
+ *
+ * @param offset the offset within the {@code class} file
* @param len the length of the range
*/
byte[] readBytes(int offset, int len);
/**
- * Copy a range of bytes from the classfile to a {@link BufWriter}
+ * Copy a range of bytes from the {@code class} file to a {@link BufWriter}.
*
* @param buf the {@linkplain BufWriter}
- * @param offset the offset within the classfile
+ * @param offset the offset within the {@code class} file
* @param len the length of the range
*/
void copyBytesTo(BufWriter buf, int offset, int len);
diff --git a/src/java.base/share/classes/java/lang/classfile/ClassSignature.java b/src/java.base/share/classes/java/lang/classfile/ClassSignature.java
index 0e1329fd167..415332f0059 100644
--- a/src/java.base/share/classes/java/lang/classfile/ClassSignature.java
+++ b/src/java.base/share/classes/java/lang/classfile/ClassSignature.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
@@ -24,6 +24,7 @@
*/
package java.lang.classfile;
+import java.lang.classfile.attribute.SignatureAttribute;
import java.util.List;
import jdk.internal.classfile.impl.SignaturesImpl;
@@ -31,27 +32,53 @@
import static java.util.Objects.requireNonNull;
/**
- * Models the generic signature of a class file, as defined by JVMS {@jvms 4.7.9}.
+ * Models the generic signature of a class or interface, as defined by JVMS
+ * {@jvms 4.7.9.1}.
*
+ * @see Class
+ * @see SignatureAttribute
+ * @jls 8.1 Class Declarations
+ * @jls 9.1 Interface Declarations
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface ClassSignature
permits SignaturesImpl.ClassSignatureImpl {
- /** {@return the type parameters of this class} */
+ /**
+ * {@return the type parameters of this class or interface, may be empty}
+ *
+ * @see Class#getTypeParameters()
+ * @jls 8.1.2 Generic Classes and Type Parameters
+ * @jls 9.1.2 Generic Interfaces and Type Parameters
+ */
List typeParameters();
- /** {@return the instantiation of the superclass in this signature} */
+ /**
+ * {@return the instantiation of the superclass in this signature}
+ * Interfaces return a signature representing the {@link Object} class.
+ *
+ * @see Class#getGenericSuperclass()
+ * @jls 8.1.4 Superclasses and Subclasses
+ */
Signature.ClassTypeSig superclassSignature();
- /** {@return the instantiation of the interfaces in this signature} */
+ /**
+ * {@return the instantiation of the interfaces in this signature, may be
+ * empty}
+ *
+ * @see Class#getGenericInterfaces()
+ * @jls 8.1.5 Superinterfaces
+ * @jls 9.1.3 Superinterfaces and Subinterfaces
+ */
List superinterfaceSignatures();
/** {@return the raw signature string} */
String signatureString();
/**
- * {@return a class signature}
+ * {@return a class signature with no type parameter declaration}
+ *
* @param superclassSignature the superclass
* @param superinterfaceSignatures the interfaces
*/
@@ -62,7 +89,7 @@ public static ClassSignature of(Signature.ClassTypeSig superclassSignature,
/**
* {@return a class signature}
- * @param typeParameters the type parameters
+ * @param typeParameters the type parameters, may be empty
* @param superclassSignature the superclass
* @param superinterfaceSignatures the interfaces
*/
@@ -76,9 +103,11 @@ public static ClassSignature of(List typeParameters,
}
/**
- * Parses a raw class signature string into a {@linkplain Signature}
+ * Parses a raw class signature string into a {@linkplain Signature}.
+ *
* @param classSignature the raw class signature string
* @return class signature
+ * @throws IllegalArgumentException if the string is not a valid class signature string
*/
public static ClassSignature parseFrom(String classSignature) {
return new SignaturesImpl(classSignature).parseClassSignature();
diff --git a/src/java.base/share/classes/java/lang/classfile/CustomAttribute.java b/src/java.base/share/classes/java/lang/classfile/CustomAttribute.java
index f47ce9f055b..9f924588770 100644
--- a/src/java.base/share/classes/java/lang/classfile/CustomAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/CustomAttribute.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
@@ -24,16 +24,28 @@
*/
package java.lang.classfile;
+import java.lang.classfile.constantpool.PoolEntry;
import java.lang.classfile.constantpool.Utf8Entry;
+
import jdk.internal.classfile.impl.TemporaryConstantPool;
/**
- * Models a non-standard attribute of a classfile. Clients should extend
- * this class to provide an implementation class for non-standard attributes,
- * and provide an {@link AttributeMapper} to mediate between the classfile
- * format and the {@linkplain CustomAttribute} representation.
- * @param the custom attribute type
+ * Models a user-defined attribute in a {@code class} file. API models for
+ * user-defined attributes should extend this class. A user-defined attribute
+ * should also have an {@link AttributeMapper} defined, which will be returned
+ * by {@link #attributeMapper}, and registered to the {@link
+ * ClassFile.AttributeMapperOption} so the user-defined attributes can be read.
+ *
+ * User-defined attributes are currently not delivered in the traversal of a
+ * {@link CodeModel}.
+ *
+ * Accessor methods on user-defined attributes read from {@code class} files
+ * may throw {@link IllegalArgumentException} if the attribute model is lazily
+ * evaluated, and the evaluation encounters malformed {@code class} file format
+ * for the attribute.
*
+ * @param the custom attribute type
+ * @see java.lang.classfile.attribute
* @since 24
*/
public abstract non-sealed class CustomAttribute>
@@ -42,7 +54,8 @@ public abstract non-sealed class CustomAttribute>
private final AttributeMapper mapper;
/**
- * Construct a {@linkplain CustomAttribute}.
+ * Constructor for subclasses to call.
+ *
* @param mapper the attribute mapper
*/
protected CustomAttribute(AttributeMapper mapper) {
@@ -54,6 +67,17 @@ public final AttributeMapper attributeMapper() {
return mapper;
}
+ /**
+ * {@inheritDoc}
+ *
+ * @implSpec
+ * The default implementation returns a {@code Utf8Entry} suitable for
+ * writing only, which may be {@linkplain PoolEntry##unbound unbound}.
+ * Subclasses representing attributes read from {@code class} files must
+ * override this method.
+ *
+ * @see AttributeMapper#readAttribute
+ */
@Override
public Utf8Entry attributeName() {
return TemporaryConstantPool.INSTANCE.utf8Entry(mapper.name());
diff --git a/src/java.base/share/classes/java/lang/classfile/MethodSignature.java b/src/java.base/share/classes/java/lang/classfile/MethodSignature.java
index e3889395e32..f81820a7f77 100644
--- a/src/java.base/share/classes/java/lang/classfile/MethodSignature.java
+++ b/src/java.base/share/classes/java/lang/classfile/MethodSignature.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
@@ -24,7 +24,10 @@
*/
package java.lang.classfile;
+import java.lang.classfile.attribute.SignatureAttribute;
import java.lang.constant.MethodTypeDesc;
+import java.lang.reflect.Executable;
+import java.lang.reflect.Method;
import java.util.List;
import jdk.internal.classfile.impl.SignaturesImpl;
@@ -33,34 +36,68 @@
import static java.util.Objects.requireNonNull;
/**
- * Models the generic signature of a method, as defined by JVMS {@jvms 4.7.9}.
+ * Models the generic signature of a method or constructor, as defined by JVMS
+ * {@jvms 4.7.9.1}.
*
+ * @see Executable
+ * @see SignatureAttribute
+ * @jls 8.4 Method Declarations
+ * @jls 8.8 Constructor Declarations
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface MethodSignature
permits SignaturesImpl.MethodSignatureImpl {
- /** {@return the type parameters of this method} */
+ /**
+ * {@return the type parameters of this method or constructor, may be empty}
+ *
+ * @see Executable#getTypeParameters()
+ * @jls 8.4.4 Generic Methods
+ * @jls 8.8.4 Generic Constructors
+ */
List typeParameters();
- /** {@return the signatures of the parameters of this method} */
+ /**
+ * {@return the signatures of the parameters of this method or constructor,
+ * may be empty} The parameters may differ from those in the method
+ * descriptor because some synthetic or implicit parameters are omitted.
+ *
+ * @see Executable#getGenericParameterTypes()
+ * @jls 8.4.1 Formal Parameters
+ * @jls 8.8.1 Formal Parameters
+ */
List arguments();
- /** {@return the signatures of the return value of this method} */
+ /**
+ * {@return the signatures of the return value of this method} For
+ * constructors, this returns a signature representing {@code void}.
+ *
+ * @see Method#getGenericReturnType()
+ * @jls 8.4.5 Method Result
+ */
Signature result();
- /** {@return the signatures of the exceptions thrown by this method} */
+ /**
+ * {@return the signatures of the exceptions thrown by this method or
+ * constructor}
+ *
+ * @see Executable#getGenericExceptionTypes()
+ * @jls 8.4.6 Method Throws
+ * @jls 8.8.5 Constructor Throws
+ */
List throwableSignatures();
/** {@return the raw signature string} */
String signatureString();
/**
- * {@return a method signature for a raw (no generic information) method descriptor}
+ * {@return a method signature for a raw method descriptor} The resulting
+ * signature has no type parameter or exception type declared.
+ *
* @param methodDescriptor the method descriptor
*/
public static MethodSignature of(MethodTypeDesc methodDescriptor) {
-
requireNonNull(methodDescriptor);
return new SignaturesImpl.MethodSignatureImpl(
List.of(),
@@ -70,13 +107,15 @@ public static MethodSignature of(MethodTypeDesc methodDescriptor) {
}
/**
- * {@return a method signature}
+ * {@return a method signature with no type parameter or exception type}
+ * The parameters may differ from those in the method descriptor because
+ * some synthetic or implicit parameters are omitted.
+ *
* @param result signature for the return type
- * @param arguments signatures for the method arguments
+ * @param arguments signatures for the method parameters
*/
public static MethodSignature of(Signature result,
Signature... arguments) {
-
return new SignaturesImpl.MethodSignatureImpl(List.of(),
List.of(),
requireNonNull(result),
@@ -84,17 +123,19 @@ public static MethodSignature of(Signature result,
}
/**
- * {@return a method signature}
+ * {@return a method signature} The parameters may differ from those in
+ * the method descriptor because some synthetic or implicit parameters are
+ * omitted.
+ *
* @param typeParameters signatures for the type parameters
* @param exceptions signatures for the exceptions
* @param result signature for the return type
- * @param arguments signatures for the method arguments
+ * @param arguments signatures for the method parameters
*/
public static MethodSignature of(List typeParameters,
List exceptions,
Signature result,
Signature... arguments) {
-
return new SignaturesImpl.MethodSignatureImpl(
List.copyOf(requireNonNull(typeParameters)),
List.copyOf(requireNonNull(exceptions)),
@@ -103,12 +144,14 @@ public static MethodSignature of(List typeParameters,
}
/**
- * Parses a raw method signature string into a {@linkplain MethodSignature}
+ * Parses a raw method signature string into a {@code MethodSignature}.
+ *
* @param methodSignature the raw method signature string
- * @return method signature
+ * @return the parsed method signature
+ * @throws IllegalArgumentException if the string is not a valid method
+ * signature string
*/
public static MethodSignature parseFrom(String methodSignature) {
-
return new SignaturesImpl(methodSignature).parseMethodSignature();
}
}
diff --git a/src/java.base/share/classes/java/lang/classfile/Signature.java b/src/java.base/share/classes/java/lang/classfile/Signature.java
index ad2dca0ad46..eef86d5a7a1 100644
--- a/src/java.base/share/classes/java/lang/classfile/Signature.java
+++ b/src/java.base/share/classes/java/lang/classfile/Signature.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
@@ -24,7 +24,15 @@
*/
package java.lang.classfile;
+import java.lang.classfile.attribute.SignatureAttribute;
+import java.lang.classfile.constantpool.ClassEntry;
import java.lang.constant.ClassDesc;
+import java.lang.reflect.GenericArrayType;
+import java.lang.reflect.GenericDeclaration;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.lang.reflect.TypeVariable;
+import java.lang.reflect.WildcardType;
import java.util.List;
import java.util.Optional;
@@ -36,6 +44,10 @@
/**
* Models generic Java type signatures, as defined in JVMS {@jvms 4.7.9.1}.
*
+ * @see Type
+ * @see SignatureAttribute
+ * @jls 4.1 The Kinds of Types and Values
+ * @jvms 4.7.9.1 Signatures
* @sealedGraph
* @since 24
*/
@@ -45,16 +57,21 @@ public sealed interface Signature {
String signatureString();
/**
- * Parses generic Java type signature from raw string
+ * Parses a Java type signature from a raw string.
+ *
* @param javaTypeSignature raw Java type signature string
- * @return Java type signature
+ * @return a Java type signature
+ * @throws IllegalArgumentException if the string is not a valid Java type
+ * signature string
*/
public static Signature parseFrom(String javaTypeSignature) {
return new SignaturesImpl(javaTypeSignature).parseSignature();
}
/**
- * {@return a Java type signature}
+ * {@return a Java type signature from a field descriptor} The returned
+ * signature represents a reifiable type (JLS {@jls 4.7}).
+ *
* @param classDesc the symbolic description of the Java type
*/
public static Signature of(ClassDesc classDesc) {
@@ -67,8 +84,10 @@ public static Signature of(ClassDesc classDesc) {
}
/**
- * Models the signature of a primitive type or void
+ * Models the signature of a primitive type (JLS {@jls 4.2}) or void.
*
+ * @jls 4.2 Primitive Types and Values
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface BaseTypeSig extends Signature
@@ -81,6 +100,8 @@ public sealed interface BaseTypeSig extends Signature
* {@return the signature of a primitive type or void}
* @param classDesc a symbolic descriptor for the base type, must correspond
* to a primitive type
+ * @throws IllegalArgumentException if the {@code classDesc} is not
+ * primitive
*/
public static BaseTypeSig of(ClassDesc classDesc) {
requireNonNull(classDesc);
@@ -92,6 +113,8 @@ public static BaseTypeSig of(ClassDesc classDesc) {
/**
* {@return the signature of a primitive type or void}
* @param baseType the single-letter descriptor for the base type
+ * @throws IllegalArgumentException if the {@code baseType} is not a
+ * valid descriptor character for a primitive type or void
*/
public static BaseTypeSig of(char baseType) {
if ("VIJCSBFDZ".indexOf(baseType) < 0)
@@ -104,6 +127,8 @@ public static BaseTypeSig of(char baseType) {
* Models the signature of a reference type, which may be a class, interface,
* type variable, or array type.
*
+ * @jls 4.3 Reference Types and Values
+ * @jvms 4.7.9.1 Signatures
* @sealedGraph
* @since 24
*/
@@ -115,42 +140,68 @@ public sealed interface RefTypeSig
/**
* Models the signature of a possibly-parameterized class or interface type.
*
+ * @see Type
+ * @see ParameterizedType
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface ClassTypeSig
extends RefTypeSig, ThrowableSig
permits SignaturesImpl.ClassTypeSigImpl {
- /** {@return the signature of the outer type, if any} */
+ /**
+ * {@return the signature of the class that this class is a member of,
+ * only if this is a member class} Note that the outer class may be
+ * absent if it is not a parameterized type.
+ *
+ * @jls 4.5 Parameterized Types
+ */
Optional outerType();
- /** {@return the class name} */
+ /**
+ * {@return the class or interface name; includes the {@linkplain
+ * ClassEntry##internalname slash-separated} package name if there is no
+ * outer type}
+ */
String className();
- /** {@return the class name, as a symbolic descriptor} */
+ /**
+ * {@return this class or interface, as a symbolic descriptor}
+ */
default ClassDesc classDesc() {
var outer = outerType();
return outer.isEmpty() ? ClassDesc.ofInternalName(className())
: outer.get().classDesc().nested(className());
}
- /** {@return the type arguments of the class} */
+ /**
+ * {@return the type arguments of this class or interface}
+ * Note that the outer type may have more type arguments.
+ *
+ * @jls 4.5 Parameterized Types
+ */
List typeArgs();
/**
- * {@return a class type signature}
- * @param className the name of the class
- * @param typeArgs signatures of the type arguments
+ * {@return a class or interface signature without an outer type}
+ *
+ * @param className the name of the class or interface
+ * @param typeArgs the type arguments
+ * @throws IllegalArgumentException if {@code className} does not
+ * represent a class or interface
*/
public static ClassTypeSig of(ClassDesc className, TypeArg... typeArgs) {
return of(null, className, typeArgs);
}
/**
- * {@return a class type signature for an inner class}
- * @param outerType signature of the outer type
- * @param className the name of the class
- * @param typeArgs signatures of the type arguments
+ * {@return a class or interface signature}
+ *
+ * @param outerType signature of the outer type, may be {@code null}
+ * @param className the name of this class or interface
+ * @param typeArgs the type arguments
+ * @throws IllegalArgumentException if {@code className} does not
+ * represent a class or interface
*/
public static ClassTypeSig of(ClassTypeSig outerType, ClassDesc className, TypeArg... typeArgs) {
requireNonNull(className);
@@ -158,19 +209,21 @@ public static ClassTypeSig of(ClassTypeSig outerType, ClassDesc className, TypeA
}
/**
- * {@return a class type signature}
- * @param className the name of the class
- * @param typeArgs signatures of the type arguments
+ * {@return a class or interface signature without an outer type}
+ *
+ * @param className the name of the class or interface
+ * @param typeArgs the type arguments
*/
public static ClassTypeSig of(String className, TypeArg... typeArgs) {
return of(null, className, typeArgs);
}
/**
- * {@return a class type signature for an inner class}
- * @param outerType signature of the outer type
- * @param className the name of the class
- * @param typeArgs signatures of the type arguments
+ * {@return a class type signature}
+ *
+ * @param outerType signature of the outer type, may be {@code null}
+ * @param className the name of this class or interface
+ * @param typeArgs the type arguments
*/
public static ClassTypeSig of(ClassTypeSig outerType, String className, TypeArg... typeArgs) {
requireNonNull(className);
@@ -179,15 +232,25 @@ public static ClassTypeSig of(ClassTypeSig outerType, String className, TypeArg.
}
/**
- * Models the type argument.
+ * Models a type argument, an argument to a type parameter.
*
+ * @see Type
+ * @see WildcardType
+ * @jls 4.5.1 Type Arguments of Parameterized Types
+ * @jvms 4.7.9.1 Signatures
* @sealedGraph
* @since 24
*/
public sealed interface TypeArg {
/**
- * Models an unbounded type argument {@code *}.
+ * Models an unbounded wildcard type argument {@code *}, or {@code
+ * ?} in Java programs. This type argument has an implicit upper
+ * bound of {@link Object}.
+ *
+ * @see WildcardType#getUpperBounds()
+ * @jls 4.5.1 Type Arguments of Parameterized Types
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface Unbounded extends TypeArg permits SignaturesImpl.UnboundedTypeArgImpl {
@@ -195,31 +258,46 @@ public sealed interface Unbounded extends TypeArg permits SignaturesImpl.Unbound
/**
* Models a type argument with an explicit bound type.
+ *
+ * @jls 4.5.1 Type Arguments of Parameterized Types
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface Bounded extends TypeArg permits SignaturesImpl.TypeArgImpl {
/**
* Models a type argument's wildcard indicator.
+ *
+ * @jls 4.5.1 Type Arguments of Parameterized Types
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public enum WildcardIndicator {
/**
- * No wildcard (empty), an exact type. Also known as
- * {@index invariant}.
+ * No wildcard (empty), an exact type. Also known as
+ * {@index invariant}. This is the direct use of a
+ * reference type in Java programs.
+ *
+ * @see Type
*/
NONE,
/**
- * Upper-bound indicator {@code +}. Also known as
- * {@index covariant}.
+ * Upper-bound indicator {@code +}. Also known as
+ * {@index covariant}. This is the {@code ? extends}
+ * prefix in Java programs.
+ *
+ * @see WildcardType#getUpperBounds()
*/
EXTENDS,
/**
- * Lower-bound indicator {@code -}. Also known as
- * {@index contravariant}.
+ * Lower-bound indicator {@code -}. Also known as
+ * {@index contravariant}. This is the {@code ? super}
+ * prefix in Java programs.
+ *
+ * @see WildcardType#getLowerBounds()
*/
SUPER;
}
@@ -232,8 +310,10 @@ public enum WildcardIndicator {
}
/**
- * {@return a bounded type arg}
- * @param boundType the bound
+ * {@return a type argument of a reference type}
+ *
+ * @param boundType the reference type
+ * @see Bounded.WildcardIndicator#NONE
*/
public static TypeArg.Bounded of(RefTypeSig boundType) {
requireNonNull(boundType);
@@ -241,15 +321,17 @@ public static TypeArg.Bounded of(RefTypeSig boundType) {
}
/**
- * {@return an unbounded type arg}
+ * {@return an unbounded wildcard type argument {@code *}}
*/
public static TypeArg.Unbounded unbounded() {
return SignaturesImpl.UnboundedTypeArgImpl.INSTANCE;
}
/**
- * {@return an upper-bounded type arg}
+ * {@return an upper-bounded wildcard type argument}
+ *
* @param boundType the upper bound
+ * @see Bounded.WildcardIndicator#EXTENDS
*/
public static TypeArg.Bounded extendsOf(RefTypeSig boundType) {
requireNonNull(boundType);
@@ -257,8 +339,10 @@ public static TypeArg.Bounded extendsOf(RefTypeSig boundType) {
}
/**
- * {@return a lower-bounded type arg}
+ * {@return a lower-bounded wildcard type argument}
+ *
* @param boundType the lower bound
+ * @see Bounded.WildcardIndicator#SUPER
*/
public static TypeArg.Bounded superOf(RefTypeSig boundType) {
requireNonNull(boundType);
@@ -266,9 +350,10 @@ public static TypeArg.Bounded superOf(RefTypeSig boundType) {
}
/**
- * {@return a bounded type arg}
- * @param wildcard the wild card
- * @param boundType optional bound type
+ * {@return a bounded type argument}
+ *
+ * @param wildcard the wildcard indicator
+ * @param boundType the bound type
*/
public static TypeArg.Bounded bounded(Bounded.WildcardIndicator wildcard, RefTypeSig boundType) {
requireNonNull(wildcard);
@@ -278,8 +363,13 @@ public static TypeArg.Bounded bounded(Bounded.WildcardIndicator wildcard, RefTyp
}
/**
- * Models the signature of a type variable.
+ * Models the signature of a type variable. A type variable is introduced
+ * by a {@linkplain TypeParam type parameter} declaration.
*
+ * @see TypeVariable
+ * @see TypeParam
+ * @jls 4.4 Type Variables
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface TypeVarSig
@@ -291,6 +381,7 @@ public sealed interface TypeVarSig
/**
* {@return a signature for a type variable}
+ *
* @param identifier the name of the type variable
*/
public static TypeVarSig of(String identifier) {
@@ -301,6 +392,10 @@ public static TypeVarSig of(String identifier) {
/**
* Models the signature of an array type.
*
+ * @see Type
+ * @see GenericArrayType
+ * @jls 10.1 Array Types
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface ArrayTypeSig
@@ -311,7 +406,7 @@ public sealed interface ArrayTypeSig
Signature componentSignature();
/**
- * {@return a signature for an array type}
+ * {@return an array type with the given component type}
* @param componentSignature the component type
*/
public static ArrayTypeSig of(Signature componentSignature) {
@@ -322,6 +417,8 @@ public static ArrayTypeSig of(Signature componentSignature) {
* {@return a signature for an array type}
* @param dims the dimension of the array
* @param componentSignature the component type
+ * @throws IllegalArgumentException if the resulting array type exceeds
+ * 255 dimensions
*/
public static ArrayTypeSig of(int dims, Signature componentSignature) {
requireNonNull(componentSignature);
@@ -334,8 +431,15 @@ public static ArrayTypeSig of(int dims, Signature componentSignature) {
}
/**
- * Models a signature for a type parameter of a generic class or method.
+ * Models a signature for a type parameter of a generic class, interface,
+ * method, or constructor, which introduces a {@linkplain TypeVarSig type
+ * variable}.
*
+ * @see GenericDeclaration#getTypeParameters()
+ * @see TypeVariable
+ * @see TypeVarSig
+ * @jls 4.4 Type Variables
+ * @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface TypeParam
@@ -344,16 +448,23 @@ public sealed interface TypeParam
/** {@return the name of the type parameter} */
String identifier();
- /** {@return the class bound of the type parameter} */
+ /**
+ * {@return the class bound of the type parameter} This may be empty
+ * if this type parameter only has interface bounds.
+ */
Optional classBound();
- /** {@return the interface bounds of the type parameter} */
+ /**
+ * {@return the interface bounds of the type parameter} This may be
+ * empty.
+ */
List interfaceBounds();
/**
* {@return a signature for a type parameter}
+ *
* @param identifier the name of the type parameter
- * @param classBound the class bound of the type parameter
+ * @param classBound the class bound of the type parameter, may be {@code null}
* @param interfaceBounds the interface bounds of the type parameter
*/
public static TypeParam of(String identifier, RefTypeSig classBound, RefTypeSig... interfaceBounds) {
@@ -365,8 +476,9 @@ public static TypeParam of(String identifier, RefTypeSig classBound, RefTypeSig.
/**
* {@return a signature for a type parameter}
+ *
* @param identifier the name of the type parameter
- * @param classBound the class bound of the type parameter
+ * @param classBound the optional class bound of the type parameter
* @param interfaceBounds the interface bounds of the type parameter
*/
public static TypeParam of(String identifier, Optional classBound, RefTypeSig... interfaceBounds) {
@@ -378,8 +490,10 @@ public static TypeParam of(String identifier, Optional classBound, R
}
/**
- * Models a signature for a throwable type.
+ * Marker interface for a signature for a throwable type.
*
+ * @jls 8.4.6 Method Throws
+ * @jvms 4.7.9.1 Signatures
* @sealedGraph
* @since 24
*/
diff --git a/src/java.base/share/classes/java/lang/classfile/TypeAnnotation.java b/src/java.base/share/classes/java/lang/classfile/TypeAnnotation.java
index 9353b30a643..68514a2436c 100644
--- a/src/java.base/share/classes/java/lang/classfile/TypeAnnotation.java
+++ b/src/java.base/share/classes/java/lang/classfile/TypeAnnotation.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
@@ -59,6 +59,7 @@ public sealed interface TypeAnnotation
/**
* The kind of target on which the annotation appears, as defined in JVMS {@jvms 4.7.20.1}.
*
+ * @see TargetInfo#targetType()
* @since 24
*/
public enum TargetType {
@@ -189,6 +190,7 @@ static TypeAnnotation of(TargetInfo targetInfo, List targetPa
/**
* Specifies which type in a declaration or expression is being annotated.
*
+ * @see #targetInfo()
* @sealedGraph
* @since 24
*/
@@ -440,8 +442,11 @@ static EmptyTarget ofMethodReceiver() {
}
/**
- * {@return a target for annotations on the type in a formal parameter declaration of a method,
- * constructor, or lambda expression}
+ * {@return a target for annotations on the type in a formal parameter
+ * declaration of a method, constructor, or lambda expression} The
+ * index may differ from the index in the method descriptor because some
+ * synthetic or implicit parameters are omitted.
+ *
* @param formalParameterIndex specifies which formal parameter declaration has an annotated type
*/
static FormalParameterTarget ofMethodFormalParameter(int formalParameterIndex) {
@@ -498,7 +503,7 @@ static CatchTarget ofExceptionParameter(int exceptionTableIndex) {
* @param targetType {@link TargetType#INSTANCEOF}, {@link TargetType#NEW},
* {@link TargetType#CONSTRUCTOR_REFERENCE},
* or {@link TargetType#METHOD_REFERENCE}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
*/
static OffsetTarget ofOffset(TargetType targetType, Label target) {
return new TargetInfoImpl.OffsetTargetImpl(targetType, target);
@@ -506,7 +511,7 @@ static OffsetTarget ofOffset(TargetType targetType, Label target) {
/**
* {@return a target for annotations on the type in an instanceof expression}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
*/
static OffsetTarget ofInstanceofExpr(Label target) {
return ofOffset(TargetType.INSTANCEOF, target);
@@ -514,7 +519,7 @@ static OffsetTarget ofInstanceofExpr(Label target) {
/**
* {@return a target for annotations on the type in a new expression}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
*/
static OffsetTarget ofNewExpr(Label target) {
return ofOffset(TargetType.NEW, target);
@@ -522,7 +527,7 @@ static OffsetTarget ofNewExpr(Label target) {
/**
* {@return a target for annotations on the type before the :: in a constructor reference expression}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
*/
static OffsetTarget ofConstructorReference(Label target) {
return ofOffset(TargetType.CONSTRUCTOR_REFERENCE, target);
@@ -530,7 +535,7 @@ static OffsetTarget ofConstructorReference(Label target) {
/**
* {@return a target for annotations on the type before the :: in a method reference expression}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
*/
static OffsetTarget ofMethodReference(Label target) {
return ofOffset(TargetType.METHOD_REFERENCE, target);
@@ -545,7 +550,7 @@ static OffsetTarget ofMethodReference(Label target) {
* {@link TargetType#METHOD_INVOCATION_TYPE_ARGUMENT},
* {@link TargetType#CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT},
* or {@link TargetType#METHOD_REFERENCE_TYPE_ARGUMENT}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
* @param typeArgumentIndex specifies which type in the cast operator or argument is annotated
*/
static TypeArgumentTarget ofTypeArgument(TargetType targetType, Label target, int typeArgumentIndex) {
@@ -554,7 +559,7 @@ static TypeArgumentTarget ofTypeArgument(TargetType targetType, Label target, in
/**
* {@return a target for annotations on the i'th type in a cast expression}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
* @param typeArgumentIndex specifies which type in the cast operator is annotated
*/
static TypeArgumentTarget ofCastExpr(Label target, int typeArgumentIndex) {
@@ -564,7 +569,7 @@ static TypeArgumentTarget ofCastExpr(Label target, int typeArgumentIndex) {
/**
* {@return a target for annotations on the i'th type argument in the explicit type argument list for
* an explicit constructor invocation statement}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
* @param typeArgumentIndex specifies which type in the argument is annotated
*/
static TypeArgumentTarget ofConstructorInvocationTypeArgument(Label target, int typeArgumentIndex) {
@@ -574,7 +579,7 @@ static TypeArgumentTarget ofConstructorInvocationTypeArgument(Label target, int
/**
* {@return a target for annotations on the i'th type argument in the explicit type argument list for
* a method invocation expression}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
* @param typeArgumentIndex specifies which type in the argument is annotated
*/
static TypeArgumentTarget ofMethodInvocationTypeArgument(Label target, int typeArgumentIndex) {
@@ -584,7 +589,7 @@ static TypeArgumentTarget ofMethodInvocationTypeArgument(Label target, int typeA
/**
* {@return a target for annotations on the i'th type argument in the explicit type argument list for
* a new expression}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
* @param typeArgumentIndex specifies which type in the argument is annotated
*/
static TypeArgumentTarget ofConstructorReferenceTypeArgument(Label target, int typeArgumentIndex) {
@@ -594,7 +599,7 @@ static TypeArgumentTarget ofConstructorReferenceTypeArgument(Label target, int t
/**
* {@return a target for annotations on the i'th type argument in the explicit type argument list for
* a method reference expression}
- * @param target the code label corresponding to the instruction
+ * @param target the label right before the instruction
* @param typeArgumentIndex specifies which type in the argument is annotated
*/
static TypeArgumentTarget ofMethodReferenceTypeArgument(Label target, int typeArgumentIndex) {
@@ -607,6 +612,9 @@ static TypeArgumentTarget ofMethodReferenceTypeArgument(Label target, int typeAr
* parameter of a generic class, generic interface, generic method, or
* generic constructor.
*
+ * @see #ofTypeParameter(TargetType, int)
+ * @see #ofClassTypeParameter(int)
+ * @see #ofMethodTypeParameter(int)
* @since 24
*/
sealed interface TypeParameterTarget extends TargetInfo
@@ -625,6 +633,7 @@ sealed interface TypeParameterTarget extends TargetInfo
* Indicates that an annotation appears on a type in the extends or implements
* clause of a class or interface declaration.
*
+ * @see #ofClassExtends(int)
* @since 24
*/
sealed interface SupertypeTarget extends TargetInfo
@@ -648,6 +657,9 @@ sealed interface SupertypeTarget extends TargetInfo
* type parameter declaration of a generic class, interface, method, or
* constructor.
*
+ * @see #ofTypeParameterBound(TargetType, int, int)
+ * @see #ofClassTypeParameterBound(int, int)
+ * @see #ofMethodTypeParameterBound(int, int)
* @since 24
*/
sealed interface TypeParameterBoundTarget extends TargetInfo
@@ -673,6 +685,10 @@ sealed interface TypeParameterBoundTarget extends TargetInfo
* declaration, the return type of a method, the type of a newly constructed
* object, or the receiver type of a method or constructor.
*
+ * @see #of(TargetType)
+ * @see #ofField()
+ * @see #ofMethodReturn()
+ * @see #ofMethodReceiver()
* @since 24
*/
sealed interface EmptyTarget extends TargetInfo
@@ -683,16 +699,17 @@ sealed interface EmptyTarget extends TargetInfo
* Indicates that an annotation appears on the type in a formal parameter
* declaration of a method, constructor, or lambda expression.
*
+ * @see #ofMethodFormalParameter(int)
* @since 24
*/
sealed interface FormalParameterTarget extends TargetInfo
permits TargetInfoImpl.FormalParameterTargetImpl {
/**
- * Which formal parameter declaration has an annotated type.
- *
- * @return the index into the formal parameter declarations, in the order
- * declared in the source code
+ * {@return the index into the formal parameter declarations, in the
+ * order declared in the source code} The index may differ from the
+ * index in the method descriptor because some synthetic or implicit
+ * parameters are omitted.
*/
int formalParameterIndex();
}
@@ -701,6 +718,7 @@ sealed interface FormalParameterTarget extends TargetInfo
* Indicates that an annotation appears on the i'th type in the throws
* clause of a method or constructor declaration.
*
+ * @see #ofThrows(int)
* @since 24
*/
sealed interface ThrowsTarget extends TargetInfo
@@ -720,13 +738,14 @@ sealed interface ThrowsTarget extends TargetInfo
* Indicates that an annotation appears on the type in a local variable declaration,
* including a variable declared as a resource in a try-with-resources statement.
*
+ * @see #ofLocalVariable(List)
* @since 24
*/
sealed interface LocalVarTarget extends TargetInfo
permits TargetInfoImpl.LocalVarTargetImpl {
/**
- * {@return the table of local variable location/indices.}
+ * {@return the table of local variable location/indices}
*/
List table();
}
@@ -736,6 +755,7 @@ sealed interface LocalVarTarget extends TargetInfo
* has a value, and the index into the local variable array of the current
* frame at which that local variable can be found.
*
+ * @see LocalVarTarget
* @since 24
*/
sealed interface LocalVarTargetInfo
@@ -782,6 +802,7 @@ static LocalVarTargetInfo of(Label startLabel, Label endLabel, int index) {
* Indicates that an annotation appears on the i'th type in an exception parameter
* declaration.
*
+ * @see #ofExceptionParameter(int)
* @since 24
*/
sealed interface CatchTarget extends TargetInfo
@@ -800,17 +821,22 @@ sealed interface CatchTarget extends TargetInfo
* Indicates that an annotation appears on either the type in an instanceof expression
* or a new expression, or the type before the :: in a method reference expression.
*
+ * @see #ofOffset(TargetType, Label)
+ * @see #ofNewExpr(Label)
+ * @see #ofInstanceofExpr(Label)
+ * @see #ofConstructorReference(Label)
+ * @see #ofMethodReference(Label)
* @since 24
*/
sealed interface OffsetTarget extends TargetInfo
permits TargetInfoImpl.OffsetTargetImpl {
/**
- * The code array offset of either the bytecode instruction
- * corresponding to the instanceof expression, the new bytecode instruction corresponding to the new
- * expression, or the bytecode instruction corresponding to the method reference expression.
+ * The label right before the {@link Instruction} corresponding to the
+ * instanceof expression, the new expression, or the method reference
+ * expression.
*
- * @return the code label corresponding to the instruction
+ * @return the label right before the instruction
*/
Label target();
}
@@ -821,19 +847,24 @@ sealed interface OffsetTarget extends TargetInfo
* expression, an explicit constructor invocation statement, a method invocation expression, or a method reference
* expression.
*
+ * @see #ofTypeArgument(TargetType, Label, int)
+ * @see #ofCastExpr(Label, int)
+ * @see #ofConstructorInvocationTypeArgument(Label, int)
+ * @see #ofConstructorReferenceTypeArgument(Label, int)
+ * @see #ofMethodInvocationTypeArgument(Label, int)
+ * @see #ofMethodReferenceTypeArgument(Label, int)
* @since 24
*/
sealed interface TypeArgumentTarget extends TargetInfo
permits TargetInfoImpl.TypeArgumentTargetImpl {
/**
- * The code array offset of either the bytecode instruction
- * corresponding to the cast expression, the new bytecode instruction corresponding to the new expression, the
- * bytecode instruction corresponding to the explicit constructor invocation statement, the bytecode
- * instruction corresponding to the method invocation expression, or the bytecode instruction corresponding to
- * the method reference expression.
+ * The label right before the {@link Instruction} corresponding to the
+ * cast expression, the new expression, the explicit constructor
+ * invocation statement, the method invocation expression, or the method
+ * reference expression.
*
- * @return the code label corresponding to the instruction
+ * @return the label right before the instruction
*/
Label target();
@@ -856,6 +887,7 @@ sealed interface TypeArgumentTarget extends TargetInfo
* JVMS: Type_path structure identifies which part of the type is annotated,
* as defined in JVMS {@jvms 4.7.20.2}
*
+ * @see #targetPath()
* @since 24
*/
sealed interface TypePathComponent
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.java
index 206c0a84087..f92f4261324 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.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
@@ -27,24 +27,31 @@
import java.lang.classfile.AnnotationValue;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.MethodElement;
-import java.lang.classfile.MethodModel;
+import java.lang.reflect.Method;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code AnnotationDefault} attribute (JVMS {@jvms 4.7.22}), which can
- * appear on methods of annotation types, and records the default value
- * {@jls 9.6.2} for the element corresponding to this method. Delivered as a
- * {@link MethodElement} when traversing the elements of a {@link MethodModel}.
+ * Models the {@link Attributes#annotationDefault() AnnotationDefault} attribute
+ * (JVMS {@jvms 4.7.22}), which records the default value (JLS {@jls 9.6.2}) for
+ * the annotation interface element defined by this method.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * This attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Attributes#annotationDefault()
+ * @jls 9.6.2 Defaults for Annotation Interface Elements
+ * @jvms 4.7.22 The {@code AnnotationDefault} Attribute
* @since 24
*/
public sealed interface AnnotationDefaultAttribute
@@ -53,14 +60,16 @@ public sealed interface AnnotationDefaultAttribute
UnboundAttribute.UnboundAnnotationDefaultAttribute {
/**
- * {@return the default value of the annotation type element represented by
- * this method}
+ * {@return the default value of the annotation interface element defined by
+ * the enclosing method}
+ *
+ * @see Method#getDefaultValue()
*/
AnnotationValue defaultValue();
/**
* {@return an {@code AnnotationDefault} attribute}
- * @param annotationDefault the default value of the annotation type element
+ * @param annotationDefault the default value of the annotation interface element
*/
static AnnotationDefaultAttribute of(AnnotationValue annotationDefault) {
return new UnboundAttribute.UnboundAnnotationDefaultAttribute(annotationDefault);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.java
index bbea96dc162..0ed08f63512 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.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
@@ -26,24 +26,41 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.BootstrapMethodEntry;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassModel;
import java.lang.classfile.constantpool.ConstantPool;
+import java.lang.classfile.constantpool.ConstantPoolBuilder;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code BootstrapMethods} attribute (JVMS {@jvms 4.7.23}), which serves as
- * an extension to the constant pool of a classfile. Elements of the bootstrap
- * method table are accessed through {@link ConstantPool}.
+ * Models the {@link Attributes#bootstrapMethods() BootstrapMethods} attribute
+ * (JVMS {@jvms 4.7.23}), which stores symbolic information for the execution of
+ * bootstrap methods, used by dynamically-computed call sites and constants.
+ * It is logically a part of the constant pool of a {@code class} file and thus
+ * not delivered in {@link ClassModel} traversal; its elements are accessible
+ * through {@link ConstantPool}.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 7.
+ * This attribute cannot be constructed directly; its entries can be constructed
+ * through {@link ConstantPoolBuilder#bsmEntry}, resulting in at most one
+ * attribute instance in the built {@code class} file.
+ *
+ * The attribute was introduced in the Java SE Platform version 7, major version
+ * {@value ClassFile#JAVA_7_VERSION}.
*
+ * @see Attributes#bootstrapMethods()
+ * @see java.lang.invoke##bsm Execution of bootstrap methods
+ * @jvms 4.7.23 The {@code BootstrapMethods} Attribute
* @since 24
*/
public sealed interface BootstrapMethodsAttribute
@@ -57,8 +74,7 @@ public sealed interface BootstrapMethodsAttribute
List bootstrapMethods();
/**
- * {@return the size of the bootstrap methods table}. Calling this method
- * does not necessarily inflate the entire table.
+ * {@return the size of the bootstrap methods table}
*/
int bootstrapMethodsSize();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeInfo.java
index ab37c372c29..7bb0a0d124d 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeInfo.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
@@ -24,64 +24,77 @@
*/
package java.lang.classfile.attribute;
+import java.lang.classfile.CodeBuilder;
import java.lang.classfile.instruction.CharacterRange;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models a single character range in the {@link CharacterRangeTableAttribute}.
+ * Models a single character range entry in the {@link
+ * CharacterRangeTableAttribute}.
+ *
+ * Each character range entry associates a range of indices in the code array
+ * with a range of character positions in the source file. A character position
+ * in the source file is represented by a line number and a column number, and
+ * its value is encoded as {@code lineNumber << 10 + columnNumber}. Note that
+ * column numbers are not the same as byte indices in a column as multibyte
+ * characters may be present in the source file.
*
+ * Each character range entry includes a
+ * flag which indicates what kind of range is described: statement, assignment,
+ * method call, etc.
+ *
+ * @see CharacterRangeTableAttribute#characterRangeTable()
+ * @see CharacterRange
* @since 24
*/
public sealed interface CharacterRangeInfo
permits UnboundAttribute.UnboundCharacterRangeInfo {
/**
- * {@return the start of the character range region (inclusive)} This is
- * the index into the code array at which the code for this character range
- * begins.
+ * {@return the start of indices in the code array, inclusive}
+ *
+ * @see CharacterRange#startScope()
*/
int startPc();
/**
- * {@return the end of the character range region (exclusive)} This is the
- * index into the code array after which the code for this character range
- * ends.
+ * {@return the end of indices in the code array, exclusive}
+ *
+ * @see CharacterRange#endScope()
*/
int endPc();
/**
- * {@return the encoded start of the character range region (inclusive)}
- * The value is constructed from the line_number/column_number pair as given
- * by {@code line_number << 10 + column_number}, where the source file is
- * viewed as an array of (possibly multi-byte) characters.
+ * {@return the encoded start of character positions in the source file,
+ * inclusive}
*/
int characterRangeStart();
/**
- * {@return the encoded end of the character range region (exclusive)}.
- * The value is constructed from the line_number/column_number pair as given
- * by {@code line_number << 10 + column_number}, where the source file is
- * viewed as an array of (possibly multi-byte) characters.
+ * {@return the encoded end of character positions in the source file,
+ * exclusive}
*/
int characterRangeEnd();
/**
+ * {@return the flags of this character range entry}
+ *
* The value of the flags item describes the kind of range. Multiple flags
* may be set within flags.
*
* - {@link CharacterRange#FLAG_STATEMENT} Range is a Statement
- * (except ExpressionStatement), StatementExpression {@jls 14.8}, as well as each
- * VariableDeclaratorId = VariableInitializer of
- * LocalVariableDeclarationStatement {@jls 14.4} or FieldDeclaration {@jls 8.3} in the
- * grammar.
- *
- {@link CharacterRange#FLAG_BLOCK} Range is a Block in the
- * grammar.
+ * (except ExpressionStatement), StatementExpression (JLS {@jls 14.8}), as
+ * well as each {@code VariableDeclaratorId = VariableInitializer} of
+ * LocalVariableDeclarationStatement (JLS {@jls 14.4}) or FieldDeclaration
+ * (JLS {@jls 8.3}) in the grammar.
+ *
- {@link CharacterRange#FLAG_BLOCK} Range is a Block in the grammar.
*
- {@link CharacterRange#FLAG_ASSIGNMENT} Range is an assignment
- * expression - Expression1 AssignmentOperator Expression1 in the grammar as
- * well as increment and decrement expressions (both prefix and postfix).
+ * expression - {@code Expression1 AssignmentOperator Expression1} in the
+ * grammar as well as increment and decrement expressions (both prefix and
+ * postfix).
*
- {@link CharacterRange#FLAG_FLOW_CONTROLLER} An expression
- * whose value will effect control flow. {@code Flowcon} in the following:
+ * whose value will affect control flow. {@code Flowcon} in the following:
*
* if ( Flowcon ) Statement [else Statement]
* for ( ForInitOpt ; [Flowcon] ; ForUpdateOpt ) Statement
@@ -131,22 +144,28 @@ public sealed interface CharacterRangeInfo
* if<cond>, ifnonull, ifnull or goto.
*
*
- * All bits of the flags item not assigned above are reserved for future use. They should be set to zero in generated class files and should be ignored by Java virtual machine implementations.
+ * All bits of the flags item not assigned above are reserved for future use.
+ * They should be set to zero in generated class files and should be ignored
+ * by Java virtual machine implementations.
*
- * @return the flags
* @see CharacterRange#flags()
*/
int flags();
/**
- * {@return a character range description}
- * @param startPc the start of the bytecode range, inclusive
- * @param endPc the end of the bytecode range, exclusive
- * @param characterRangeStart the start of the character range, inclusive,
- * encoded as {@code line_number << 10 + column_number}
- * @param characterRangeEnd the end of the character range, exclusive,
- * encoded as {@code line_number << 10 + column_number}
- * @param flags the range flags
+ * {@return a character range entry}
+ *
+ * @apiNote
+ * The created entry cannot be written to a {@link CodeBuilder}. Use
+ * {@link CodeBuilder#characterRange CodeBuilder::characterRange} instead.
+ *
+ * @param startPc the start of indices in the code array, inclusive
+ * @param endPc the end of indices in the code array, exclusive
+ * @param characterRangeStart the encoded start of character positions in
+ * the source file, inclusive
+ * @param characterRangeEnd the encoded end of character positions in the
+ * source file, exclusive
+ * @param flags the flags of this entry
*/
static CharacterRangeInfo of(int startPc,
int endPc,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeTableAttribute.java
index 42a8443f2f6..49168ed99f8 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeTableAttribute.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
@@ -26,37 +26,48 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.CodeModel;
+import java.lang.classfile.instruction.CharacterRange;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * The CharacterRangeTable attribute is an optional variable-length attribute in
- * the attributes table of a {@code Code} attribute. It may be used by debuggers
- * to determine which part of the Java virtual machine code array corresponds to
- * a given position in the source file or to determine what section of source
- * code corresponds to a given index into the code array. The
- * CharacterRangeTable attribute consists of an array of character range entries.
- * Each character range entry within the table associates a range of indices in
- * the code array with a range of character indices in the source file. If the
- * source file is viewed as an array of characters, a character index is the
- * corresponding index into this array. Note that character indices are not the
- * same as byte indices as multi-byte characters may be present in the source
- * file. Each character range entry includes a flag which indicates what kind of
- * range is described: statement, assignment, method call, etc. Both code index
- * ranges and character ranges may nest within other ranges, but they may not
- * partially overlap. Thus, a given code index may correspond to several
- * character range entries and in turn several character ranges, but there will
- * be a smallest character range, and for each kind of range in which it is
- * enclosed there will be a smallest character range. Similarly, a given
- * character index may correspond to several character range entries and in turn
- * several code index ranges, but there will be a smallest code index range, and
- * for each kind of range in which it is enclosed there will be a smallest code
- * index range. The character range entries may appear in any order.
+ * Models the {@link Attributes#characterRangeTable() CharacterRangeTable}
+ * attribute, which is a bidirectional mapping from ranges of positions in the
+ * source file to ranges of indices into the {@code code} array. Its entries
+ * are delivered as {@link CharacterRange}s when traversing the elements of a
+ * {@link CodeModel}, toggled by {@link ClassFile.DebugElementsOption}.
*
- * The attribute permits multiple instances in a given location.
+ * The {@code CharacterRangeTable} attribute consists of an array of {@linkplain
+ * CharacterRangeInfo character range entries}. The character range entries
+ * form a forest data structure: any two range entries are either disjoint, or
+ * if they overlap, then one entry must be enclosed within the other, both in
+ * {@code code} array indices and source file character positions. The
+ * character range entries may appear in any order.
+ *
+ * This attribute only appears on {@code Code} attributes, permits multiple
+ * appearances but should only {@linkplain AttributeMapper#allowMultiple()
+ * appear once} in a {@code Code} attribute. It has a data dependency on
+ * {@linkplain AttributeStability#LABELS labels}.
+ *
+ * This attribute cannot be sent to a {@link CodeBuilder}; its entries can be
+ * constructed with {@link CharacterRange}, resulting in at most one
+ * attribute instance in the built {@code Code} attribute.
+ *
+ * This attribute is not predefined in the Java SE Platform. This is a
+ * JDK-specific nonstandard attribute produced by the reference implementation
+ * of the system Java compiler, defined by the {@code jdk.compiler} module.
*
+ * @see Attributes#characterRangeTable()
+ * @see CompilationIDAttribute
+ * @see SourceIDAttribute
* @since 24
*/
public sealed interface CharacterRangeTableAttribute
@@ -71,6 +82,11 @@ public sealed interface CharacterRangeTableAttribute
/**
* {@return a {@code CharacterRangeTable} attribute}
+ *
+ * @apiNote
+ * The created attribute cannot be written to a {@link CodeBuilder}. Use
+ * {@link CodeBuilder#characterRange CodeBuilder::characterRange} instead.
+ *
* @param ranges the descriptions of the character ranges
*/
static CharacterRangeTableAttribute of(List ranges) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.java
index 9bc9e975d12..4a06fe2d610 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.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
@@ -25,22 +25,31 @@
package java.lang.classfile.attribute;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.CodeModel;
-import java.lang.classfile.Label;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
import jdk.internal.classfile.impl.BoundAttribute;
/**
- * Models the {@code Code} attribute (JVMS {@jvms 4.7.3}), appears on non-native,
- * non-abstract methods and contains the bytecode of the method body. Delivered
- * as a {@link java.lang.classfile.MethodElement} when traversing the elements of a
- * {@link java.lang.classfile.MethodModel}.
+ * Models the {@link Attributes#code() Code} attribute (JVMS {@jvms 4.7.3}),
+ * which contains the bytecode of this method.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * This attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * {@code CodeAttribute} models properties of a {@code Code} attribute read
+ * from {@code class} files. General {@code class} file transformation should
+ * process and traverse a {@link CodeModel} in the traversal of a {@link
+ * MethodModel}, to support transformation of {@code Code} attributes currently
+ * being built.
*
+ * @see Attributes#code()
+ * @jvms 4.7.3 The {@code Code} Attribute
* @since 24
*/
public sealed interface CodeAttribute extends Attribute, CodeModel
@@ -68,6 +77,9 @@ public sealed interface CodeAttribute extends Attribute, CodeMode
/**
* {@return the position of the {@code label} in the {@link #codeArray codeArray}}
+ * The label represents a cursor pointing at immediately before the returned
+ * index into the {@code code} array.
+ *
* @param label a marker for a position within this {@code CodeAttribute}
* @throws IllegalArgumentException if the {@code label} is not from this attribute
*/
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/CompilationIDAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/CompilationIDAttribute.java
index 8311a8e045c..f3cbce227c3 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/CompilationIDAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/CompilationIDAttribute.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
@@ -26,6 +26,9 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
import java.lang.classfile.constantpool.Utf8Entry;
@@ -34,15 +37,20 @@
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code CompilationID} attribute (@@@ need reference), which can
- * appear on classes and records the compilation time of the class. Delivered
- * as a {@link java.lang.classfile.ClassElement} when traversing the elements of
- * a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#compilationId() CompilationID} attribute, which
+ * records the compilation time of the {@code class} file.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * This attribute is not predefined in the Java SE Platform. This is a
+ * JDK-specific nonstandard attribute produced by the reference implementation
+ * of the system Java compiler, defined by the {@code jdk.compiler} module.
*
+ * @see Attributes#compilationId()
+ * @see CharacterRangeTableAttribute
+ * @see SourceIDAttribute
* @since 24
*/
public sealed interface CompilationIDAttribute
@@ -51,8 +59,8 @@ public sealed interface CompilationIDAttribute
UnboundAttribute.UnboundCompilationIDAttribute {
/**
- * {@return the compilation ID} The compilation ID is the value of
- * {@link System#currentTimeMillis()} when the classfile is generated.
+ * {@return the compilation ID} The compilation ID is the string value of
+ * {@link System#currentTimeMillis()} when the {@code class} file is generated.
*/
Utf8Entry compilationId();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.java
index 54f4742ab0c..7aa6540aa86 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.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
@@ -25,6 +25,10 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.FieldElement;
import java.lang.classfile.constantpool.ConstantValueEntry;
import java.lang.constant.ConstantDesc;
@@ -34,15 +38,19 @@
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code ConstantValue} attribute (JVMS {@jvms 4.7.2}), which can appear on
- * fields and indicates that the field's value is a constant. Delivered as a
- * {@link java.lang.classfile.FieldElement} when traversing the elements of a
- * {@link java.lang.classfile.FieldModel}.
+ * Models the {@link Attributes#constantValue() ConstantValue} attribute (JVMS
+ * {@jvms 4.7.2}), which indicates this field's value is a constant and that
+ * constant value.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on fields, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a field. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * This attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
*
+ * @see Attributes#constantValue()
+ * @jvms 4.7.2 The {@code ConstantValue} Attribute
* @since 24
*/
public sealed interface ConstantValueAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.java
index 9e470711e1f..89a0394388c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.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
@@ -24,22 +24,34 @@
*/
package java.lang.classfile.attribute;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code Deprecated} attribute (JVMS {@jvms 4.7.15}), which can appear on
- * classes, methods, and fields. Delivered as a {@link ClassElement},
- * {@link MethodElement}, or {@link FieldElement} when traversing the elements
- * of a corresponding model.
+ * Models the {@link Attributes#deprecated() Deprecated} attribute (JVMS {@jvms
+ * 4.7.15}), which indicates this structure has been superseded.
*
- * The attribute permits multiple instances in a given location.
+ * This attribute can appear on classes, methods, and fields, and permits
+ * {@linkplain AttributeMapper#allowMultiple multiple instances} in a structure.
+ * It has {@linkplain AttributeStability#STATELESS no data dependency}.
+ *
+ * This attribute was introduced in the Java SE Platform version 1.1, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * When this attribute is present, the {@link Deprecated} annotation should
+ * also be present in the {@link RuntimeVisibleAnnotationsAttribute
+ * RuntimeVisibleAnnotations} attribute to provide more obvious alerts.
+ * The reference implementation of the system Java compiler emits this attribute
+ * without the annotation when a {@code @deprecated} tag is present in the
+ * documentation comments without the annotation.
*
+ * @see Attributes#deprecated()
+ * @see Deprecated
+ * @jvms 4.7.15 The {@code Deprecated} Attribute
* @since 24
*/
public sealed interface DeprecatedAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.java
index 06ded8c82a5..c89bed9fde9 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.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
@@ -25,11 +25,16 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.constantpool.ClassEntry;
import java.lang.classfile.constantpool.NameAndTypeEntry;
import java.lang.classfile.constantpool.Utf8Entry;
import java.lang.constant.ClassDesc;
+import java.lang.constant.ConstantDescs;
import java.lang.constant.MethodTypeDesc;
import java.util.Optional;
@@ -39,17 +44,20 @@
import jdk.internal.classfile.impl.Util;
/**
- * Models the {@code EnclosingMethod} attribute (JVMS {@jvms 4.7.7}), which can appear
- * on classes, and indicates that the class is a local or anonymous class.
- * Delivered as a {@link ClassElement} when traversing the elements of a {@link
- * java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#enclosingMethod() EnclosingMethod} attribute
+ * (JVMS {@jvms 4.7.7}), which indicates that this class is a local or
+ * anonymous class, and indicates the enclosing method or constructor of this
+ * class if this class is enclosed in exactly one method or constructor.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Attributes#enclosingMethod()
+ * @jvms 4.7.7 The {@code EnclosingMethod} Attribute
* @since 24
*/
public sealed interface EnclosingMethodAttribute
@@ -58,36 +66,52 @@ public sealed interface EnclosingMethodAttribute
UnboundAttribute.UnboundEnclosingMethodAttribute {
/**
- * {@return the innermost class that encloses the declaration of the current
- * class}
+ * {@return the class that encloses the declaration of the current
+ * class} If the {@link #enclosingMethod()} is present, this is the
+ * declaring class of that enclosing method or constructor.
+ *
+ * @see Class#getEnclosingClass()
*/
ClassEntry enclosingClass();
/**
* {@return the name and type of the enclosing method, if the class is
- * immediately enclosed by a method or constructor}
+ * immediately enclosed by exactly one method or constructor} This may
+ * be empty if the anonymous or local class appears in a field initializer
+ * (JLS {@jls 8.3.2}), an instance initializer (JLS {@jls 8.6}), or a static
+ * initializer (JLS {@jls 8.7}). As a result, this never describes a class
+ * initialization method {@value ConstantDescs#CLASS_INIT_NAME}.
+ *
+ * @see Class#getEnclosingMethod()
+ * @see Class#getEnclosingConstructor()
*/
Optional enclosingMethod();
/**
- * {@return the name of the enclosing method, if the class is
- * immediately enclosed by a method or constructor}
+ * {@return the name of the enclosing method, if the class is immediately
+ * enclosed by exactly one method or constructor}
+ *
+ * @see #enclosingMethod()
*/
default Optional enclosingMethodName() {
return enclosingMethod().map(NameAndTypeEntry::name);
}
/**
- * {@return the type of the enclosing method, if the class is
- * immediately enclosed by a method or constructor}
+ * {@return the name of the enclosing method, if the class is immediately
+ * enclosed by exactly one method or constructor}
+ *
+ * @see #enclosingMethod()
*/
default Optional enclosingMethodType() {
return enclosingMethod().map(NameAndTypeEntry::type);
}
/**
- * {@return the type of the enclosing method, if the class is
- * immediately enclosed by a method or constructor}
+ * {@return the name of the enclosing method, if the class is immediately
+ * enclosed by exactly one method or constructor}
+ *
+ * @see #enclosingMethod()
*/
default Optional enclosingMethodTypeSymbol() {
return enclosingMethodType().map(Util::methodTypeSymbol);
@@ -96,8 +120,8 @@ default Optional enclosingMethodTypeSymbol() {
/**
* {@return an {@code EnclosingMethod} attribute}
* @param className the class name
- * @param method the name and type of the enclosing method or {@code empty} if
- * the class is not immediately enclosed by a method or constructor
+ * @param method the name and type of the enclosing method or {@code Optional.empty()} if
+ * the class is not immediately enclosed by exactly one method or constructor
*/
static EnclosingMethodAttribute of(ClassEntry className,
Optional method) {
@@ -107,10 +131,10 @@ static EnclosingMethodAttribute of(ClassEntry className,
/**
* {@return an {@code EnclosingMethod} attribute}
* @param className the class name
- * @param methodName the name of the enclosing method or {@code empty} if
- * the class is not immediately enclosed by a method or constructor
- * @param methodType the type of the enclosing method or {@code empty} if
- * the class is not immediately enclosed by a method or constructor
+ * @param methodName the name of the enclosing method or {@code Optional.empty()} if
+ * the class is not immediately enclosed by exactly one method or constructor
+ * @param methodType the type of the enclosing method or {@code Optional.empty()} if
+ * the class is not immediately enclosed by exactly one method or constructor
* @throws IllegalArgumentException if {@code className} represents a primitive type
*/
static EnclosingMethodAttribute of(ClassDesc className,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.java
index 67732e10e81..acfd8bcca94 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.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
@@ -25,9 +25,14 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.MethodElement;
import java.lang.classfile.constantpool.ClassEntry;
import java.lang.constant.ClassDesc;
+import java.lang.reflect.Executable;
import java.util.Arrays;
import java.util.List;
@@ -36,15 +41,25 @@
import jdk.internal.classfile.impl.Util;
/**
- * Models the {@code Exceptions} attribute (JVMS {@jvms 4.7.5}), which can appear on
- * methods, and records the exceptions declared to be thrown by this method.
- * Delivered as a {@link MethodElement} when traversing the elements of a
- * {@link java.lang.classfile.MethodModel}.
+ * Models the {@link Attributes#exceptions() Exceptions} attribute (JVMS {@jvms
+ * 4.7.5}), which records the exceptions declared to be thrown by this
+ * method.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * The attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * Generic exceptions types thrown by a method and potentially annotated use of
+ * those types are defined by {@link SignatureAttribute} and {@link
+ * RuntimeVisibleTypeAnnotationsAttribute} respectively, which requires this
+ * attribute to be present.
*
+ * @see Attributes#exceptions()
+ * @jvms 4.7.5 The {@code Exceptions} Attribute
* @since 24
*/
public sealed interface ExceptionsAttribute
@@ -54,12 +69,14 @@ public sealed interface ExceptionsAttribute
/**
* {@return the exceptions declared to be thrown by this method}
+ *
+ * @see Executable#getExceptionTypes()
*/
List exceptions();
/**
* {@return an {@code Exceptions} attribute}
- * @param exceptions the checked exceptions that may be thrown from this method
+ * @param exceptions the exceptions that may be thrown from this method
*/
static ExceptionsAttribute of(List exceptions) {
return new UnboundAttribute.UnboundExceptionsAttribute(exceptions);
@@ -67,7 +84,7 @@ static ExceptionsAttribute of(List exceptions) {
/**
* {@return an {@code Exceptions} attribute}
- * @param exceptions the checked exceptions that may be thrown from this method
+ * @param exceptions the exceptions that may be thrown from this method
*/
static ExceptionsAttribute of(ClassEntry... exceptions) {
return of(List.of(exceptions));
@@ -75,7 +92,7 @@ static ExceptionsAttribute of(ClassEntry... exceptions) {
/**
* {@return an {@code Exceptions} attribute}
- * @param exceptions the checked exceptions that may be thrown from this method
+ * @param exceptions the exceptions that may be thrown from this method
*/
static ExceptionsAttribute ofSymbols(List exceptions) {
return of(Util.entryList(exceptions));
@@ -83,7 +100,7 @@ static ExceptionsAttribute ofSymbols(List exceptions) {
/**
* {@return an {@code Exceptions} attribute}
- * @param exceptions the checked exceptions that may be thrown from this method
+ * @param exceptions the exceptions that may be thrown from this method
*/
static ExceptionsAttribute ofSymbols(ClassDesc... exceptions) {
return ofSymbols(Arrays.asList(exceptions));
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassInfo.java
index 6965d5fdfd2..1394ee592ed 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassInfo.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
@@ -36,38 +36,52 @@
import jdk.internal.classfile.impl.Util;
/**
- * Models a single inner class in the {@link InnerClassesAttribute}.
+ * Models a single entry in the {@link InnerClassesAttribute}.
*
+ * @see InnerClassesAttribute#classes()
+ * @jvms 4.7.6 The {@code InnerClasses} Attribute
* @since 24
*/
public sealed interface InnerClassInfo
permits UnboundAttribute.UnboundInnerClassInfo {
/**
- * {@return the class described by this inner class description}
+ * {@return the nested class described by this entry}
*/
ClassEntry innerClass();
/**
- * {@return the class or interface of which this class is a member, if it is a
- * member of a class or interface}
+ * {@return the class or interface of which this class is a member, if it is
+ * a member of a class or interface} This may be empty if this class is
+ * local or anonymous.
+ *
+ * @see Class#getDeclaringClass()
*/
Optional outerClass();
/**
* {@return the simple name of this class, or empty if this class is anonymous}
+ *
+ * @see Class#getSimpleName()
*/
Optional innerName();
/**
* {@return a bit mask of flags denoting access permissions and properties
* of the inner class}
+ *
+ * @see Class#getModifiers()
+ * @see AccessFlag.Location#INNER_CLASS
*/
int flagsMask();
/**
* {@return a set of flag enums denoting access permissions and properties
- * of the inner class}
+ * of the nested class}
+ *
+ * @throws IllegalArgumentException if the flags mask has any undefined bit set
+ * @see Class#accessFlags()
+ * @see AccessFlag.Location#INNER_CLASS
*/
default Set flags() {
return AccessFlag.maskToAccessFlags(flagsMask(), AccessFlag.Location.INNER_CLASS);
@@ -75,17 +89,19 @@ default Set flags() {
/**
* {@return whether a specific access flag is set}
+ *
* @param flag the access flag
+ * @see AccessFlag.Location#INNER_CLASS
*/
default boolean has(AccessFlag flag) {
return Util.has(AccessFlag.Location.INNER_CLASS, flagsMask(), flag);
}
/**
- * {@return an inner class description}
- * @param innerClass the inner class being described
- * @param outerClass the class containing the inner class, if any
- * @param innerName the name of the inner class, if it is not anonymous
+ * {@return a nested class description}
+ * @param innerClass the nested class being described
+ * @param outerClass the class that has the nested class as a member, if it exists
+ * @param innerName the simple name of the nested class, if it is not anonymous
* @param flags the inner class access flags
*/
static InnerClassInfo of(ClassEntry innerClass, Optional outerClass,
@@ -94,10 +110,10 @@ static InnerClassInfo of(ClassEntry innerClass, Optional outerClass,
}
/**
- * {@return an inner class description}
- * @param innerClass the inner class being described
- * @param outerClass the class containing the inner class, if any
- * @param innerName the name of the inner class, if it is not anonymous
+ * {@return a nested class description}
+ * @param innerClass the nested class being described
+ * @param outerClass the class that has the nested class as a member, if it exists
+ * @param innerName the simple name of the nested class, if it is not anonymous
* @param flags the inner class access flags
* @throws IllegalArgumentException if {@code innerClass} or {@code outerClass} represents a primitive type
*/
@@ -109,12 +125,14 @@ static InnerClassInfo of(ClassDesc innerClass, Optional outerClass, O
}
/**
- * {@return an inner class description}
- * @param innerClass the inner class being described
- * @param outerClass the class containing the inner class, if any
- * @param innerName the name of the inner class, if it is not anonymous
+ * {@return a nested class description}
+ * @param innerClass the nested class being described
+ * @param outerClass the class that has the nested class as a member, if it exists
+ * @param innerName the name of the nested class, if it is not anonymous
* @param flags the inner class access flags
- * @throws IllegalArgumentException if {@code innerClass} or {@code outerClass} represents a primitive type
+ * @throws IllegalArgumentException if {@code innerClass} or {@code outerClass}
+ * represents a primitive type, or if any flag cannot be applied to
+ * the {@link AccessFlag.Location#INNER_CLASS} location
*/
static InnerClassInfo of(ClassDesc innerClass, Optional outerClass, Optional innerName, AccessFlag... flags) {
return of(innerClass, outerClass, innerName, Util.flagsToBits(AccessFlag.Location.INNER_CLASS, flags));
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.java
index 463a29f9398..b50b38d0a00 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.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
@@ -26,22 +26,30 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code InnerClasses} attribute (JVMS {@jvms 4.7.6}), which can
- * appear on classes, and records which classes referenced by this classfile
- * are inner classes. Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#innerClasses() InnerClasses} attribute (JVMS
+ * {@jvms 4.7.6}), which records which classes referenced by this {@code class}
+ * file are nested classes.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * The attribute was introduced in the Java SE Platform version 1.1, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
*
+ * @see Attributes#innerClasses()
+ * @jvms 4.7.6 The {@code InnerClasses} Attribute
* @since 24
*/
public sealed interface InnerClassesAttribute
@@ -50,13 +58,13 @@ public sealed interface InnerClassesAttribute
UnboundAttribute.UnboundInnerClassesAttribute {
/**
- * {@return the inner classes used by this class}
+ * {@return the nested classes used by this {@code class} file}
*/
List classes();
/**
* {@return an {@code InnerClasses} attribute}
- * @param innerClasses descriptions of the inner classes
+ * @param innerClasses descriptions of the nested classes
*/
static InnerClassesAttribute of(List innerClasses) {
return new UnboundAttribute.UnboundInnerClassesAttribute(innerClasses);
@@ -64,7 +72,7 @@ static InnerClassesAttribute of(List innerClasses) {
/**
* {@return an {@code InnerClasses} attribute}
- * @param innerClasses descriptions of the inner classes
+ * @param innerClasses descriptions of the nested classes
*/
static InnerClassesAttribute of(InnerClassInfo... innerClasses) {
return new UnboundAttribute.UnboundInnerClassesAttribute(List.of(innerClasses));
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberInfo.java
index 7e148cec9c1..2f4f6d00deb 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberInfo.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
@@ -24,11 +24,16 @@
*/
package java.lang.classfile.attribute;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.instruction.LineNumber;
+
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models a single line number in the {@link LineNumberTableAttribute}.
+ * Models a single line number entry in the {@link LineNumberTableAttribute}.
*
+ * @see LineNumberTableAttribute#lineNumbers()
+ * @see LineNumber
* @since 24
*/
public sealed interface LineNumberInfo
@@ -47,6 +52,12 @@ public sealed interface LineNumberInfo
/**
* {@return a line number description}
+ *
+ * @apiNote
+ * The created entry cannot be written to a {@link CodeBuilder}. Call
+ * {@link CodeBuilder#lineNumber CodeBuilder::lineNumber} in the correct
+ * order instead.
+ *
* @param startPc the starting index of the code array for this line
* @param lineNumber the line number within the original source file
*/
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.java
index 1c00745218a..bb08beacaa2 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.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
@@ -25,21 +25,39 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.CodeModel;
+import java.lang.classfile.instruction.LineNumber;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code LineNumberTable} attribute (JVMS {@jvms 4.7.12}), which can appear
- * on a {@code Code} attribute, and records the mapping between indexes into
- * the code table and line numbers in the source file.
- * Delivered as a {@link java.lang.classfile.instruction.LineNumber} when traversing the
- * elements of a {@link java.lang.classfile.CodeModel}, according to the setting of the
- * {@link java.lang.classfile.ClassFile.LineNumbersOption} option.
+ * Models the {@link Attributes#lineNumberTable() LineNumberTable} attribute
+ * (JVMS {@jvms 4.7.12}), which records the mapping between indexes into
+ * the {@code code} array and line numbers in the source file. Its entries are
+ * delivered as {@link LineNumber} when traversing the elements of a {@link
+ * CodeModel}, which is toggled by {@link ClassFile.LineNumbersOption}.
*
- * The attribute permits multiple instances in a given location.
+ * This attribute only appears on {@code Code} attributes, and permits {@linkplain
+ * AttributeMapper#allowMultiple() multiple instances} in a {@code Code}
+ * attribute. It has a data dependency on {@linkplain AttributeStability#LABELS
+ * labels}.
+ *
+ * This attribute cannot be sent to a {@link CodeBuilder}; its entries can be
+ * constructed with {@link LineNumber}, resulting in at most one attribute
+ * instance in the built {@code Code} attribute.
+ *
+ * The attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
*
+ * @see Attributes#lineNumberTable()
+ * @jvms 4.7.12 The {@code LineNumberTable} Attribute
* @since 24
*/
public sealed interface LineNumberTableAttribute
@@ -54,6 +72,12 @@ public sealed interface LineNumberTableAttribute
/**
* {@return a {@code LineNumberTable} attribute}
+ *
+ * @apiNote
+ * The created attribute cannot be written to a {@link CodeBuilder}. Call
+ * {@link CodeBuilder#lineNumber CodeBuilder::lineNumber} in the correct
+ * order instead.
+ *
* @param lines the line number descriptions
*/
static LineNumberTableAttribute of(List lines) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableInfo.java
index 2b4030b46a6..b6b1c03f133 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableInfo.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
@@ -25,6 +25,7 @@
package java.lang.classfile.attribute;
import java.lang.classfile.constantpool.Utf8Entry;
+import java.lang.classfile.instruction.LocalVariable;
import java.lang.constant.ClassDesc;
import jdk.internal.classfile.impl.BoundLocalVariable;
@@ -34,20 +35,23 @@
/**
* Models a single local variable in the {@link LocalVariableTableAttribute}.
*
+ * @see LocalVariableTableAttribute#localVariables()
+ * @see LocalVariable
+ * @jvms 4.7.13 The {@code LocalVaribleTable} Attribute
* @since 24
*/
public sealed interface LocalVariableInfo
permits UnboundAttribute.UnboundLocalVariableInfo, BoundLocalVariable {
/**
- * {@return the index into the code array (inclusive) at which the scope of
+ * {@return the index into the code array, inclusive, at which the scope of
* this variable begins}
*/
int startPc();
/**
* {@return the length of the region of the code array in which this
- * variable is in scope.}
+ * variable is in scope}
*/
int length();
@@ -57,7 +61,7 @@ public sealed interface LocalVariableInfo
Utf8Entry name();
/**
- * {@return the field descriptor of the local variable}
+ * {@return the field descriptor string of the local variable}
*/
Utf8Entry type();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.java
index 8f44ab2905f..6c1795e17bf 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.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
@@ -25,21 +25,45 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.CodeModel;
+import java.lang.classfile.instruction.LocalVariable;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code LocalVariableTable} attribute (JVMS {@jvms 4.7.13}), which can appear
- * on a {@code Code} attribute, and records debug information about local
- * variables.
- * Delivered as a {@link java.lang.classfile.instruction.LocalVariable} when traversing the
- * elements of a {@link java.lang.classfile.CodeModel}, according to the setting of the
- * {@link java.lang.classfile.ClassFile.DebugElementsOption} option.
+ * Models the {@link Attributes#localVariableTable() LocalVariableTable}
+ * attribute (JVMS {@jvms 4.7.13}), which records debug information about local
+ * variables. Its entries are delivered as {@link LocalVariable}s when
+ * traversing the elements of a {@link CodeModel}, which is toggled by {@link
+ * ClassFile.DebugElementsOption}.
*
- * The attribute permits multiple instances in a given location.
+ * This attribute only appears on {@code Code} attributes, and permits {@linkplain
+ * AttributeMapper#allowMultiple() multiple instances} in a {@code Code}
+ * attribute. It has a data dependency on {@linkplain AttributeStability#LABELS
+ * labels}.
+ *
+ * This attribute cannot be sent to a {@link CodeBuilder}; its entries can be
+ * constructed with {@link LocalVariable}, resulting in at most one attribute
+ * instance in the built {@code Code} attribute.
+ *
+ * The attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * Generic local variable types and potentially annotated use of those types are
+ * defined by {@link LocalVariableTypeTableAttribute} and {@link
+ * RuntimeVisibleTypeAnnotationsAttribute} respectively, which requires this
+ * attribute to be present.
*
+ * @see Attributes#localVariableTable()
+ * @jvms 4.7.13 The {@code LocalVaribleTable} Attribute
* @since 24
*/
public sealed interface LocalVariableTableAttribute
@@ -53,6 +77,11 @@ public sealed interface LocalVariableTableAttribute
/**
* {@return a {@code LocalVariableTable} attribute}
+ *
+ * @apiNote
+ * The created attribute cannot be written to a {@link CodeBuilder}. Use
+ * {@link CodeBuilder#localVariable CodeBuilder::localVariable} instead.
+ *
* @param locals the local variable descriptions
*/
static LocalVariableTableAttribute of(List locals) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeInfo.java
index e7a137102ae..a45dd76d520 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeInfo.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
@@ -25,6 +25,7 @@
package java.lang.classfile.attribute;
import java.lang.classfile.constantpool.Utf8Entry;
+import java.lang.classfile.instruction.LocalVariableType;
import jdk.internal.classfile.impl.BoundLocalVariableType;
import jdk.internal.classfile.impl.UnboundAttribute;
@@ -32,20 +33,23 @@
/**
* Models a single local variable in the {@link LocalVariableTypeTableAttribute}.
*
+ * @see LocalVariableTypeTableAttribute#localVariableTypes()
+ * @see LocalVariableType
+ * @jvms 4.7.14 The {@code LocalVariableTypeTable} Attribute
* @since 24
*/
public sealed interface LocalVariableTypeInfo
permits UnboundAttribute.UnboundLocalVariableTypeInfo, BoundLocalVariableType {
/**
- * {@return the index into the code array (inclusive) at which the scope of
+ * {@return the index into the code array, inclusive at which the scope of
* this variable begins}
*/
int startPc();
/**
* {@return the length of the region of the code array in which this
- * variable is in scope.}
+ * variable is in scope}
*/
int length();
@@ -56,7 +60,7 @@ public sealed interface LocalVariableTypeInfo
/**
- * {@return the field signature of the local variable}
+ * {@return the field signature string of the local variable}
*/
Utf8Entry signature();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.java
index 2bf7b7a87b3..b4bc80cdca1 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.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
@@ -26,23 +26,45 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.CodeModel;
+import java.lang.classfile.instruction.LocalVariableType;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code LocalVariableTypeTable} attribute (JVMS {@jvms 4.7.14}), which can appear
- * on a {@code Code} attribute, and records debug information about local
- * variables.
- * Delivered as a {@link java.lang.classfile.instruction.LocalVariable} when traversing the
- * elements of a {@link java.lang.classfile.CodeModel}, according to the setting of the
- * {@link java.lang.classfile.ClassFile.LineNumbersOption} option.
+ * Models the {@link Attributes#localVariableTypeTable() LocalVariableTypeTable}
+ * attribute (JVMS {@jvms 4.7.14}), which records debug information about local
+ * variables with generic types. Its entries are delivered as {@link
+ * LocalVariableType}s when traversing the elements of a {@link CodeModel},
+ * which can be toggled by {@link ClassFile.DebugElementsOption}.
*
- * The attribute permits multiple instances in a given location.
+ * This attribute only appears on {@code Code} attributes, and permits {@linkplain
+ * AttributeMapper#allowMultiple() multiple instances} in a {@code Code}
+ * attribute. It has a data dependency on {@linkplain AttributeStability#LABELS
+ * labels}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * This attribute cannot be sent to a {@link CodeBuilder}; its entries can be
+ * constructed with {@link LocalVariableType}, resulting in at most one attribute
+ * instance in the built {@code Code} attribute.
+ *
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
+ *
+ * @apiNote
+ * Only local variables that have generic field types need to be described by
+ * this attribute. If a local variable is described in a {@code
+ * LocalVariableTypeTable} attribute, it must also be described in a {@link
+ * LocalVariableTableAttribute LocalVariableTable} attribute.
*
+ * @see Attributes#localVariableTypeTable()
+ * @jvms 4.7.14 The {@code LocalVariableTypeTable} Attribute
* @since 24
*/
public sealed interface LocalVariableTypeTableAttribute
@@ -50,7 +72,7 @@ public sealed interface LocalVariableTypeTableAttribute
permits BoundAttribute.BoundLocalVariableTypeTableAttribute, UnboundAttribute.UnboundLocalVariableTypeTableAttribute {
/**
- * {@return debug information for the local variables in this method}
+ * {@return debug information for the local variables with generic types in this method}
*/
List localVariableTypes();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/MethodParameterInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/MethodParameterInfo.java
index 35301a30284..0366ec07e25 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/MethodParameterInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/MethodParameterInfo.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
@@ -24,9 +24,9 @@
*/
package java.lang.classfile.attribute;
-import java.lang.classfile.ClassFile;
import java.lang.classfile.constantpool.Utf8Entry;
import java.lang.reflect.AccessFlag;
+import java.lang.reflect.Parameter;
import java.util.Optional;
import java.util.Set;
@@ -37,30 +37,35 @@
/**
* Models a single method parameter in the {@link MethodParametersAttribute}.
*
+ * @see MethodParametersAttribute#parameters()
+ * @see Parameter
+ * @jvms 4.7.24 The {@code MethodParameters} Attribute
* @since 24
*/
public sealed interface MethodParameterInfo
permits UnboundAttribute.UnboundMethodParameterInfo {
/**
- * The name of the method parameter, if there is one.
+ * {@return the parameter name, if it has one}
*
- * @return the parameter name, if it has one
+ * @see Parameter#getName()
+ * @see Parameter#isNamePresent()
*/
Optional name();
/**
- * Parameter access flags for this parameter, as a bit mask. Valid
- * parameter flags include {@link ClassFile#ACC_FINAL},
- * {@link ClassFile#ACC_SYNTHETIC}, and {@link ClassFile#ACC_MANDATED}.
+ * {@return the access flags, as a bit mask}
*
- * @return the access flags, as a bit mask
+ * @see Parameter#getModifiers()
+ * @see AccessFlag.Location#METHOD_PARAMETER
*/
int flagsMask();
/**
- * Parameter access flags for this parameter.
+ * {@return the access flags, as a set of flag enums}
*
- * @return the access flags, as a bit mask
+ * @throws IllegalArgumentException if the flags mask has any undefined bit set
+ * @see Parameter#accessFlags()
+ * @see AccessFlag.Location#METHOD_PARAMETER
*/
default Set flags() {
return AccessFlag.maskToAccessFlags(flagsMask(), AccessFlag.Location.METHOD_PARAMETER);
@@ -69,6 +74,7 @@ default Set flags() {
/**
* {@return whether the method parameter has a specific flag set}
* @param flag the method parameter flag
+ * @see AccessFlag.Location#METHOD_PARAMETER
*/
default boolean has(AccessFlag flag) {
return Util.has(AccessFlag.Location.METHOD_PARAMETER, flagsMask(), flag);
@@ -76,7 +82,7 @@ default boolean has(AccessFlag flag) {
/**
* {@return a method parameter description}
- * @param name the method parameter name
+ * @param name the method parameter name, may be empty
* @param flags the method parameter access flags
*/
static MethodParameterInfo of(Optional name, int flags) {
@@ -85,8 +91,10 @@ static MethodParameterInfo of(Optional name, int flags) {
/**
* {@return a method parameter description}
- * @param name the method parameter name
+ * @param name the method parameter name, may be empty
* @param flags the method parameter access flags
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#METHOD_PARAMETER} location
*/
static MethodParameterInfo of(Optional name, AccessFlag... flags) {
return of(name.map(TemporaryConstantPool.INSTANCE::utf8Entry), Util.flagsToBits(AccessFlag.Location.METHOD_PARAMETER, flags));
@@ -94,7 +102,7 @@ static MethodParameterInfo of(Optional name, AccessFlag... flags) {
/**
* {@return a method parameter description}
- * @param name the method parameter name
+ * @param name the method parameter name, may be empty
* @param flags the method parameter access flags
*/
static MethodParameterInfo ofParameter(Optional name, int flags) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.java
index 3b3bacbbca5..8cf6d7b6319 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.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
@@ -26,24 +26,32 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.MethodElement;
+import java.lang.reflect.Executable;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code MethodParameters} attribute (JVMS {@jvms 4.7.24}), which can
- * appear on methods, and records optional information about the method's
- * parameters. Delivered as a {@link java.lang.classfile.MethodElement} when
- * traversing the elements of a {@link java.lang.classfile.MethodModel}.
+ * Models the {@link Attributes#methodParameters() MethodParameters} attribute
+ * (JVMS {@jvms 4.7.24}), which records reflective information about this
+ * method's parameters such as access modifiers.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method. It has a
+ * data dependency on the {@linkplain AttributeMapper.AttributeStability#CP_REFS
+ * constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 8.
+ * The attribute was introduced in the Java SE Platform version 8, major version
+ * {@value ClassFile#JAVA_8_VERSION}.
*
+ * @see Attributes#methodParameters()
+ * @see Executable#getParameters()
+ * @jvms 4.7.24 The {@code MethodParameters} Attribute
* @since 24
*/
public sealed interface MethodParametersAttribute
@@ -53,7 +61,7 @@ public sealed interface MethodParametersAttribute
/**
* {@return information about the parameters of the method} The i'th entry
- * in the list corresponds to the i'th parameter in the method declaration.
+ * in the list corresponds to the i'th parameter in the method descriptor.
*/
List parameters();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java
index 07e0f2baa12..231796c1b81 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.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
@@ -25,17 +25,24 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassModel;
import java.lang.classfile.constantpool.ClassEntry;
import java.lang.classfile.constantpool.ModuleEntry;
import java.lang.classfile.constantpool.Utf8Entry;
import java.lang.constant.ClassDesc;
import java.lang.constant.ModuleDesc;
import java.lang.constant.PackageDesc;
+import java.lang.invoke.MethodHandles;
+import java.lang.module.ModuleDescriptor;
import java.lang.reflect.AccessFlag;
import java.util.Collection;
import java.util.List;
import java.util.Optional;
+import java.util.ServiceLoader;
import java.util.Set;
import java.util.function.Consumer;
@@ -45,17 +52,21 @@
import jdk.internal.classfile.impl.Util;
/**
- * Models the {@code Module} attribute (JVMS {@jvms 4.7.25}), which can
- * appear on classes that represent module descriptors.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#module() Module} attribute (JVMS {@jvms 4.7.25}),
+ * which always appears on classes that {@linkplain ClassModel#isModuleInfo()
+ * represent} module descriptors.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeMapper.AttributeStability#CP_REFS
+ * constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 9.
+ * The attribute was introduced in the Java SE Platform version 9, major version
+ * {@value ClassFile#JAVA_9_VERSION}.
*
+ * @see Attributes#module()
+ * @see ModuleDescriptor
+ * @jvms 4.7.25 The {@code Module} Attribute
* @since 24
*/
public sealed interface ModuleAttribute
@@ -64,25 +75,36 @@ public sealed interface ModuleAttribute
/**
* {@return the name of the module}
+ *
+ * @see ModuleDescriptor#name()
*/
ModuleEntry moduleName();
/**
- * {@return the the module flags of the module, as a bit mask}
+ * {@return the module flags of the module, as a bit mask}
+ *
+ * @see ModuleDescriptor#modifiers()
+ * @see AccessFlag.Location#MODULE
*/
int moduleFlagsMask();
/**
- * {@return the the module flags of the module, as a set of enum constants}
+ * {@return the module flags of the module, as a set of enum constants}
+ *
+ * @throws IllegalArgumentException if the flags mask has any undefined bit set
+ * @see ModuleDescriptor#accessFlags()
+ * @see AccessFlag.Location#MODULE
*/
default Set moduleFlags() {
return AccessFlag.maskToAccessFlags(moduleFlagsMask(), AccessFlag.Location.MODULE);
}
/**
- * Tests presence of module flag
+ * Tests presence of module flag.
+ *
* @param flag the module flag
* @return true if the flag is set
+ * @see AccessFlag.Location#MODULE
*/
default boolean has(AccessFlag flag) {
return Util.has(AccessFlag.Location.MODULE, moduleFlagsMask(), flag);
@@ -90,32 +112,49 @@ default boolean has(AccessFlag flag) {
/**
* {@return the version of the module, if present}
+ *
+ * @see ModuleDescriptor#version()
*/
Optional moduleVersion();
/**
* {@return the modules required by this module}
+ *
+ * @see ModuleDescriptor#requires()
*/
List requires();
/**
* {@return the packages exported by this module}
+ *
+ * @see ModuleDescriptor#packages()
*/
List exports();
/**
* {@return the packages opened by this module}
+ *
+ * @apiNote
+ * Opening a package to another module allows that other module to gain
+ * the same full privilege access as members in this module. See {@link
+ * MethodHandles#privateLookupIn} for more details.
+ *
+ * @see ModuleDescriptor#opens()
*/
List opens();
/**
* {@return the services used by this module} Services may be discovered via
- * {@link java.util.ServiceLoader}.
+ * {@link ServiceLoader}.
+ *
+ * @see ModuleDescriptor#uses()
*/
List uses();
/**
* {@return the service implementations provided by this module}
+ *
+ * @see ModuleDescriptor#provides()
*/
List provides();
@@ -124,7 +163,7 @@ default boolean has(AccessFlag flag) {
*
* @param moduleName the module name
* @param moduleFlags the module flags
- * @param moduleVersion the module version
+ * @param moduleVersion the module version, may be {@code null}
* @param requires the required packages
* @param exports the exported packages
* @param opens the opened packages
@@ -168,126 +207,165 @@ static ModuleAttribute of(ModuleEntry moduleName,
}
/**
- * A builder for module attributes.
+ * A builder for {@link ModuleAttribute Module} attributes.
*
+ * @see ModuleDescriptor.Builder
+ * @jvms 4.7.25 The {@code Module} Attribute
* @since 24
*/
public sealed interface ModuleAttributeBuilder
permits ModuleAttributeBuilderImpl {
/**
- * Sets the module name
+ * Sets the module name.
+ *
* @param moduleName the module name
* @return this builder
*/
ModuleAttributeBuilder moduleName(ModuleDesc moduleName);
/**
- * Sets the module flags
+ * Sets the module flags.
+ *
* @param flagsMask the module flags
* @return this builder
*/
ModuleAttributeBuilder moduleFlags(int flagsMask);
/**
- * Sets the module flags
+ * Sets the module flags.
+ *
* @param moduleFlags the module flags
* @return this builder
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE} location
*/
default ModuleAttributeBuilder moduleFlags(AccessFlag... moduleFlags) {
return moduleFlags(Util.flagsToBits(AccessFlag.Location.MODULE, moduleFlags));
}
/**
- * Sets the module version
- * @param version the module version
+ * Sets the module version, which may be {@code null}.
+ *
+ * @param version the module version, may be {@code null}
* @return this builder
*/
ModuleAttributeBuilder moduleVersion(String version);
/**
- * Adds module requirement
+ * Adds a module requirement.
+ *
* @param module the required module
* @param requiresFlagsMask the requires flags
- * @param version the required module version
+ * @param version the required module version, may be {@code null}
* @return this builder
*/
ModuleAttributeBuilder requires(ModuleDesc module, int requiresFlagsMask, String version);
/**
- * Adds module requirement
+ * Adds a module requirement.
+ *
* @param module the required module
* @param requiresFlags the requires flags
- * @param version the required module version
+ * @param version the required module version, may be {@code null}
* @return this builder
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_REQUIRES} location
*/
default ModuleAttributeBuilder requires(ModuleDesc module, Collection requiresFlags, String version) {
return requires(module, Util.flagsToBits(AccessFlag.Location.MODULE_REQUIRES, requiresFlags), version);
}
/**
- * Adds module requirement
+ * Adds module requirement.
+ *
* @param requires the module require info
* @return this builder
*/
ModuleAttributeBuilder requires(ModuleRequireInfo requires);
/**
- * Adds exported package
+ * Adds an exported package.
+ *
* @param pkge the exported package
* @param exportsFlagsMask the export flags
- * @param exportsToModules the modules to export to
+ * @param exportsToModules the modules to export to, or empty for an unqualified export
* @return this builder
*/
ModuleAttributeBuilder exports(PackageDesc pkge, int exportsFlagsMask, ModuleDesc... exportsToModules);
/**
- * Adds exported package
+ * Adds an exported package.
+ *
* @param pkge the exported package
* @param exportsFlags the export flags
- * @param exportsToModules the modules to export to
+ * @param exportsToModules the modules to export to, or empty for an unqualified export
* @return this builder
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_EXPORTS} location
*/
default ModuleAttributeBuilder exports(PackageDesc pkge, Collection exportsFlags, ModuleDesc... exportsToModules) {
return exports(pkge, Util.flagsToBits(AccessFlag.Location.MODULE_EXPORTS, exportsFlags), exportsToModules);
}
/**
- * Adds exported package
+ * Adds an exported package.
+ *
* @param exports the module export info
* @return this builder
*/
ModuleAttributeBuilder exports(ModuleExportInfo exports);
/**
- * Opens package
+ * Opens a package.
+ *
+ * @apiNote
+ * Opening a package to another module allows that other module to gain
+ * the same full privilege access as members in this module. See {@link
+ * MethodHandles#privateLookupIn} for more details.
+ *
* @param pkge the opened package
* @param opensFlagsMask the open package flags
- * @param opensToModules the modules to open to
+ * @param opensToModules the modules to open to, or empty for an unqualified open
* @return this builder
*/
ModuleAttributeBuilder opens(PackageDesc pkge, int opensFlagsMask, ModuleDesc... opensToModules);
/**
- * Opens package
+ * Opens a package.
+ *
+ * @apiNote
+ * Opening a package to another module allows that other module to gain
+ * the same full privilege access as members in this module. See {@link
+ * MethodHandles#privateLookupIn} for more details.
+ *
* @param pkge the opened package
* @param opensFlags the open package flags
- * @param opensToModules the modules to open to
+ * @param opensToModules the modules to open to, or empty for an unqualified open
* @return this builder
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_OPENS} location
*/
default ModuleAttributeBuilder opens(PackageDesc pkge, Collection opensFlags, ModuleDesc... opensToModules) {
return opens(pkge, Util.flagsToBits(AccessFlag.Location.MODULE_OPENS, opensFlags), opensToModules);
}
/**
- * Opens package
+ * Opens a package.
+ *
+ * @apiNote
+ * Opening a package to another module allows that other module to gain
+ * the same full privilege access as members in this module. See {@link
+ * MethodHandles#privateLookupIn} for more details.
+ *
* @param opens the module open info
* @return this builder
*/
ModuleAttributeBuilder opens(ModuleOpenInfo opens);
/**
- * Declares use of a service
+ * Declares use of a service.
+ *
* @param service the service class used
* @return this builder
* @throws IllegalArgumentException if {@code service} represents a primitive type
@@ -295,14 +373,16 @@ default ModuleAttributeBuilder opens(PackageDesc pkge, Collection op
ModuleAttributeBuilder uses(ClassDesc service);
/**
- * Declares use of a service
+ * Declares use of a service.
+ *
* @param uses the service class used
* @return this builder
*/
ModuleAttributeBuilder uses(ClassEntry uses);
/**
- * Declares provision of a service
+ * Declares provision of a service.
+ *
* @param service the service class provided
* @param implClasses the implementation classes
* @return this builder
@@ -311,7 +391,8 @@ default ModuleAttributeBuilder opens(PackageDesc pkge, Collection op
ModuleAttributeBuilder provides(ClassDesc service, ClassDesc... implClasses);
/**
- * Declares provision of a service
+ * Declares provision of a service.
+ *
* @param provides the module provides info
* @return this builder
*/
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.java
index 69290c55994..2071561a1e5 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.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
@@ -24,11 +24,11 @@
*/
package java.lang.classfile.attribute;
-import java.lang.classfile.ClassFile;
import java.lang.classfile.constantpool.ModuleEntry;
import java.lang.classfile.constantpool.PackageEntry;
import java.lang.constant.ModuleDesc;
import java.lang.constant.PackageDesc;
+import java.lang.module.ModuleDescriptor;
import java.lang.reflect.AccessFlag;
import java.util.Collection;
import java.util.List;
@@ -41,6 +41,9 @@
/**
* Models a single "exports" declaration in the {@link ModuleAttribute}.
*
+ * @see ModuleAttribute#exports()
+ * @see ModuleDescriptor.Exports
+ * @jvms 4.7.25 The {@code Module} Attribute
* @since 24
*/
public sealed interface ModuleExportInfo
@@ -48,43 +51,57 @@ public sealed interface ModuleExportInfo
/**
* {@return the exported package}
+ *
+ * @see ModuleDescriptor.Exports#source()
*/
PackageEntry exportedPackage();
/**
* {@return the flags associated with this export declaration, as a bit mask}
- * Valid flags include {@link ClassFile#ACC_SYNTHETIC} and
- * {@link ClassFile#ACC_MANDATED}.
+ *
+ * @see ModuleDescriptor.Exports#modifiers()
+ * @see AccessFlag.Location#MODULE_EXPORTS
*/
int exportsFlagsMask();
/**
* {@return the flags associated with this export declaration, as a set of
- * flag values}
+ * flag enums}
+ *
+ * @throws IllegalArgumentException if the flags mask has any undefined bit set
+ * @see ModuleDescriptor.Exports#accessFlags()
+ * @see AccessFlag.Location#MODULE_EXPORTS
*/
default Set exportsFlags() {
return AccessFlag.maskToAccessFlags(exportsFlagsMask(), AccessFlag.Location.MODULE_EXPORTS);
}
/**
- * {@return the list of modules to which this package is exported, if it is a
- * qualified export}
- */
- List exportsTo();
-
- /**
- * {@return whether the module has the specified access flag set}
+ * {@return whether the export declaration has the specified access flag set}
+ *
* @param flag the access flag
+ * @see AccessFlag.Location#MODULE_EXPORTS
*/
default boolean has(AccessFlag flag) {
return Util.has(AccessFlag.Location.MODULE_EXPORTS, exportsFlagsMask(), flag);
}
+ /**
+ * {@return the list of modules to which this package is exported, or empty
+ * if this is an unqualified export}
+ *
+ * @see ModuleDescriptor.Exports#isQualified()
+ * @see ModuleDescriptor.Exports#targets()
+ */
+ List exportsTo();
+
/**
* {@return a module export description}
+ *
* @param exports the exported package
* @param exportFlags the export flags, as a bitmask
- * @param exportsTo the modules to which this package is exported
+ * @param exportsTo the modules to which this package is exported, or empty
+ * if this is an unqualified export
*/
static ModuleExportInfo of(PackageEntry exports, int exportFlags,
List exportsTo) {
@@ -93,9 +110,13 @@ static ModuleExportInfo of(PackageEntry exports, int exportFlags,
/**
* {@return a module export description}
+ *
* @param exports the exported package
* @param exportFlags the export flags
- * @param exportsTo the modules to which this package is exported
+ * @param exportsTo the modules to which this package is exported, or empty
+ * if this is an unqualified export
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_EXPORTS} location
*/
static ModuleExportInfo of(PackageEntry exports, Collection exportFlags,
List exportsTo) {
@@ -104,9 +125,11 @@ static ModuleExportInfo of(PackageEntry exports, Collection exportFl
/**
* {@return a module export description}
+ *
* @param exports the exported package
* @param exportFlags the export flags, as a bitmask
- * @param exportsTo the modules to which this package is exported
+ * @param exportsTo the modules to which this package is exported, or empty
+ * if this is an unqualified export
*/
static ModuleExportInfo of(PackageEntry exports,
int exportFlags,
@@ -116,9 +139,13 @@ static ModuleExportInfo of(PackageEntry exports,
/**
* {@return a module export description}
+ *
* @param exports the exported package
* @param exportFlags the export flags
- * @param exportsTo the modules to which this package is exported
+ * @param exportsTo the modules to which this package is exported, or empty
+ * if this is an unqualified export
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_EXPORTS} location
*/
static ModuleExportInfo of(PackageEntry exports,
Collection exportFlags,
@@ -128,9 +155,11 @@ static ModuleExportInfo of(PackageEntry exports,
/**
* {@return a module export description}
+ *
* @param exports the exported package
* @param exportFlags the export flags, as a bitmask
- * @param exportsTo the modules to which this package is exported
+ * @param exportsTo the modules to which this package is exported, or empty
+ * if this is an unqualified export
*/
static ModuleExportInfo of(PackageDesc exports, int exportFlags,
List exportsTo) {
@@ -141,9 +170,13 @@ static ModuleExportInfo of(PackageDesc exports, int exportFlags,
/**
* {@return a module export description}
+ *
* @param exports the exported package
* @param exportFlags the export flags
- * @param exportsTo the modules to which this package is exported
+ * @param exportsTo the modules to which this package is exported, or empty
+ * if this is an unqualified export
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_EXPORTS} location
*/
static ModuleExportInfo of(PackageDesc exports, Collection exportFlags,
List exportsTo) {
@@ -152,9 +185,11 @@ static ModuleExportInfo of(PackageDesc exports, Collection exportFla
/**
* {@return a module export description}
+ *
* @param exports the exported package
* @param exportFlags the export flags, as a bitmask
- * @param exportsTo the modules to which this package is exported
+ * @param exportsTo the modules to which this package is exported, or empty
+ * if this is an unqualified export
*/
static ModuleExportInfo of(PackageDesc exports,
int exportFlags,
@@ -164,9 +199,13 @@ static ModuleExportInfo of(PackageDesc exports,
/**
* {@return a module export description}
+ *
* @param exports the exported package
* @param exportFlags the export flags
- * @param exportsTo the modules to which this package is exported
+ * @param exportsTo the modules to which this package is exported, or empty
+ * if this is an unqualified export
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_EXPORTS} location
*/
static ModuleExportInfo of(PackageDesc exports,
Collection exportFlags,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashInfo.java
index 07616757daa..e89a941296c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashInfo.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
@@ -33,6 +33,7 @@
/**
* Models hash information for a single module in the {@link ModuleHashesAttribute}.
*
+ * @see ModuleHashesAttribute#hashes()
* @since 24
*/
public sealed interface ModuleHashInfo
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashesAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashesAttribute.java
index 918d18bda1e..11c016aa9e1 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashesAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashesAttribute.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
@@ -26,7 +26,11 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassModel;
import java.lang.classfile.constantpool.Utf8Entry;
import java.util.List;
@@ -35,13 +39,11 @@
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code ModuleHashes} attribute, which can
- * appear on classes that represent module descriptors. This is a JDK-specific
- * attribute, which captures the hashes of a set of co-delivered modules.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
- *
- * The specification of the {@code ModuleHashes} attribute is:
+ * Models the {@link Attributes#moduleHashes() ModuleHashes} attribute, which
+ * appears on classes that {@linkplain ClassModel#isModuleInfo() represent}
+ * module descriptors to capture the hashes of a set of co-delivered modules.
+ *
+ * The specification of the {@code ModuleHashes} attribute is:
*
{@code
*
* ModuleHashes_attribute {
@@ -63,10 +65,17 @@
* }
* }
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * This attribute is not predefined in the Java SE Platform. This is a
+ * JDK-specific nonstandard attribute produced by the {@code jdk.jlink} module,
+ * which defines the {@code jlink} and {@code jmod} tools.
*
+ * @see Attributes#moduleHashes()
+ * @see ModuleResolutionAttribute
+ * @see ModuleTargetAttribute
* @since 24
*/
public sealed interface ModuleHashesAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.java
index 7f06eb0f95b..cc88da465fe 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.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
@@ -26,26 +26,36 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassModel;
import java.lang.classfile.constantpool.ClassEntry;
import java.lang.constant.ClassDesc;
+import java.lang.module.ModuleDescriptor;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.TemporaryConstantPool;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code ModuleMainClass} attribute (JVMS {@jvms 4.7.27}), which can
- * appear on classes that represent module descriptors.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#moduleMainClass() ModuleMainClass} attribute
+ * (JVMS {@jvms 4.7.27}), which appears on classes that {@linkplain
+ * ClassModel#isModuleInfo() represent} module descriptors to indicate the main
+ * class of the module.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 9.
+ * The attribute was introduced in the Java SE Platform version 9, major version
+ * {@value ClassFile#JAVA_9_VERSION}.
*
+ * @see Attributes#moduleMainClass()
+ * @see ModuleDescriptor#mainClass()
+ * @jvms 4.7.27 The {@code ModuleMainClass} Attribute
* @since 24
*/
public sealed interface ModuleMainClassAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.java
index a16c9973627..16c0cf8a057 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.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
@@ -28,6 +28,8 @@
import java.lang.classfile.constantpool.PackageEntry;
import java.lang.constant.ModuleDesc;
import java.lang.constant.PackageDesc;
+import java.lang.invoke.MethodHandles;
+import java.lang.module.ModuleDescriptor;
import java.lang.reflect.AccessFlag;
import java.util.Collection;
import java.util.List;
@@ -40,6 +42,14 @@
/**
* Models a single "opens" declaration in the {@link ModuleAttribute}.
*
+ * @apiNote
+ * Opening a package to another module allows that other module to gain
+ * the same full privilege access as members in this module. See {@link
+ * MethodHandles#privateLookupIn} for more details.
+ *
+ * @see ModuleAttribute#exports()
+ * @see ModuleDescriptor.Opens
+ * @jvms 4.7.25 The {@code Module} Attribute
* @since 24
*/
public sealed interface ModuleOpenInfo
@@ -47,44 +57,57 @@ public sealed interface ModuleOpenInfo
/**
* {@return the package being opened}
+ *
+ * @see ModuleDescriptor.Opens#source()
*/
PackageEntry openedPackage();
/**
* {@return the flags associated with this open declaration, as a bit mask}
- * Valid flags include {@link java.lang.classfile.ClassFile#ACC_SYNTHETIC} and
- * {@link java.lang.classfile.ClassFile#ACC_MANDATED}
+ *
+ * @see ModuleDescriptor.Opens#modifiers()
+ * @see AccessFlag.Location#MODULE_OPENS
*/
int opensFlagsMask();
/**
- * {@return the access flags}
+ * {@return the flags associated with this open declaration, as a set of
+ * flag enums}
+ *
+ * @throws IllegalArgumentException if the flags mask has any undefined bit set
+ * @see ModuleDescriptor.Opens#accessFlags()
+ * @see AccessFlag.Location#MODULE_OPENS
*/
default Set opensFlags() {
return AccessFlag.maskToAccessFlags(opensFlagsMask(), AccessFlag.Location.MODULE_OPENS);
}
/**
- * {@return whether the specified access flag is set}
+ * {@return whether the open declaration has the specified access flag set}
+ *
* @param flag the access flag
+ * @see AccessFlag.Location#MODULE_OPENS
*/
default boolean has(AccessFlag flag) {
return Util.has(AccessFlag.Location.MODULE_OPENS, opensFlagsMask(), flag);
}
/**
- * The list of modules to which this package is opened, if it is a
- * qualified open.
+ * {@return the modules to which this package is opened, or empty if this
+ * is an unqualified open}
*
- * @return the modules to which this package is opened
+ * @see ModuleDescriptor.Opens#isQualified()
+ * @see ModuleDescriptor.Opens#targets()
*/
List opensTo();
/**
* {@return a module open description}
+ *
* @param opens the package to open
* @param opensFlags the open flags
- * @param opensTo the packages to which this package is opened, if it is a qualified open
+ * @param opensTo the modules to which this package is opened, or empty if
+ * this is an unqualified open
*/
static ModuleOpenInfo of(PackageEntry opens, int opensFlags,
List opensTo) {
@@ -93,9 +116,13 @@ static ModuleOpenInfo of(PackageEntry opens, int opensFlags,
/**
* {@return a module open description}
+ *
* @param opens the package to open
* @param opensFlags the open flags
- * @param opensTo the packages to which this package is opened, if it is a qualified open
+ * @param opensTo the modules to which this package is opened, or empty if
+ * this is an unqualified open
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_OPENS} location
*/
static ModuleOpenInfo of(PackageEntry opens, Collection opensFlags,
List opensTo) {
@@ -104,9 +131,11 @@ static ModuleOpenInfo of(PackageEntry opens, Collection opensFlags,
/**
* {@return a module open description}
+ *
* @param opens the package to open
* @param opensFlags the open flags
- * @param opensTo the packages to which this package is opened, if it is a qualified open
+ * @param opensTo the modules to which this package is opened, or empty if
+ * this is an unqualified open
*/
static ModuleOpenInfo of(PackageEntry opens,
int opensFlags,
@@ -116,9 +145,13 @@ static ModuleOpenInfo of(PackageEntry opens,
/**
* {@return a module open description}
+ *
* @param opens the package to open
* @param opensFlags the open flags
- * @param opensTo the packages to which this package is opened, if it is a qualified open
+ * @param opensTo the modules to which this package is opened, or empty if
+ * this is an unqualified open
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_OPENS} location
*/
static ModuleOpenInfo of(PackageEntry opens,
Collection opensFlags,
@@ -130,7 +163,8 @@ static ModuleOpenInfo of(PackageEntry opens,
* {@return a module open description}
* @param opens the package to open
* @param opensFlags the open flags
- * @param opensTo the packages to which this package is opened, if it is a qualified open
+ * @param opensTo the modules to which this package is opened, if it is a
+ * qualified open, or empty
*/
static ModuleOpenInfo of(PackageDesc opens, int opensFlags,
List opensTo) {
@@ -143,7 +177,10 @@ static ModuleOpenInfo of(PackageDesc opens, int opensFlags,
* {@return a module open description}
* @param opens the package to open
* @param opensFlags the open flags
- * @param opensTo the packages to which this package is opened, if it is a qualified open
+ * @param opensTo the modules to which this package is opened, if it is a
+ * qualified open, or empty
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_OPENS} location
*/
static ModuleOpenInfo of(PackageDesc opens, Collection opensFlags,
List opensTo) {
@@ -154,7 +191,8 @@ static ModuleOpenInfo of(PackageDesc opens, Collection opensFlags,
* {@return a module open description}
* @param opens the package to open
* @param opensFlags the open flags
- * @param opensTo the packages to which this package is opened, if it is a qualified open
+ * @param opensTo the packages to which this package is opened, or empty if
+ * this is an unqualified open
*/
static ModuleOpenInfo of(PackageDesc opens,
int opensFlags,
@@ -166,7 +204,10 @@ static ModuleOpenInfo of(PackageDesc opens,
* {@return a module open description}
* @param opens the package to open
* @param opensFlags the open flags
- * @param opensTo the packages to which this package is opened, if it is a qualified open
+ * @param opensTo the packages to which this package is opened, or empty if
+ * this is an unqualified open
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_OPENS} location
*/
static ModuleOpenInfo of(PackageDesc opens,
Collection opensFlags,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.java
index ec0a65742b4..24a9218c9fd 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.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
@@ -25,9 +25,15 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassModel;
import java.lang.classfile.constantpool.PackageEntry;
import java.lang.constant.PackageDesc;
+import java.lang.module.ModuleDescriptor;
import java.util.Arrays;
import java.util.List;
@@ -36,17 +42,21 @@
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code ModulePackages} attribute (JVMS {@jvms 4.7.26}), which can
- * appear on classes that represent module descriptors.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#modulePackages() ModulePackages} attribute (JVMS
+ * {@jvms 4.7.26}), which can appear on classes that {@linkplain
+ * ClassModel#isModuleInfo() represent} module descriptors to indicate packages
+ * in the module used by the module descriptor.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 9.
+ * The attribute was introduced in the Java SE Platform version 9, major version
+ * {@value ClassFile#JAVA_9_VERSION}.
*
+ * @see Attributes#modulePackages()
+ * @see ModuleDescriptor#packages()
+ * @jvms 4.7.26 The {@code ModulePackages} Attribute
* @since 24
*/
public sealed interface ModulePackagesAttribute
@@ -55,7 +65,9 @@ public sealed interface ModulePackagesAttribute
UnboundAttribute.UnboundModulePackagesAttribute {
/**
- * {@return the packages that are opened or exported by this module}
+ * {@return the packages used by the module descriptor} This must include
+ * all packages opened or exported by the module, as well as the packages of
+ * any service providers, and the package for the main class.
*/
List packages();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleProvideInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleProvideInfo.java
index ce68848d4dc..76dc88c50f7 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleProvideInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleProvideInfo.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
@@ -26,6 +26,7 @@
import java.lang.classfile.constantpool.ClassEntry;
import java.lang.constant.ClassDesc;
+import java.lang.module.ModuleDescriptor;
import java.util.Arrays;
import java.util.List;
@@ -36,6 +37,9 @@
/**
* Models a single "provides" declaration in the {@link ModuleAttribute}.
*
+ * @see ModuleAttribute#provides()
+ * @see ModuleDescriptor.Provides
+ * @jvms 4.7.25 The {@code Module} Attribute
* @since 24
*/
public sealed interface ModuleProvideInfo
@@ -43,18 +47,23 @@ public sealed interface ModuleProvideInfo
/**
* {@return the service interface representing the provided service}
+ *
+ * @see ModuleDescriptor.Provides#service()
*/
ClassEntry provides();
/**
- * {@return the classes providing the service implementation}
+ * {@return the classes providing the service implementation} The list
+ * should not be empty.
+ *
+ * @see ModuleDescriptor.Provides#providers()
*/
List providesWith();
/**
* {@return a service provision description}
* @param provides the service class interface
- * @param providesWith the service class implementations
+ * @param providesWith the service class implementations, must not be empty
*/
static ModuleProvideInfo of(ClassEntry provides,
List providesWith) {
@@ -64,7 +73,7 @@ static ModuleProvideInfo of(ClassEntry provides,
/**
* {@return a service provision description}
* @param provides the service class interface
- * @param providesWith the service class implementations
+ * @param providesWith the service class implementations, must not be empty
*/
static ModuleProvideInfo of(ClassEntry provides,
ClassEntry... providesWith) {
@@ -74,22 +83,24 @@ static ModuleProvideInfo of(ClassEntry provides,
/**
* {@return a service provision description}
* @param provides the service class interface
- * @param providesWith the service class implementations
- * @throws IllegalArgumentException if {@code provides} represents a primitive type
+ * @param providesWith the service class implementations, must not be empty
+ * @throws IllegalArgumentException if {@code provides} or any of {@code
+ * providesWith} represents a primitive type
*/
static ModuleProvideInfo of(ClassDesc provides,
- List providesWith) {
+ List providesWith) {
return of(TemporaryConstantPool.INSTANCE.classEntry(provides), Util.entryList(providesWith));
}
/**
* {@return a service provision description}
* @param provides the service class interface
- * @param providesWith the service class implementations
- * @throws IllegalArgumentException if {@code provides} or any of {@code providesWith} represents a primitive type
+ * @param providesWith the service class implementations, must not be empty
+ * @throws IllegalArgumentException if {@code provides} or any of {@code
+ * providesWith} represents a primitive type
*/
static ModuleProvideInfo of(ClassDesc provides,
- ClassDesc... providesWith) {
+ ClassDesc... providesWith) {
// List view, since ref to providesWith is temporary
return of(provides, Arrays.asList(providesWith));
}
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.java
index 578a783f277..edffe941629 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.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
@@ -27,6 +27,7 @@
import java.lang.classfile.constantpool.ModuleEntry;
import java.lang.classfile.constantpool.Utf8Entry;
import java.lang.constant.ModuleDesc;
+import java.lang.module.ModuleDescriptor;
import java.lang.reflect.AccessFlag;
import java.util.Collection;
import java.util.Optional;
@@ -39,6 +40,9 @@
/**
* Models a single "requires" declaration in the {@link ModuleAttribute}.
*
+ * @see ModuleAttribute#requires()
+ * @see ModuleDescriptor#requires()
+ * @jvms 4.7.25 The {@code Module} Attribute
* @since 24
*/
public sealed interface ModuleRequireInfo
@@ -51,15 +55,19 @@ public sealed interface ModuleRequireInfo
/**
* {@return the flags associated with this require declaration, as a bit mask}
- * Valid flags include {@link java.lang.classfile.ClassFile#ACC_TRANSITIVE},
- * {@link java.lang.classfile.ClassFile#ACC_STATIC_PHASE},
- * {@link java.lang.classfile.ClassFile#ACC_SYNTHETIC} and
- * {@link java.lang.classfile.ClassFile#ACC_MANDATED}
+ *
+ * @see ModuleDescriptor.Requires#modifiers()
+ * @see AccessFlag.Location#MODULE_REQUIRES
*/
int requiresFlagsMask();
/**
- * {@return the access flags}
+ * {@return the flags associated with this require declaration, as a set of
+ * flag enums}
+ *
+ * @throws IllegalArgumentException if the flags mask has any undefined bit set
+ * @see ModuleDescriptor.Requires#accessFlags()
+ * @see AccessFlag.Location#MODULE_REQUIRES
*/
default Set requiresFlags() {
return AccessFlag.maskToAccessFlags(requiresFlagsMask(), AccessFlag.Location.MODULE_REQUIRES);
@@ -67,12 +75,16 @@ default Set requiresFlags() {
/**
* {@return the required version of the required module, if present}
+ *
+ * @see ModuleDescriptor.Requires#rawCompiledVersion()
*/
Optional requiresVersion();
/**
* {@return whether the specific access flag is set}
+ *
* @param flag the access flag
+ * @see AccessFlag.Location#MODULE_REQUIRES
*/
default boolean has(AccessFlag flag) {
return Util.has(AccessFlag.Location.MODULE_REQUIRES, requiresFlagsMask(), flag);
@@ -80,9 +92,10 @@ default boolean has(AccessFlag flag) {
/**
* {@return a module requirement description}
+ *
* @param requires the required module
* @param requiresFlags the require-specific flags
- * @param requiresVersion the required version
+ * @param requiresVersion the required version, may be {@code null}
*/
static ModuleRequireInfo of(ModuleEntry requires, int requiresFlags, Utf8Entry requiresVersion) {
return new UnboundAttribute.UnboundModuleRequiresInfo(requires, requiresFlags, Optional.ofNullable(requiresVersion));
@@ -90,9 +103,12 @@ static ModuleRequireInfo of(ModuleEntry requires, int requiresFlags, Utf8Entry r
/**
* {@return a module requirement description}
+ *
* @param requires the required module
* @param requiresFlags the require-specific flags
- * @param requiresVersion the required version
+ * @param requiresVersion the required version, may be {@code null}
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_REQUIRES} location
*/
static ModuleRequireInfo of(ModuleEntry requires, Collection requiresFlags, Utf8Entry requiresVersion) {
return of(requires, Util.flagsToBits(AccessFlag.Location.MODULE_REQUIRES, requiresFlags), requiresVersion);
@@ -100,9 +116,10 @@ static ModuleRequireInfo of(ModuleEntry requires, Collection require
/**
* {@return a module requirement description}
+ *
* @param requires the required module
* @param requiresFlags the require-specific flags
- * @param requiresVersion the required version
+ * @param requiresVersion the required version, may be {@code null}
*/
static ModuleRequireInfo of(ModuleDesc requires, int requiresFlags, String requiresVersion) {
return new UnboundAttribute.UnboundModuleRequiresInfo(TemporaryConstantPool.INSTANCE.moduleEntry(TemporaryConstantPool.INSTANCE.utf8Entry(requires.name())), requiresFlags, Optional.ofNullable(requiresVersion).map(s -> TemporaryConstantPool.INSTANCE.utf8Entry(s)));
@@ -110,9 +127,12 @@ static ModuleRequireInfo of(ModuleDesc requires, int requiresFlags, String requi
/**
* {@return a module requirement description}
+ *
* @param requires the required module
* @param requiresFlags the require-specific flags
- * @param requiresVersion the required version
+ * @param requiresVersion the required version, may be {@code null}
+ * @throws IllegalArgumentException if any flag cannot be applied to the
+ * {@link AccessFlag.Location#MODULE_REQUIRES} location
*/
static ModuleRequireInfo of(ModuleDesc requires, Collection requiresFlags, String requiresVersion) {
return of(requires, Util.flagsToBits(AccessFlag.Location.MODULE_REQUIRES, requiresFlags), requiresVersion);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.java
index 3457cb8073e..75e9ca485ff 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.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
@@ -26,19 +26,21 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassModel;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code ModuleResolution} attribute, which can
- * appear on classes that represent module descriptors. This is a JDK-specific
- * * attribute, which captures resolution metadata for modules.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
- *
- * The specification of the {@code ModuleResolution} attribute is:
+ * Models the {@link Attributes#moduleResolution() ModuleResolution} attribute,
+ * which can appear on classes that {@linkplain ClassModel#isModuleInfo()
+ * represent} module descriptors, to capture resolution metadata for modules.
+ *
+ * The specification of the {@code ModuleResolution} attribute is:
*
{@code
* ModuleResolution_attribute {
* u2 attribute_name_index; // "ModuleResolution"
@@ -58,10 +60,17 @@
* }
* }
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has
+ * {@linkplain AttributeStability#STATELESS no data dependency}.
+ *
+ * This attribute is not predefined in the Java SE Platform. This is a
+ * JDK-specific nonstandard attribute produced by the {@code jdk.jlink} module,
+ * which defines the {@code jlink} and {@code jmod} tools.
*
+ * @see Attributes#moduleResolution()
+ * @see ModuleHashesAttribute
+ * @see ModuleTargetAttribute
* @since 24
*/
public sealed interface ModuleResolutionAttribute
@@ -69,8 +78,10 @@ public sealed interface ModuleResolutionAttribute
permits BoundAttribute.BoundModuleResolutionAttribute, UnboundAttribute.UnboundModuleResolutionAttribute {
/**
- * The value of the resolution_flags item is a mask of flags used to denote
- * properties of module resolution. The flags are as follows:
+ * {@return the module resolution flags}
+ *
+ * The value of the resolution_flags item is a mask of flags used to denote
+ * properties of module resolution. The flags are as follows:
*
{@code
* // Optional
* 0x0001 (DO_NOT_RESOLVE_BY_DEFAULT)
@@ -80,12 +91,12 @@ public sealed interface ModuleResolutionAttribute
* 0x0004 (WARN_DEPRECATED_FOR_REMOVAL)
* 0x0008 (WARN_INCUBATING)
* }
- * @return the module resolution flags
*/
int resolutionFlags();
/**
* {@return a {@code ModuleResolution} attribute}
+ *
* @param resolutionFlags the resolution flags
*/
static ModuleResolutionAttribute of(int resolutionFlags) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleTargetAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleTargetAttribute.java
index ac390c3d391..6d727db6851 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleTargetAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleTargetAttribute.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
@@ -26,7 +26,11 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassModel;
import java.lang.classfile.constantpool.Utf8Entry;
import jdk.internal.classfile.impl.BoundAttribute;
@@ -34,13 +38,11 @@
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code ModuleTarget} attribute, which can
- * appear on classes that represent module descriptors. This is a JDK-specific
- * attribute, which captures constraints on the target platform.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
- *
- * The specification of the {@code ModuleTarget} attribute is:
+ * Models the {@link Attributes#moduleTarget() ModuleTarget} attribute, which
+ * can appear on classes that {@linkplain ClassModel#isModuleInfo() represent}
+ * module descriptors, to represent constraints on the target platform.
+ *
+ * The specification of the {@code ModuleTarget} attribute is:
*
{@code
* TargetPlatform_attribute {
* // index to CONSTANT_utf8_info structure in constant pool representing
@@ -53,10 +55,17 @@
* }
* }
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * This attribute is not predefined in the Java SE Platform. This is a
+ * JDK-specific nonstandard attribute produced by the {@code jdk.jlink} module,
+ * which defines the {@code jlink} and {@code jmod} tools.
*
+ * @see Attributes#moduleTarget()
+ * @see ModuleHashesAttribute
+ * @see ModuleResolutionAttribute
* @since 24
*/
public sealed interface ModuleTargetAttribute
@@ -70,6 +79,7 @@ public sealed interface ModuleTargetAttribute
/**
* {@return a {@code ModuleTarget} attribute}
+ *
* @param targetPlatform the target platform
*/
static ModuleTargetAttribute of(String targetPlatform) {
@@ -78,6 +88,7 @@ static ModuleTargetAttribute of(String targetPlatform) {
/**
* {@return a {@code ModuleTarget} attribute}
+ *
* @param targetPlatform the target platform
*/
static ModuleTargetAttribute of(Utf8Entry targetPlatform) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.java
index ccfb61242cd..d2c398e556b 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.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
@@ -26,7 +26,11 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.constantpool.ClassEntry;
import java.lang.constant.ClassDesc;
@@ -35,17 +39,22 @@
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code NestHost} attribute (JVMS {@jvms 4.7.28}), which can
- * appear on classes to indicate that this class is a member of a nest.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#nestHost() NestHost} attribute (JVMS {@jvms
+ * 4.7.28}), which indicates this class is a member of a nest and the host
+ * class of the nest.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 11.
+ * The attribute was introduced in the Java SE Platform version 11, major
+ * version {@value ClassFile#JAVA_11_VERSION}.
*
+ * @see Attributes#nestHost()
+ * @see NestMembersAttribute
+ * @see Class#getNestHost()
+ * @see Class#isNestmateOf(Class)
+ * @jvms 4.7.28 The {@code NestHost} Attribute
* @since 24
*/
public sealed interface NestHostAttribute extends Attribute, ClassElement
@@ -54,11 +63,14 @@ public sealed interface NestHostAttribute extends Attribute,
/**
* {@return the host class of the nest to which this class belongs}
+ *
+ * @see Class#getNestHost()
*/
ClassEntry nestHost();
/**
* {@return a {@code NestHost} attribute}
+ *
* @param nestHost the host class of the nest
*/
static NestHostAttribute of(ClassEntry nestHost) {
@@ -67,6 +79,7 @@ static NestHostAttribute of(ClassEntry nestHost) {
/**
* {@return a {@code NestHost} attribute}
+ *
* @param nestHost the host class of the nest
* @throws IllegalArgumentException if {@code nestHost} represents a primitive type
*/
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.java
index b01c05542de..baab955221c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.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
@@ -25,7 +25,11 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.constantpool.ClassEntry;
import java.lang.constant.ClassDesc;
import java.util.Arrays;
@@ -36,17 +40,22 @@
import jdk.internal.classfile.impl.Util;
/**
- * Models the {@code NestMembers} attribute (JVMS {@jvms 4.7.29}), which can
- * appear on classes to indicate that this class is the host of a nest.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#nestMembers() NestMembers} attribute (JVMS
+ * {@jvms 4.7.29}), which indicates that this class is the host of a nest
+ * and the other nest members.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 11.
+ * The attribute was introduced in the Java SE Platform version 11, major
+ * version {@value ClassFile#JAVA_11_VERSION}.
*
+ * @see Attributes#nestMembers()
+ * @see NestHostAttribute
+ * @see Class#getNestMembers()
+ * @see Class#isNestmateOf(Class)
+ * @jvms 4.7.29 The {@code NestMembers} Attribute
* @since 24
*/
public sealed interface NestMembersAttribute extends Attribute, ClassElement
@@ -54,11 +63,14 @@ public sealed interface NestMembersAttribute extends Attribute nestMembers();
/**
* {@return a {@code NestMembers} attribute}
+ *
* @param nestMembers the member classes of the nest
*/
static NestMembersAttribute of(List nestMembers) {
@@ -67,6 +79,7 @@ static NestMembersAttribute of(List nestMembers) {
/**
* {@return a {@code NestMembers} attribute}
+ *
* @param nestMembers the member classes of the nest
*/
static NestMembersAttribute of(ClassEntry... nestMembers) {
@@ -75,7 +88,9 @@ static NestMembersAttribute of(ClassEntry... nestMembers) {
/**
* {@return a {@code NestMembers} attribute}
+ *
* @param nestMembers the member classes of the nest
+ * @throws IllegalArgumentException if any of {@code nestMembers} is primitive
*/
static NestMembersAttribute ofSymbols(List nestMembers) {
return of(Util.entryList(nestMembers));
@@ -83,10 +98,12 @@ static NestMembersAttribute ofSymbols(List nestMembers) {
/**
* {@return a {@code NestMembers} attribute}
+ *
* @param nestMembers the member classes of the nest
+ * @throws IllegalArgumentException if any of {@code nestMembers} is primitive
*/
static NestMembersAttribute ofSymbols(ClassDesc... nestMembers) {
- // List view, since ref to nestMembers is temporary
+ // List version does defensive copy
return ofSymbols(Arrays.asList(nestMembers));
}
}
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.java
index dac63c73435..026cbb96ca0 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.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
@@ -25,7 +25,11 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.constantpool.ClassEntry;
import java.lang.constant.ClassDesc;
import java.util.Arrays;
@@ -36,31 +40,43 @@
import jdk.internal.classfile.impl.Util;
/**
- * Models the {@code PermittedSubclasses} attribute (JVMS {@jvms 4.7.31}), which can
- * appear on classes to indicate which classes may extend this class.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#permittedSubclasses() PermittedSubclasses}
+ * attribute (JVMS {@jvms 4.7.31}), which indicates this class or interface
+ * is {@linkplain java.compiler/javax.lang.model.element.Modifier#SEALED sealed},
+ * and which classes or interfaces may extend or implement this class or
+ * interface.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 17.
+ * The attribute was introduced in the Java SE Platform version 17, major
+ * version {@value ClassFile#JAVA_17_VERSION}.
*
+ * @see Attributes#permittedSubclasses()
+ * @see Class#isSealed()
+ * @see Class#getPermittedSubclasses()
+ * @jls 8.1.1.2 {@code sealed}, {@code non-sealed}, and {@code final} Classes
+ * @jls 9.1.1.4 {@code sealed} and {@code non-sealed} Interfaces
+ * @jvms 4.7.31 The {@code PermittedSubclasses} Attribute
* @since 24
*/
+@SuppressWarnings("doclint:reference")
public sealed interface PermittedSubclassesAttribute
extends Attribute, ClassElement
permits BoundAttribute.BoundPermittedSubclassesAttribute, UnboundAttribute.UnboundPermittedSubclassesAttribute {
/**
- * {@return the list of permitted subclasses}
+ * {@return the list of permitted subclasses or subinterfaces}
+ *
+ * @see Class#getPermittedSubclasses()
*/
List permittedSubclasses();
/**
* {@return a {@code PermittedSubclasses} attribute}
- * @param permittedSubclasses the permitted subclasses
+ *
+ * @param permittedSubclasses the permitted subclasses or subinterfaces
*/
static PermittedSubclassesAttribute of(List permittedSubclasses) {
return new UnboundAttribute.UnboundPermittedSubclassesAttribute(permittedSubclasses);
@@ -68,7 +84,8 @@ static PermittedSubclassesAttribute of(List permittedSubclasses) {
/**
* {@return a {@code PermittedSubclasses} attribute}
- * @param permittedSubclasses the permitted subclasses
+ *
+ * @param permittedSubclasses the permitted subclasses or subinterfaces
*/
static PermittedSubclassesAttribute of(ClassEntry... permittedSubclasses) {
return of(List.of(permittedSubclasses));
@@ -76,7 +93,9 @@ static PermittedSubclassesAttribute of(ClassEntry... permittedSubclasses) {
/**
* {@return a {@code PermittedSubclasses} attribute}
- * @param permittedSubclasses the permitted subclasses
+ *
+ * @param permittedSubclasses the permitted subclasses or subinterfaces
+ * @throws IllegalArgumentException if any of {@code permittedSubclasses} is primitive
*/
static PermittedSubclassesAttribute ofSymbols(List permittedSubclasses) {
return of(Util.entryList(permittedSubclasses));
@@ -84,10 +103,12 @@ static PermittedSubclassesAttribute ofSymbols(List permittedSubclasse
/**
* {@return a {@code PermittedSubclasses} attribute}
- * @param permittedSubclasses the permitted subclasses
+ *
+ * @param permittedSubclasses the permitted subclasses or subinterfaces
+ * @throws IllegalArgumentException if any of {@code permittedSubclasses} is primitive
*/
static PermittedSubclassesAttribute ofSymbols(ClassDesc... permittedSubclasses) {
- // List view, since ref to nestMembers is temporary
+ // List version does defensive copy
return ofSymbols(Arrays.asList(permittedSubclasses));
}
}
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.java
index b0c4fa7c61c..8f55b3a1cf9 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.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
@@ -26,24 +26,32 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code Record} attribute (JVMS {@jvms 4.7.30}), which can
- * appear on classes to indicate that this class is a record class.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#record() Record} attribute (JVMS {@jvms 4.7.30}),
+ * which indicates that this class is a record class and the record
+ * components.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 16.
+ * The attribute was introduced in the Java SE Platform version 16, major
+ * version {@value ClassFile#JAVA_16_VERSION}.
*
+ * @see Attributes#record()
+ * @see Class#isRecord()
+ * @see Class#getRecordComponents()
+ * @jvms 4.7.30 The {@code Record} Attribute
* @since 24
*/
public sealed interface RecordAttribute extends Attribute, ClassElement
@@ -51,11 +59,14 @@ public sealed interface RecordAttribute extends Attribute, Clas
/**
* {@return the components of this record class}
+ *
+ * @see Class#getRecordComponents()
*/
List components();
/**
* {@return a {@code Record} attribute}
+ *
* @param components the record components
*/
static RecordAttribute of(List components) {
@@ -64,6 +75,7 @@ static RecordAttribute of(List components) {
/**
* {@return a {@code Record} attribute}
+ *
* @param components the record components
*/
static RecordAttribute of(RecordComponentInfo... components) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RecordComponentInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/RecordComponentInfo.java
index 73e4497915e..f3c74f066cf 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RecordComponentInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RecordComponentInfo.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
@@ -28,6 +28,7 @@
import java.lang.classfile.AttributedElement;
import java.lang.classfile.constantpool.Utf8Entry;
import java.lang.constant.ClassDesc;
+import java.lang.reflect.RecordComponent;
import java.util.List;
import jdk.internal.classfile.impl.BoundRecordComponentInfo;
@@ -36,8 +37,17 @@
import jdk.internal.classfile.impl.Util;
/**
- * Models a single record component in the {@link java.lang.classfile.attribute.RecordAttribute}.
+ * Models a single record component in the {@link RecordAttribute}.
+ *
+ * {@link SignatureAttribute}, {@link RuntimeVisibleAnnotationsAttribute},
+ * {@link RuntimeInvisibleAnnotationsAttribute}, {@link
+ * RuntimeVisibleTypeAnnotationsAttribute}, and {@link
+ * RuntimeInvisibleTypeAnnotationsAttribute} are the only predefined attributes
+ * that may exist on record components.
*
+ * @see RecordAttribute#components()
+ * @see RecordComponent
+ * @jvms 4.7.30 The {@code Record} Attribute
* @since 24
*/
public sealed interface RecordComponentInfo
@@ -45,16 +55,30 @@ public sealed interface RecordComponentInfo
permits BoundRecordComponentInfo, UnboundAttribute.UnboundRecordComponentInfo {
/**
* {@return the name of this component}
+ *
+ * @see RecordComponent#getName()
*/
Utf8Entry name();
/**
- * {@return the field descriptor of this component}
+ * {@return the field descriptor string of this component}
+ *
+ * @apiNote
+ * A record component may have a generic type; this information is stored
+ * in the {@link SignatureAttribute Signature} attribute in this component.
+ *
+ * @see RecordComponent#getType()
*/
Utf8Entry descriptor();
/**
- * {@return the field descriptor of this component, as a {@linkplain ClassDesc}}
+ * {@return the symbolic field descriptor of this component}
+ *
+ * @apiNote
+ * A record component may have a generic type; this information is stored
+ * in the {@link SignatureAttribute Signature} attribute in this component.
+ *
+ * @see RecordComponent#getType()
*/
default ClassDesc descriptorSymbol() {
return Util.fieldTypeSymbol(descriptor());
@@ -62,8 +86,9 @@ default ClassDesc descriptorSymbol() {
/**
* {@return a record component description}
+ *
* @param name the component name
- * @param descriptor the component field descriptor
+ * @param descriptor the component field descriptor string
* @param attributes the component attributes
*/
static RecordComponentInfo of(Utf8Entry name,
@@ -74,8 +99,9 @@ static RecordComponentInfo of(Utf8Entry name,
/**
* {@return a record component description}
+ *
* @param name the component name
- * @param descriptor the component field descriptor
+ * @param descriptor the component field descriptor sting
* @param attributes the component attributes
*/
static RecordComponentInfo of(Utf8Entry name,
@@ -86,8 +112,9 @@ static RecordComponentInfo of(Utf8Entry name,
/**
* {@return a record component description}
+ *
* @param name the component name
- * @param descriptor the component field descriptor
+ * @param descriptor the component symbolic field descriptor
* @param attributes the component attributes
*/
static RecordComponentInfo of(String name,
@@ -100,8 +127,9 @@ static RecordComponentInfo of(String name,
/**
* {@return a record component description}
+ *
* @param name the component name
- * @param descriptor the component field descriptor
+ * @param descriptor the component symbolic field descriptor
* @param attributes the component attributes
*/
static RecordComponentInfo of(String name,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.java
index 58903859464..da453ad4f5e 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.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
@@ -25,30 +25,39 @@
package java.lang.classfile.attribute;
-import java.lang.classfile.Annotation;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AnnotatedElement;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code RuntimeInvisibleAnnotations} attribute (JVMS {@jvms 4.7.17}), which
- * can appear on classes, methods, and fields. Delivered as a
- * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement}, or
- * {@link java.lang.classfile.MethodElement} when traversing the corresponding model type.
+ * Models the {@link Attributes#runtimeInvisibleAnnotations()
+ * RuntimeInvisibleAnnotations} attribute (JVMS {@jvms 4.7.17}), which stores
+ * declaration annotations on this structure that are visible to {@code
+ * class} file consumers but are not visible to {@linkplain AnnotatedElement
+ * core reflection}.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, and record components,
+ * and does not permit {@linkplain AttributeMapper#allowMultiple multiple
+ * instances} in one structure. It has a data dependency on the {@linkplain
+ * AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Attributes#runtimeInvisibleAnnotations()
+ * @see java.compiler/javax.lang.model.element.Element
+ * @see ElementType
+ * @see RetentionPolicy#CLASS
+ * @jvms 4.7.17 The {@code RuntimeInvisibleAnnotations} Attribute
* @since 24
*/
+@SuppressWarnings("doclint:reference")
public sealed interface RuntimeInvisibleAnnotationsAttribute
extends Attribute,
ClassElement, MethodElement, FieldElement
@@ -56,12 +65,13 @@ public sealed interface RuntimeInvisibleAnnotationsAttribute
UnboundAttribute.UnboundRuntimeInvisibleAnnotationsAttribute {
/**
- * {@return the non-runtime-visible annotations on this class, field, or method}
+ * {@return the run-time invisible declaration annotations on this structure}
*/
List annotations();
/**
* {@return a {@code RuntimeInvisibleAnnotations} attribute}
+ *
* @param annotations the annotations
*/
static RuntimeInvisibleAnnotationsAttribute of(List annotations) {
@@ -70,6 +80,7 @@ static RuntimeInvisibleAnnotationsAttribute of(List annotations) {
/**
* {@return a {@code RuntimeInvisibleAnnotations} attribute}
+ *
* @param annotations the annotations
*/
static RuntimeInvisibleAnnotationsAttribute of(Annotation... annotations) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.java
index f1c02b77e1e..2051cd5dcdf 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.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
@@ -25,26 +25,39 @@
package java.lang.classfile.attribute;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
import java.lang.classfile.Annotation;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.MethodElement;
-import java.lang.classfile.MethodModel;
+import java.lang.reflect.AnnotatedElement;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code RuntimeInvisibleParameterAnnotations} attribute
- * (JVMS {@jvms 4.7.19}), which can appear on methods. Delivered as a {@link
- * java.lang.classfile.MethodElement} when traversing a {@link MethodModel}.
+ * Models the {@link Attributes#runtimeInvisibleParameterAnnotations()
+ * RuntimeInvisibleParameterAnnotations} attribute (JVMS {@jvms 4.7.19}), which
+ * stores declaration annotations on the method parameters of this method
+ * that are visible to {@code class} file consumers but are not visible to
+ * {@linkplain AnnotatedElement core reflection}.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Attributes#runtimeInvisibleParameterAnnotations()
+ * @see ElementType#PARAMETER
+ * @see RetentionPolicy#CLASS
+ * @jvms 4.7.19 The {@code RuntimeInvisibleParameterAnnotations} Attribute
* @since 24
*/
public sealed interface RuntimeInvisibleParameterAnnotationsAttribute
@@ -53,15 +66,26 @@ public sealed interface RuntimeInvisibleParameterAnnotationsAttribute
UnboundAttribute.UnboundRuntimeInvisibleParameterAnnotationsAttribute {
/**
- * {@return the list of annotations corresponding to each method parameter}
+ * {@return the list of run-time invisible annotations on the method parameters}
* The element at the i'th index corresponds to the annotations on the i'th
- * parameter.
+ * formal parameter, but note that some synthetic or implicit parameters
+ * may be omitted by this list. If a parameter has no annotations, that
+ * element is left empty, but is not omitted; thus, the list will never be
+ * truncated because trailing parameters are not annotated.
+ *
+ * @see java.lang.reflect##LanguageJvmModel Java programming language and
+ * JVM modeling in core reflection
*/
List> parameterAnnotations();
/**
* {@return a {@code RuntimeInvisibleParameterAnnotations} attribute}
- * @param parameterAnnotations a list of parameter annotations for each parameter
+ * The {@code parameterAnnotations} list should not be truncated, and must
+ * have a length equal to the number of formal parameters; elements for
+ * unannotated parameters may be empty, but may not be omitted. It may omit
+ * some synthetic or implicit parameters.
+ *
+ * @param parameterAnnotations a list of run-time invisible annotations for each parameter
*/
static RuntimeInvisibleParameterAnnotationsAttribute of(List> parameterAnnotations) {
return new UnboundAttribute.UnboundRuntimeInvisibleParameterAnnotationsAttribute(parameterAnnotations);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.java
index 7500d39fc19..3ff1a643a82 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.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
@@ -25,32 +25,44 @@
package java.lang.classfile.attribute;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.CodeElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
-import java.lang.classfile.TypeAnnotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AnnotatedType;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code RuntimeInvisibleTypeAnnotations} attribute (JVMS {@jvms 4.7.21}), which
- * can appear on classes, methods, fields, and code attributes. Delivered as a
- * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement},
- * {@link java.lang.classfile.MethodElement}, or {@link CodeElement} when traversing
- * the corresponding model type.
+ * Models the {@link Attributes#runtimeInvisibleTypeAnnotations()
+ * RuntimeInvisibleTypeAnnotations} attribute (JVMS {@jvms 4.7.21}), which
+ * stores type-use annotations for the annotated uses of types in this
+ * structure that are visible to {@code class} file consumers but are not
+ * visible to {@linkplain AnnotatedType core reflection}. Its delivery in the
+ * traversal of a {@link CodeModel} may be toggled by {@link
+ * ClassFile.DebugElementsOption}.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, {@code Code} attributes,
+ * and record components, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in one structure. It has a
+ * data dependency on {@linkplain AttributeStability#UNSTABLE arbitrary indices}
+ * in the {@code class} file format, so users must take great care to ensure
+ * this attribute is still correct after a {@code class} file has been transformed.
*
- * The attribute was introduced in the Java SE Platform version 8.
+ * The attribute was introduced in the Java SE Platform version 8, major version
+ * {@value ClassFile#JAVA_8_VERSION}.
*
+ * @see Attributes#runtimeInvisibleTypeAnnotations()
+ * @see java.compiler/javax.lang.model.type.TypeMirror
+ * @see ElementType#TYPE_PARAMETER
+ * @see ElementType#TYPE_USE
+ * @see RetentionPolicy#CLASS
+ * @jvms 4.7.21 The {@code RuntimeInvisibleTypeAnnotations} Attribute
* @since 24
*/
+@SuppressWarnings("doclint:reference")
public sealed interface RuntimeInvisibleTypeAnnotationsAttribute
extends Attribute,
ClassElement, MethodElement, FieldElement, CodeElement
@@ -58,12 +70,14 @@ public sealed interface RuntimeInvisibleTypeAnnotationsAttribute
UnboundAttribute.UnboundRuntimeInvisibleTypeAnnotationsAttribute {
/**
- * {@return the non-runtime-visible type annotations on parts of this class, field, or method}
+ * {@return the run-time invisible annotations on uses of types in this
+ * structure}
*/
List annotations();
/**
* {@return a {@code RuntimeInvisibleTypeAnnotations} attribute}
+ *
* @param annotations the annotations
*/
static RuntimeInvisibleTypeAnnotationsAttribute of(List annotations) {
@@ -72,6 +86,7 @@ static RuntimeInvisibleTypeAnnotationsAttribute of(List annotati
/**
* {@return a {@code RuntimeInvisibleTypeAnnotations} attribute}
+ *
* @param annotations the annotations
*/
static RuntimeInvisibleTypeAnnotationsAttribute of(TypeAnnotation... annotations) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.java
index d41fcf3794b..ceabe2131af 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.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
@@ -25,30 +25,39 @@
package java.lang.classfile.attribute;
-import java.lang.classfile.Annotation;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AnnotatedElement;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code RuntimeVisibleAnnotations} attribute (JVMS {@jvms 4.7.16}), which
- * can appear on classes, methods, and fields. Delivered as a
- * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement}, or
- * {@link java.lang.classfile.MethodElement} when traversing the corresponding model type.
+ * Models the {@link Attributes#runtimeVisibleAnnotations()
+ * RuntimeVisibleAnnotations} attribute (JVMS {@jvms 4.7.16}), which stores
+ * declaration annotations on this structure that are visible to both
+ * {@code class} file consumers and {@linkplain AnnotatedElement core reflection}.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, and record components,
+ * and does not permit {@linkplain AttributeMapper#allowMultiple multiple
+ * instances} in one structure. It has a data dependency on the {@linkplain
+ * AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Attributes#runtimeVisibleAnnotations()
+ * @see java.compiler/javax.lang.model.element.Element
+ * @see AnnotatedElement
+ * @see ElementType
+ * @see RetentionPolicy#RUNTIME
+ * @jvms 4.7.16 The {@code RuntimeVisibleAnnotations} Attribute
* @since 24
*/
+@SuppressWarnings("doclint:reference")
public sealed interface RuntimeVisibleAnnotationsAttribute
extends Attribute,
ClassElement, MethodElement, FieldElement
@@ -56,7 +65,7 @@ public sealed interface RuntimeVisibleAnnotationsAttribute
UnboundAttribute.UnboundRuntimeVisibleAnnotationsAttribute {
/**
- * {@return the runtime-visible annotations on this class, field, or method}
+ * {@return the run-time visible declaration annotations on this structure}
*/
List annotations();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.java
index 5ed9817eeb9..2cf462d246c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.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
@@ -25,26 +25,41 @@
package java.lang.classfile.attribute;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
import java.lang.classfile.Annotation;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.MethodElement;
-import java.lang.classfile.MethodModel;
+import java.lang.reflect.AnnotatedElement;
+import java.lang.reflect.Executable;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code RuntimeVisibleParameterAnnotations} attribute (JVMS {@jvms 4.7.18}), which
- * can appear on methods. Delivered as a {@link java.lang.classfile.MethodElement}
- * when traversing a {@link MethodModel}.
- *
- * @apiNote The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * Models the {@link Attributes#runtimeVisibleParameterAnnotations()
+ * RuntimeVisibleParameterAnnotations} attribute (JVMS {@jvms 4.7.18}), which
+ * stores declaration annotations on the method parameters of this method
+ * that are visible to both {@code class} file consumers and {@linkplain
+ * AnnotatedElement core reflection}.
+ *
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Attributes#runtimeVisibleParameterAnnotations()
+ * @see Executable#getParameterAnnotations()
+ * @see ElementType#PARAMETER
+ * @see RetentionPolicy#RUNTIME
+ * @jvms 4.7.18 The {@code RuntimeVisibleParameterAnnotations} Attribute
* @since 24
*/
public sealed interface RuntimeVisibleParameterAnnotationsAttribute
@@ -53,15 +68,26 @@ public sealed interface RuntimeVisibleParameterAnnotationsAttribute
UnboundAttribute.UnboundRuntimeVisibleParameterAnnotationsAttribute {
/**
- * {@return the list of annotations corresponding to each method parameter}
+ * {@return the list of run-time visible annotations on the method parameters}
* The element at the i'th index corresponds to the annotations on the i'th
- * parameter.
+ * formal parameter, but note that some synthetic or implicit parameters
+ * may be omitted by this list. If a parameter has no annotations, that
+ * element is left empty, but is not omitted; thus, the list will never be
+ * truncated because trailing parameters are not annotated.
+ *
+ * @see java.lang.reflect##LanguageJvmModel Java programming language and
+ * JVM modeling in core reflection
*/
List> parameterAnnotations();
/**
* {@return a {@code RuntimeVisibleParameterAnnotations} attribute}
- * @param parameterAnnotations a list of parameter annotations for each parameter
+ * The {@code parameterAnnotations} list should not be truncated, and must
+ * have a length equal to the number of formal parameters; elements for
+ * unannotated parameters may be empty, but may not be omitted. It may omit
+ * some synthetic or implicit parameters.
+ *
+ * @param parameterAnnotations a list of run-time visible annotations for each parameter
*/
static RuntimeVisibleParameterAnnotationsAttribute of(List> parameterAnnotations) {
return new UnboundAttribute.UnboundRuntimeVisibleParameterAnnotationsAttribute(parameterAnnotations);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.java
index a4e780c4536..ad4595ffb6b 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.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
@@ -25,32 +25,44 @@
package java.lang.classfile.attribute;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.CodeElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
-import java.lang.classfile.TypeAnnotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AnnotatedType;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code RuntimeVisibleTypeAnnotations} attribute (JVMS {@jvms 4.7.20}), which
- * can appear on classes, methods, fields, and code attributes. Delivered as a
- * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement},
- * {@link java.lang.classfile.MethodElement}, or {@link CodeElement} when traversing
- * the corresponding model type.
+ * Models the {@link Attributes#runtimeVisibleTypeAnnotations()
+ * RuntimeVisibleTypeAnnotations} attribute (JVMS {@jvms 4.7.20}), which
+ * stores type-use annotations for the annotated uses of types in this
+ * structure that are visible to both {@code class} file consumers and
+ * {@linkplain AnnotatedType core reflection}. Its delivery in the traversal of
+ * a {@link CodeModel} may be toggled by {@link ClassFile.DebugElementsOption}.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, {@code Code} attributes,
+ * and record components, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in one structure. It has a
+ * data dependency on {@linkplain AttributeStability#UNSTABLE arbitrary indices}
+ * in the {@code class} file format, so users must take great care to ensure
+ * this attribute is still correct after a {@code class} file has been transformed.
*
- * The attribute was introduced in the Java SE Platform version 8.
+ * The attribute was introduced in the Java SE Platform version 8, major version
+ * {@value ClassFile#JAVA_8_VERSION}.
*
+ * @see Attributes#runtimeVisibleTypeAnnotations()
+ * @see java.compiler/javax.lang.model.type.TypeMirror
+ * @see AnnotatedType
+ * @see ElementType#TYPE_PARAMETER
+ * @see ElementType#TYPE_USE
+ * @see RetentionPolicy#RUNTIME
+ * @jvms 4.7.20 the {@code RuntimeVisibleTypeAnnotations} Attribute
* @since 24
*/
+@SuppressWarnings("doclint:reference")
public sealed interface RuntimeVisibleTypeAnnotationsAttribute
extends Attribute,
ClassElement, MethodElement, FieldElement, CodeElement
@@ -58,12 +70,14 @@ public sealed interface RuntimeVisibleTypeAnnotationsAttribute
UnboundAttribute.UnboundRuntimeVisibleTypeAnnotationsAttribute {
/**
- * {@return the runtime-visible type annotations on parts of this class, field, or method}
+ * {@return the run-time visible annotations on uses of types in this
+ * structure}
*/
List annotations();
/**
* {@return a {@code RuntimeVisibleTypeAnnotations} attribute}
+ *
* @param annotations the annotations
*/
static RuntimeVisibleTypeAnnotationsAttribute of(List annotations) {
@@ -72,6 +86,7 @@ static RuntimeVisibleTypeAnnotationsAttribute of(List annotation
/**
* {@return a {@code RuntimeVisibleTypeAnnotations} attribute}
+ *
* @param annotations the annotations
*/
static RuntimeVisibleTypeAnnotationsAttribute of(TypeAnnotation... annotations) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.java
index 8f06e16a1b1..2be07e38a58 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.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
@@ -27,24 +27,29 @@
import java.lang.classfile.*;
import java.lang.classfile.constantpool.Utf8Entry;
+import java.lang.reflect.Field;
+import java.lang.reflect.RecordComponent;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.TemporaryConstantPool;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code Signature} attribute (JVMS {@jvms 4.7.9}), which
- * can appear on classes, methods, or fields. Delivered as a
- * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement}, or
- * {@link java.lang.classfile.MethodElement} when traversing
- * the corresponding model type.
+ * Models the {@link Attributes#signature() Signature} attribute (JVMS {@jvms
+ * 4.7.9}), which indicates the generic signature of this structure.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, and record components,
+ * and does not permit {@linkplain AttributeMapper#allowMultiple multiple
+ * instances} in one structure. It has a data dependency on the {@linkplain
+ * AttributeMapper.AttributeStability#CP_REFS constant pool}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Signature
+ * @see ClassSignature
+ * @see MethodSignature
+ * @jvms 4.7.9 The {@code Signature} Attribute
* @since 24
*/
public sealed interface SignatureAttribute
@@ -53,29 +58,46 @@ public sealed interface SignatureAttribute
permits BoundAttribute.BoundSignatureAttribute, UnboundAttribute.UnboundSignatureAttribute {
/**
- * {@return the signature for the class, method, or field}
+ * {@return the signature string for the class, method, field, or record
+ * component} It is a class signature string if this attribute is on a
+ * class, a method signature string if this attribute is on a method, or
+ * a field signature string if this attribute is on a field or a record
+ * component.
+ *
+ * @jvms 4.7.9.1 Signatures
*/
Utf8Entry signature();
/**
- * Parse the signature as a class signature.
+ * Parses the signature string as a class signature.
+ *
* @return the class signature
+ * @throws IllegalArgumentException if the signature string is not a valid
+ * class signature string
*/
default ClassSignature asClassSignature() {
return ClassSignature.parseFrom(signature().stringValue());
}
/**
- * Parse the signature as a method signature.
+ * Parse the signature string as a method signature.
+ *
* @return the method signature
+ * @throws IllegalArgumentException if the signature string is not a valid
+ * method signature string
*/
default MethodSignature asMethodSignature() {
return MethodSignature.parseFrom(signature().stringValue());
}
/**
- * Parse the signature as a type signature.
+ * Parses the signature string as a Java type signature.
+ *
* @return the type signature
+ * @throws IllegalArgumentException if the signature string is not a valid
+ * Java type signature string
+ * @see Field#getGenericType()
+ * @see RecordComponent#getGenericType()
*/
default Signature asTypeSignature() {
return Signature.parseFrom(signature().stringValue());
@@ -83,7 +105,8 @@ default Signature asTypeSignature() {
/**
* {@return a {@code Signature} attribute for a class}
- * @param classSignature the signature
+ *
+ * @param classSignature the class signature
*/
static SignatureAttribute of(ClassSignature classSignature) {
return of(TemporaryConstantPool.INSTANCE.utf8Entry(classSignature.signatureString()));
@@ -91,15 +114,17 @@ static SignatureAttribute of(ClassSignature classSignature) {
/**
* {@return a {@code Signature} attribute for a method}
- * @param methodSignature the signature
+ *
+ * @param methodSignature the method signature
*/
static SignatureAttribute of(MethodSignature methodSignature) {
return of(TemporaryConstantPool.INSTANCE.utf8Entry(methodSignature.signatureString()));
}
/**
- * {@return a {@code Signature} attribute}
- * @param signature the signature
+ * {@return a {@code Signature} attribute for a field or a record component}
+ *
+ * @param signature the Java type signature
*/
static SignatureAttribute of(Signature signature) {
return of(TemporaryConstantPool.INSTANCE.utf8Entry(signature.signatureString()));
@@ -107,7 +132,8 @@ static SignatureAttribute of(Signature signature) {
/**
* {@return a {@code Signature} attribute}
- * @param signature the signature
+ *
+ * @param signature the signature string
*/
static SignatureAttribute of(Utf8Entry signature) {
return new UnboundAttribute.UnboundSignatureAttribute(signature);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SourceDebugExtensionAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SourceDebugExtensionAttribute.java
index 0e6b7267263..9634ebe3011 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SourceDebugExtensionAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SourceDebugExtensionAttribute.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
@@ -25,23 +25,31 @@
package java.lang.classfile.attribute;
+import java.io.DataInput;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code SourceDebugExtension} attribute.
- * Delivered as a {@link java.lang.classfile.ClassElement} when traversing the elements of
- * a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#sourceDebugExtension() SourceDebugExtension}
+ * attribute (JVMS {@jvms 4.7.11}), which stores arbitrary {@linkplain
+ * DataInput##modified-utf-8 modified UTF-8} data.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has
+ * {@linkplain AttributeStability#STATELESS no data dependency}.
*
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Attributes#sourceDebugExtension()
+ * @jvms 4.7.11 The {@code SourceDebugExtension} Attribute
* @since 24
*/
public sealed interface SourceDebugExtensionAttribute
@@ -49,7 +57,8 @@ public sealed interface SourceDebugExtensionAttribute
permits BoundAttribute.BoundSourceDebugExtensionAttribute, UnboundAttribute.UnboundSourceDebugExtensionAttribute {
/**
- * {@return the debug extension payload}
+ * {@return the debug extension payload} The payload may denote a string
+ * longer than that which can be represented with a {@link String}.
*/
byte[] contents();
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.java
index 70f3d1e72ce..e2621d241fb 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.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
@@ -26,8 +26,11 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
-import java.lang.classfile.ClassModel;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.constantpool.Utf8Entry;
import jdk.internal.classfile.impl.BoundAttribute;
@@ -35,14 +38,19 @@
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code SourceFile} attribute (JVMS {@jvms 4.7.10}), which
- * can appear on classes. Delivered as a {@link java.lang.classfile.ClassElement}
- * when traversing a {@link ClassModel}.
+ * Models the {@link Attributes#sourceFile() SourceFile} attribute (JVMS {@jvms
+ * 4.7.10}), which indicates the name of the source file from which this {@code
+ * class} file was compiled.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a data
+ * dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
*
+ * @see Attributes#sourceFile()
+ * @jvms 4.7.10 The {@code SourceFile} Attribute
* @since 24
*/
public sealed interface SourceFileAttribute
@@ -56,6 +64,7 @@ public sealed interface SourceFileAttribute
/**
* {@return a source file attribute}
+ *
* @param sourceFile the source file name
*/
static SourceFileAttribute of(String sourceFile) {
@@ -64,6 +73,7 @@ static SourceFileAttribute of(String sourceFile) {
/**
* {@return a source file attribute}
+ *
* @param sourceFile the source file name
*/
static SourceFileAttribute of(Utf8Entry sourceFile) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SourceIDAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SourceIDAttribute.java
index 71fd9d5b059..b7d2e3cf9b7 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SourceIDAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SourceIDAttribute.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
@@ -26,8 +26,10 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
import java.lang.classfile.ClassElement;
-import java.lang.classfile.ClassModel;
import java.lang.classfile.constantpool.Utf8Entry;
import jdk.internal.classfile.impl.BoundAttribute;
@@ -35,14 +37,21 @@
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code SourceID} attribute, which can
- * appear on classes. Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing a {@link ClassModel}.
+ * Models the {@link Attributes#sourceId() SourceID} attribute, which records
+ * the last modified time of the source file from which this {@code class} file
+ * was compiled.
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class. It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ *
+ * This attribute is not predefined in the Java SE Platform. This is a
+ * JDK-specific nonstandard attribute produced by the reference implementation
+ * of the system Java compiler, defined by the {@code jdk.compiler} module.
*
+ * @see Attributes#sourceId()
+ * @see CompilationIDAttribute
+ * @see CharacterRangeTableAttribute
* @since 24
*/
public sealed interface SourceIDAttribute
@@ -51,13 +60,14 @@ public sealed interface SourceIDAttribute
/**
* {@return the source id} The source id is the last modified time of the
- * source file (as reported by the filesystem, in milliseconds) when the
- * classfile is compiled.
+ * source file (as reported by the file system, in milliseconds) when this
+ * {@code class} file is compiled.
*/
Utf8Entry sourceId();
/**
* {@return a {@code SourceID} attribute}
+ *
* @param sourceId the source id
*/
static SourceIDAttribute of(Utf8Entry sourceId) {
@@ -66,6 +76,7 @@ static SourceIDAttribute of(Utf8Entry sourceId) {
/**
* {@return a {@code SourceID} attribute}
+ *
* @param sourceId the source id
*/
static SourceIDAttribute of(String sourceId) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java
index 920db8ac9d7..71d5ccc79a4 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
+ * 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
@@ -25,8 +25,11 @@
package java.lang.classfile.attribute;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.Label;
+import java.lang.classfile.Opcode;
import java.lang.classfile.constantpool.ClassEntry;
+import java.lang.classfile.instruction.BranchInstruction;
import java.lang.constant.ClassDesc;
import java.util.List;
@@ -34,15 +37,28 @@
import jdk.internal.classfile.impl.TemporaryConstantPool;
/**
- * Models stack map frame of {@code StackMapTable} attribute (JVMS {@jvms 4.7.4}).
+ * Models a stack map frame in a {@link StackMapTableAttribute StackMapTable}
+ * attribute (JVMS {@jvms 4.7.4}). A stack map frame must appear at the
+ * beginning of each basic block in a method (JVMS {@jvms 4.10.1}).
*
+ * @apiNote
+ * In general, a stack map frame should be defined for each target of a
+ * {@link BranchInstruction}, or unreachable code right after an unconditional
+ * branch instruction like {@link Opcode#GOTO goto}. The automatic stack map
+ * generation cannot handle unreachable code right after an unconditional jump;
+ * The {@link ClassFile.DeadCodeOption} allows substituting such code, or
+ * advanced users can provide their own stack maps for dead code.
+ *
+ * @see StackMapTableAttribute#entries()
+ * @jvms 4.7.4 The {@code StackMapTable} Attribute
+ * @jvms 4.10.1 Verification by Type Checking
* @since 24
*/
public sealed interface StackMapFrameInfo
permits StackMapDecoder.StackMapFrameImpl {
/**
- * {@return the frame compact form type}
+ * {@return the raw {@code u1 frame_type}}
*/
int frameType();
@@ -57,12 +73,13 @@ public sealed interface StackMapFrameInfo
List locals();
/**
- * {@return the expanded stack types}
+ * {@return the expanded operand stack types}
*/
List stack();
/**
* {@return a new stack map frame}
+ *
* @param target the location of the frame
* @param locals the complete list of frame locals
* @param stack the complete frame stack
@@ -70,13 +87,15 @@ public sealed interface StackMapFrameInfo
public static StackMapFrameInfo of(Label target,
List locals,
List stack) {
-
return new StackMapDecoder.StackMapFrameImpl(255, target, locals, stack);
}
/**
- * The type of a stack value.
+ * The type of a stack or local variable value.
*
+ * @see #locals()
+ * @see #stack()
+ * @jvms 4.7.4 The {@code StackMapTable} Attribute
* @since 24
*/
sealed interface VerificationTypeInfo {
@@ -125,25 +144,25 @@ sealed interface VerificationTypeInfo {
*/
public enum SimpleVerificationTypeInfo implements VerificationTypeInfo {
- /** verification type top */
+ /** Verification type top. */
TOP(ITEM_TOP),
- /** verification type int */
+ /** Verification type int. */
INTEGER(ITEM_INTEGER),
- /** verification type float */
+ /** Verification type float. */
FLOAT(ITEM_FLOAT),
- /** verification type double */
+ /** Verification type double. */
DOUBLE(ITEM_DOUBLE),
- /** verification type long */
+ /** Verification type long. */
LONG(ITEM_LONG),
- /** verification type null */
+ /** Verification type null. */
NULL(ITEM_NULL),
- /** verification type uninitializedThis */
+ /** Verification type uninitializedThis. */
UNINITIALIZED_THIS(ITEM_UNINITIALIZED_THIS);
@@ -162,6 +181,7 @@ public int tag() {
/**
* A stack value for an object type. Its {@link #tag() tag} is {@value #ITEM_OBJECT}.
*
+ * @jvms 4.7.4 The {@code StackMapTable} Attribute
* @since 24
*/
sealed interface ObjectVerificationTypeInfo extends VerificationTypeInfo
@@ -190,7 +210,7 @@ public static ObjectVerificationTypeInfo of(ClassDesc classDesc) {
ClassEntry className();
/**
- * {@return the class of the object}
+ * {@return the class of the object, as a symbolic descriptor}
*/
default ClassDesc classSymbol() {
return className().asSymbol();
@@ -200,19 +220,22 @@ default ClassDesc classSymbol() {
/**
* An uninitialized stack value. Its {@link #tag() tag} is {@value #ITEM_UNINITIALIZED}.
*
+ * @jvms 4.7.4 The {@code StackMapTable} Attribute
* @since 24
*/
sealed interface UninitializedVerificationTypeInfo extends VerificationTypeInfo
permits StackMapDecoder.UninitializedVerificationTypeInfoImpl {
/**
- * {@return the {@code new} instruction position that creates this unitialized object}
+ * {@return the label immediately before the {@link Opcode#NEW new}
+ * instruction that creates this uninitialized object}
*/
Label newTarget();
/**
- * {@return an unitialized verification type info}
- * @param newTarget the {@code new} instruction position that creates this unitialized object
+ * {@return an uninitialized verification type info}
+ * @param newTarget the label immediately before the {@link Opcode#NEW new}
+ * instruction that creates this uninitialized object
*/
public static UninitializedVerificationTypeInfo of(Label newTarget) {
return new StackMapDecoder.UninitializedVerificationTypeInfoImpl(newTarget);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.java
index 0d577fb6cd5..e9b3acbff5b 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.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
@@ -26,22 +26,40 @@
package java.lang.classfile.attribute;
import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
import java.lang.classfile.CodeElement;
+import java.lang.classfile.instruction.DiscontinuedInstruction;
import java.util.List;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code StackMapTable} attribute (JVMS {@jvms 4.7.4}), which can appear
- * on a {@code Code} attribute.
+ * Models the {@link Attributes#stackMapTable() StackMapTable} attribute (JVMS
+ * {@jvms 4.7.4}), which is used for verification by type checking ({@jvms
+ * 4.10.1}).
*
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute is not delivered in the traversal of a {@link CodeAttribute},
+ * but instead automatically generated upon {@code class} file writing.
+ * Advanced users can supply their own stack maps according to the {@link
+ * ClassFile.StackMapsOption}.
*
- * The attribute was introduced in the Java SE Platform version 6.
+ * This attribute only appears on {@code Code} attributes, and does not permit
+ * {@linkplain AttributeMapper#allowMultiple multiple instances} in a {@code
+ * Code} attribute. It has a data dependency on {@linkplain
+ * AttributeStability#LABELS labels} in the {@code code} array.
+ *
+ * This attribute was introduced in the Java SE Platform version 6, major
+ * version {@value ClassFile#JAVA_6_VERSION}.
*
+ * @see Attributes#stackMapTable()
+ * @see DiscontinuedInstruction.JsrInstruction
+ * @see DiscontinuedInstruction.RetInstruction
+ * @jvms 4.7.4 The {@code StackMapTable} Attribute
+ * @jvms 4.10.1 Verification by Type Checking
* @since 24
*/
public sealed interface StackMapTableAttribute
@@ -55,6 +73,7 @@ public sealed interface StackMapTableAttribute
/**
* {@return a stack map table attribute}
+ *
* @param entries the stack map frames
*/
public static StackMapTableAttribute of(List entries) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java
index 1e6b706ec08..6a38e4c34d6 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.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
@@ -25,24 +25,37 @@
package java.lang.classfile.attribute;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AccessFlag;
import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
- * Models the {@code Synthetic} attribute (JVMS {@jvms 4.7.8}), which can appear on
- * classes, methods, and fields. Delivered as a {@link ClassElement},
- * {@link MethodElement}, or {@link FieldElement} when traversing the elements
- * of a corresponding model.
+ * Models the {@link Attributes#synthetic() Synthetic} attribute (JVMS {@jvms
+ * 4.7.8}), which marks a class member as implementation-specific artifacts.
*
- * The attribute permits multiple instances in a given location.
+ * This attribute can appear on classes, methods, and fields, and permits
+ * {@linkplain AttributeMapper#allowMultiple multiple instances} in a structure.
+ * It has {@linkplain AttributeStability#STATELESS no data dependency}.
+ *
+ * This attribute was introduced in the Java SE Platform version 1.1, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * This attribute has been largely superseded by the {@link AccessFlag#SYNTHETIC
+ * ACC_SYNTHETIC} modifier in newer {@code class} files. See {@link
+ * java.compiler/javax.lang.model.util.Elements.Origin} for a more in-depth
+ * description about the differences between synthetic and implicit (mandated)
+ * constructs generated by compilers.
*
+ * @see Attributes#synthetic()
+ * @see AccessFlag#SYNTHETIC
+ * @jvms 4.7.8 The {@code Synthetic} Attribute
* @since 24
*/
+@SuppressWarnings("doclint:reference")
public sealed interface SyntheticAttribute
extends Attribute,
ClassElement, MethodElement, FieldElement
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/UnknownAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/UnknownAttribute.java
index ad47f35a856..c35942bc42c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/UnknownAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/UnknownAttribute.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
@@ -25,16 +25,22 @@
package java.lang.classfile.attribute;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
import jdk.internal.classfile.impl.BoundAttribute;
/**
- * Models an unknown attribute on a class, method, or field.
+ * Models an unknown attribute read from a {@code class} file. An attribute is
+ * unknown if it is not recognized by one of the mappers in {@link Attributes}
+ * and is not recognized by the {@link ClassFile.AttributesProcessingOption}.
+ *
+ * This attribute is not delivered in the traversal of a {@link CodeModel}.
+ *
+ * An unknown attribute may appear anywhere where an attribute may appear, and
+ * has an {@linkplain AttributeStability#UNKNOWN unknown} data dependency.
*
+ * @see CustomAttribute
* @since 24
*/
public sealed interface UnknownAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/package-info.java b/src/java.base/share/classes/java/lang/classfile/attribute/package-info.java
index 08bd28cbc58..1ddd0511d85 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/package-info.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/package-info.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
+ * 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
@@ -24,11 +24,79 @@
*/
/**
- *
Provides interfaces describing classfile attributes for the {@link java.lang.classfile} library.
+ * Provides interfaces describing {@code class} file attributes for the {@link java.lang.classfile} library.
*
- * The {@code java.lang.classfile.attribute} package contains interfaces describing classfile attributes.
+ * 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;
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/snippet-files/PackageSnippets.java b/src/java.base/share/classes/java/lang/classfile/attribute/snippet-files/PackageSnippets.java
new file mode 100644
index 00000000000..452f39f56db
--- /dev/null
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/snippet-files/PackageSnippets.java
@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 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.
+ */
+package java.lang.classfile.attribute.snippet;
+
+import java.lang.classfile.AttributedElement;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.MethodModel;
+import java.lang.classfile.attribute.RuntimeVisibleAnnotationsAttribute;
+import java.util.List;
+
+class PackageSnippets {
+
+ // @start region=hasDeprecated
+ 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;
+ }
+ // @end
+
+ // @start region=reuseStackMaps
+ static void reuseStackMaps(MethodModel oldMethod, CodeBuilder cob) {
+ var oldCode = oldMethod.code().orElseThrow();
+ // The StackMapTable attribute is not streamed in CodeModel, so this is
+ // the only way to obtain it
+ // @link substring="findAttribute" target="AttributedElement#findAttribute" :
+ var stackMaps = oldCode.findAttribute(Attributes.stackMapTable());
+ stackMaps.ifPresent(cob); // Note: CodeBuilder is a Consumer
+ }
+ // @end
+}
diff --git a/src/java.base/share/classes/java/lang/classfile/constantpool/DoubleEntry.java b/src/java.base/share/classes/java/lang/classfile/constantpool/DoubleEntry.java
index bc6956b5bf5..f41dde8c966 100644
--- a/src/java.base/share/classes/java/lang/classfile/constantpool/DoubleEntry.java
+++ b/src/java.base/share/classes/java/lang/classfile/constantpool/DoubleEntry.java
@@ -34,8 +34,8 @@
*
* The use of a {@code DoubleEntry} is modeled by a {@code double}. Conversions
* are through {@link ConstantPoolBuilder#doubleEntry} and {@link #doubleValue()}.
- * In the conversions, all NaN values of the {@code double} may be collapsed
- * into a single {@linkplain Double#NaN "canonical" NaN value}.
+ * In the conversions, all NaN values of the {@code double} may or may not be
+ * collapsed into a single {@linkplain Double#NaN "canonical" NaN value}.
*
* A double entry has a {@linkplain #width() width} of {@code 2}, making its
* subsequent constant pool index valid and unusable.
diff --git a/src/java.base/share/classes/java/lang/classfile/constantpool/FloatEntry.java b/src/java.base/share/classes/java/lang/classfile/constantpool/FloatEntry.java
index 2ccf3fb94e4..add8707ce82 100644
--- a/src/java.base/share/classes/java/lang/classfile/constantpool/FloatEntry.java
+++ b/src/java.base/share/classes/java/lang/classfile/constantpool/FloatEntry.java
@@ -34,8 +34,8 @@
*
* The use of a {@code FloatEntry} is modeled by a {@code float}. Conversions
* are through {@link ConstantPoolBuilder#floatEntry} and {@link #floatValue()}.
- * In the conversions, all NaN values of the {@code float} may be collapsed into
- * a single {@linkplain Float#NaN "canonical" NaN value}.
+ * In the conversions, all NaN values of the {@code float} may or may not be
+ * collapsed into a single {@linkplain Float#NaN "canonical" NaN value}.
*
* @see ConstantPoolBuilder#floatEntry ConstantPoolBuilder::floatEntry
* @jvms 4.4.4 The {@code CONSTANT_Integer_info} and {@code CONSTANT_Float_info}
diff --git a/src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java b/src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java
index 4170e142ffe..906aaea421d 100644
--- a/src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java
+++ b/src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
+ * 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
@@ -25,6 +25,7 @@
package java.lang.classfile.instruction;
import java.lang.classfile.*;
+import java.lang.classfile.attribute.StackMapTableAttribute;
import jdk.internal.classfile.impl.AbstractInstruction;
import jdk.internal.classfile.impl.BytecodeHelpers;
@@ -71,7 +72,13 @@ public sealed interface DiscontinuedInstruction extends Instruction {
* astore} series of instructions can then store this value to a local
* variable slot.
*
+ * @apiNote
+ * Jump subroutine instructions are discontinued to enforce verification by
+ * type checking (JVMS {@jvms 4.10.1}) using the {@link StackMapTableAttribute
+ * StackMapTable} attribute.
+ *
* @see Opcode.Kind#DISCONTINUED_JSR
+ * @see StackMapTableAttribute
* @since 24
*/
sealed interface JsrInstruction extends DiscontinuedInstruction
@@ -130,8 +137,14 @@ static JsrInstruction of(Label target) {
* TypeKind##returnAddress returnAddress} value to a local variable slot,
* making the slot usable by a return from subroutine instruction.
*
+ * @apiNote
+ * Return from subroutine instructions are discontinued to enforce
+ * verification by type checking (JVMS {@jvms 4.10.1}) using the {@link
+ * StackMapTableAttribute StackMapTable} attribute.
+ *
* @jvms 6.5.ret ret
* @see Opcode.Kind#DISCONTINUED_RET
+ * @see StackMapTableAttribute
* @since 24
*/
sealed interface RetInstruction extends DiscontinuedInstruction
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_de.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_de.java
index a6f8370a2d7..bcdb0f59f5c 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_de.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_de.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2017, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
*/
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
@@ -31,7 +31,7 @@
* Array. You also need to update MAX_CODE for error strings
* and MAX_WARNING for warnings ( Needed for only information
* purpose )
- * @LastModified: May 2022
+ * @LastModified: Dec 2024
*/
public class XSLTErrorResources_de extends ListResourceBundle
{
@@ -1197,7 +1197,7 @@ public Object[][] getContents()
"Das Feature \"{0}\" kann nicht f\u00FCr diese TransformerFactory festgelegt werden."},
{ ER_EXTENSION_ELEMENT_NOT_ALLOWED_IN_SECURE_PROCESSING,
- "Verwendung des Erweiterungselements \"{0}\" ist nicht zul\u00E4ssig, wenn das Feature f\u00FCr die sichere Verarbeitung auf \"true\" gesetzt ist."},
+ "Verwendung der Erweiterungsfunktion \"{0}\" ist nicht zul\u00E4ssig, wenn die Erweiterungsfunktionen vom Feature f\u00FCr die sichere Verarbeitung oder der Eigenschaft \"jdk.xml.enableExtensionFunctions\" deaktiviert wurden. Setzen Sie \"jdk.xml.enableExtensionFunctions\" auf \"true\", um die Erweiterungsfunktionen zu aktivieren."},
{ ER_NAMESPACE_CONTEXT_NULL_NAMESPACE,
"Pr\u00E4fix f\u00FCr Null-Namespace-URI kann nicht abgerufen werden."},
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_ja.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_ja.java
index cf8a0f2563b..8555d69597b 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_ja.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_ja.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2017, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
*/
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
@@ -31,7 +31,7 @@
* Array. You also need to update MAX_CODE for error strings
* and MAX_WARNING for warnings ( Needed for only information
* purpose )
- * @LastModified: May 2022
+ * @LastModified: Dec 2024
*/
public class XSLTErrorResources_ja extends ListResourceBundle
{
@@ -1197,7 +1197,7 @@ public Object[][] getContents()
"\u6A5F\u80FD''{0}''\u3092\u3053\u306ETransformerFactory\u306B\u8A2D\u5B9A\u3067\u304D\u307E\u305B\u3093\u3002"},
{ ER_EXTENSION_ELEMENT_NOT_ALLOWED_IN_SECURE_PROCESSING,
- "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u304Ctrue\u306B\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u8981\u7D20''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002"},
+ "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u307E\u305F\u306F\u30D7\u30ED\u30D1\u30C6\u30A3''jdk.xml.enableExtensionFunctions''\u306B\u3088\u3063\u3066\u62E1\u5F35\u95A2\u6570\u304C\u7121\u52B9\u306B\u306A\u3063\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u95A2\u6570''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002\u62E1\u5F35\u95A2\u6570\u3092\u6709\u52B9\u306B\u3059\u308B\u306B\u306F\u3001''jdk.xml.enableExtensionFunctions''\u3092''true''\u306B\u8A2D\u5B9A\u3057\u307E\u3059\u3002"},
{ ER_NAMESPACE_CONTEXT_NULL_NAMESPACE,
"null\u306E\u30CD\u30FC\u30E0\u30B9\u30DA\u30FC\u30B9URI\u306B\u3064\u3044\u3066\u63A5\u982D\u8F9E\u3092\u53D6\u5F97\u3067\u304D\u307E\u305B\u3093\u3002"},
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_zh_CN.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_zh_CN.java
index dc7ecef28f8..c5ae6af08c0 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_zh_CN.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_zh_CN.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2017, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
*/
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
@@ -31,7 +31,7 @@
* Array. You also need to update MAX_CODE for error strings
* and MAX_WARNING for warnings ( Needed for only information
* purpose )
- * @LastModified: May 2022
+ * @LastModified: Dec 2024
*/
public class XSLTErrorResources_zh_CN extends ListResourceBundle
{
@@ -1197,7 +1197,7 @@ public Object[][] getContents()
"\u65E0\u6CD5\u5BF9\u6B64 TransformerFactory \u8BBE\u7F6E\u529F\u80FD ''{0}''\u3002"},
{ ER_EXTENSION_ELEMENT_NOT_ALLOWED_IN_SECURE_PROCESSING,
- "\u5F53\u5B89\u5168\u5904\u7406\u529F\u80FD\u8BBE\u7F6E\u4E3A\u201C\u771F\u201D\u65F6, \u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u5143\u7D20 ''{0}''\u3002"},
+ "\u5F53\u6269\u5C55\u51FD\u6570\u88AB\u5B89\u5168\u5904\u7406\u529F\u80FD\u6216\u5C5E\u6027 ''jdk.xml.enableExtensionFunctions'' \u7981\u7528\u65F6\uFF0C\u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u51FD\u6570 ''{0}''\u3002\u8981\u542F\u7528\u6269\u5C55\u51FD\u6570\uFF0C\u8BF7\u5C06 ''jdk.xml.enableExtensionFunctions'' \u8BBE\u7F6E\u4E3A ''true''\u3002"},
{ ER_NAMESPACE_CONTEXT_NULL_NAMESPACE,
"\u65E0\u6CD5\u83B7\u53D6\u7A7A\u540D\u79F0\u7A7A\u95F4 uri \u7684\u524D\u7F00\u3002"},
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_de.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_de.java
index 12ec243bbc9..c16620ec7b1 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_de.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_de.java
@@ -24,7 +24,7 @@
/**
* @author Morten Jorgensen
- * @LastModified: Nov 2024
+ * @LastModified: Dec 2024
*/
public class ErrorMessages_de extends ListResourceBundle {
@@ -548,6 +548,12 @@ public Object[][] getContents()
{ErrorMsg.DATA_CONVERSION_ERR,
"Datentyp \"{0}\" kann nicht in \"{1}\" konvertiert werden."},
+ /*
+ * Note to translators: property name "jdk.xml.enableExtensionFunctions"
+ * and value "true" should not be translated.
+ */
+ {ErrorMsg.UNSUPPORTED_EXT_FUNC_ERR,
+ "Verwendung der Erweiterungsfunktion \"{0}\" ist nicht zul\u00E4ssig, wenn die Erweiterungsfunktionen vom Feature f\u00FCr die sichere Verarbeitung oder der Eigenschaft \"jdk.xml.enableExtensionFunctions\" deaktiviert wurden. Setzen Sie \"jdk.xml.enableExtensionFunctions\" auf \"true\", um die Erweiterungsfunktionen zu aktivieren."},
/*
* Note to translators: "Templates" is a Java class name that should
* not be translated.
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_ja.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_ja.java
index 5e03673aef5..48f7d63f353 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_ja.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_ja.java
@@ -24,7 +24,7 @@
/**
* @author Morten Jorgensen
- * @LastModified: Nov 2024
+ * @LastModified: Dec 2024
*/
public class ErrorMessages_ja extends ListResourceBundle {
@@ -548,6 +548,12 @@ public Object[][] getContents()
{ErrorMsg.DATA_CONVERSION_ERR,
"\u30C7\u30FC\u30BF\u578B''{0}''\u3092''{1}''\u306B\u5909\u63DB\u3067\u304D\u307E\u305B\u3093\u3002"},
+ /*
+ * Note to translators: property name "jdk.xml.enableExtensionFunctions"
+ * and value "true" should not be translated.
+ */
+ {ErrorMsg.UNSUPPORTED_EXT_FUNC_ERR,
+ "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u307E\u305F\u306F\u30D7\u30ED\u30D1\u30C6\u30A3''jdk.xml.enableExtensionFunctions''\u306B\u3088\u3063\u3066\u62E1\u5F35\u95A2\u6570\u304C\u7121\u52B9\u306B\u306A\u3063\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u95A2\u6570''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002\u62E1\u5F35\u95A2\u6570\u3092\u6709\u52B9\u306B\u3059\u308B\u306B\u306F\u3001''jdk.xml.enableExtensionFunctions''\u3092''true''\u306B\u8A2D\u5B9A\u3057\u307E\u3059\u3002"},
/*
* Note to translators: "Templates" is a Java class name that should
* not be translated.
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_zh_CN.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_zh_CN.java
index 728abc0df37..0affded17e3 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_zh_CN.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_zh_CN.java
@@ -24,7 +24,7 @@
/**
* @author Morten Jorgensen
- * @LastModified: Nov 2024
+ * @LastModified: Dec 2024
*/
public class ErrorMessages_zh_CN extends ListResourceBundle {
@@ -548,6 +548,12 @@ public Object[][] getContents()
{ErrorMsg.DATA_CONVERSION_ERR,
"\u65E0\u6CD5\u5C06\u6570\u636E\u7C7B\u578B ''{0}'' \u8F6C\u6362\u4E3A ''{1}''\u3002"},
+ /*
+ * Note to translators: property name "jdk.xml.enableExtensionFunctions"
+ * and value "true" should not be translated.
+ */
+ {ErrorMsg.UNSUPPORTED_EXT_FUNC_ERR,
+ "\u5F53\u6269\u5C55\u51FD\u6570\u88AB\u5B89\u5168\u5904\u7406\u529F\u80FD\u6216\u5C5E\u6027 ''jdk.xml.enableExtensionFunctions'' \u7981\u7528\u65F6\uFF0C\u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u51FD\u6570 ''{0}''\u3002\u8981\u542F\u7528\u6269\u5C55\u51FD\u6570\uFF0C\u8BF7\u5C06 ''jdk.xml.enableExtensionFunctions'' \u8BBE\u7F6E\u4E3A ''true''\u3002"},
/*
* Note to translators: "Templates" is a Java class name that should
* not be translated.
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_de.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_de.java
index dadea4ba3b0..c93e05d74e4 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_de.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_de.java
@@ -1,6 +1,5 @@
/*
- * reserved comment block
- * DO NOT REMOVE OR ALTER!
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
*/
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,6 +24,7 @@
/**
* @author Morten Jorgensen
+ * @LastModified: Dec 2024
*/
public class ErrorMessages_de extends ListResourceBundle {
@@ -275,10 +275,10 @@ public Object[][] getContents()
"Ein Attribut, dessen Wert ein NCName sein muss, hatte den Wert \"{0}\""},
{BasisLibrary.UNALLOWED_EXTENSION_FUNCTION_ERR,
- "Verwendung der Erweiterungsfunktion \"{0}\" ist nicht zul\u00E4ssig, wenn das Feature f\u00FCr die sichere Verarbeitung auf \"true\" gesetzt ist."},
+ "Verwendung der Erweiterungsfunktion \"{0}\" ist nicht zul\u00E4ssig, wenn die Erweiterungsfunktionen vom Feature f\u00FCr die sichere Verarbeitung oder der Eigenschaft \"jdk.xml.enableExtensionFunctions\" deaktiviert wurden. Setzen Sie \"jdk.xml.enableExtensionFunctions\" auf \"true\", um die Erweiterungsfunktionen zu aktivieren."},
{BasisLibrary.UNALLOWED_EXTENSION_ELEMENT_ERR,
- "Verwendung des Erweiterungselements \"{0}\" ist nicht zul\u00E4ssig, wenn das Feature f\u00FCr die sichere Verarbeitung auf \"true\" gesetzt ist."},
+ "Verwendung des Erweiterungselements \"{0}\" ist nicht zul\u00E4ssig, wenn die Erweiterungsfunktionen vom Feature f\u00FCr die sichere Verarbeitung oder der Eigenschaft \"jdk.xml.enableExtensionFunctions\" deaktiviert wurden. Setzen Sie \"jdk.xml.enableExtensionFunctions\" auf \"true\", um die Erweiterungsfunktionen zu aktivieren."},
};
}
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_ja.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_ja.java
index 8108e8f7218..941c1c38c00 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_ja.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_ja.java
@@ -1,6 +1,5 @@
/*
- * reserved comment block
- * DO NOT REMOVE OR ALTER!
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
*/
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,6 +24,7 @@
/**
* @author Morten Jorgensen
+ * @LastModified: Dec 2024
*/
public class ErrorMessages_ja extends ListResourceBundle {
@@ -275,10 +275,10 @@ public Object[][] getContents()
"\u5024\u304CNCName\u3067\u3042\u308B\u3053\u3068\u304C\u5FC5\u8981\u306A\u5C5E\u6027\u306E\u5024\u304C''{0}''\u3067\u3057\u305F"},
{BasisLibrary.UNALLOWED_EXTENSION_FUNCTION_ERR,
- "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u304Ctrue\u306B\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u95A2\u6570''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002"},
+ "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u307E\u305F\u306F\u30D7\u30ED\u30D1\u30C6\u30A3''jdk.xml.enableExtensionFunctions''\u306B\u3088\u3063\u3066\u62E1\u5F35\u95A2\u6570\u304C\u7121\u52B9\u306B\u306A\u3063\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u95A2\u6570''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002\u62E1\u5F35\u95A2\u6570\u3092\u6709\u52B9\u306B\u3059\u308B\u306B\u306F\u3001''jdk.xml.enableExtensionFunctions''\u3092''true''\u306B\u8A2D\u5B9A\u3057\u307E\u3059\u3002"},
{BasisLibrary.UNALLOWED_EXTENSION_ELEMENT_ERR,
- "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u304Ctrue\u306B\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u8981\u7D20''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002"},
+ "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u307E\u305F\u306F\u30D7\u30ED\u30D1\u30C6\u30A3''jdk.xml.enableExtensionFunctions''\u306B\u3088\u3063\u3066\u62E1\u5F35\u95A2\u6570\u304C\u7121\u52B9\u306B\u306A\u3063\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u8981\u7D20''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002\u62E1\u5F35\u95A2\u6570\u3092\u6709\u52B9\u306B\u3059\u308B\u306B\u306F\u3001''jdk.xml.enableExtensionFunctions''\u3092''true''\u306B\u8A2D\u5B9A\u3057\u307E\u3059\u3002"},
};
}
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_zh_CN.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_zh_CN.java
index 076b06d50db..55484c2b10c 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_zh_CN.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_zh_CN.java
@@ -1,6 +1,5 @@
/*
- * reserved comment block
- * DO NOT REMOVE OR ALTER!
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
*/
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,6 +24,7 @@
/**
* @author Morten Jorgensen
+ * @LastModified: Dec 2024
*/
public class ErrorMessages_zh_CN extends ListResourceBundle {
@@ -275,10 +275,10 @@ public Object[][] getContents()
"\u5176\u503C\u5FC5\u987B\u4E3A NCName \u7684\u5C5E\u6027\u5177\u6709\u503C ''{0}''"},
{BasisLibrary.UNALLOWED_EXTENSION_FUNCTION_ERR,
- "\u5F53\u5B89\u5168\u5904\u7406\u529F\u80FD\u8BBE\u7F6E\u4E3A\u201C\u771F\u201D\u65F6, \u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u51FD\u6570 ''{0}''\u3002"},
+ "\u5F53\u6269\u5C55\u51FD\u6570\u88AB\u5B89\u5168\u5904\u7406\u529F\u80FD\u6216\u5C5E\u6027 ''jdk.xml.enableExtensionFunctions'' \u7981\u7528\u65F6\uFF0C\u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u51FD\u6570 ''{0}''\u3002\u8981\u542F\u7528\u6269\u5C55\u51FD\u6570\uFF0C\u8BF7\u5C06 ''jdk.xml.enableExtensionFunctions'' \u8BBE\u7F6E\u4E3A ''true''\u3002"},
{BasisLibrary.UNALLOWED_EXTENSION_ELEMENT_ERR,
- "\u5F53\u5B89\u5168\u5904\u7406\u529F\u80FD\u8BBE\u7F6E\u4E3A\u201C\u771F\u201D\u65F6, \u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u5143\u7D20 ''{0}''\u3002"},
+ "\u5F53\u6269\u5C55\u51FD\u6570\u88AB\u5B89\u5168\u5904\u7406\u529F\u80FD\u6216\u5C5E\u6027 ''jdk.xml.enableExtensionFunctions'' \u7981\u7528\u65F6\uFF0C\u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u5143\u7D20 ''{0}''\u3002\u8981\u542F\u7528\u6269\u5C55\u51FD\u6570\uFF0C\u8BF7\u5C06 ''jdk.xml.enableExtensionFunctions'' \u8BBE\u7F6E\u4E3A ''true''\u3002"},
};
}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties
index 130a644da94..8761d334157 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties
@@ -839,8 +839,6 @@ compiler.misc.user.selected.completion.failure=Von Benutzer ausgewählter Abschl
# 0: collection of string
compiler.err.proc.no.explicit.annotation.processing.requested=Klassennamen "{0}" werden nur akzeptiert, wenn die Annotationsverarbeitung explizit angefordert wird
-compiler.err.proc.no.service=ServiceLoader konnte nicht verwendet werden und ist für Annotationsverarbeitung erforderlich.
-
# 0: string, 1: string
compiler.err.proc.processor.bad.option.name=Ungültiger Optionsname "{0}" von Prozessor "{1}" angegeben
@@ -2300,7 +2298,7 @@ compiler.misc.feature.flexible.constructors=Flexible Konstruktoren
compiler.misc.feature.module.imports=Modulimporte
# L10N: do not localize: transitive
-compiler.misc.feature.java.base.transitive=transitive Modifikator für java.base
+compiler.misc.feature.java.base.transitive=Modifikator "transitive" für java.base
compiler.warn.underscore.as.identifier=Ab Release 9 ist "_" ein Schlüsselwort und kann nicht als ID verwendet werden
@@ -2668,7 +2666,7 @@ compiler.misc.locn.module_path=Anwendungsmodulpfad
compiler.misc.cant.resolve.modules=Module können nicht aufgelöst werden
-compiler.misc.bad.requires.flag=Ungültiges requires-Kennzeichen: {0}
+compiler.misc.bad.requires.flag=Ungültiges Kennzeichen für "requires java.base": {0}
# 0: string
compiler.err.invalid.module.specifier=Modulbezeichner nicht zulässig: {0}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_ja.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_ja.properties
index 2c108edf692..9ab2862407f 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_ja.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_ja.properties
@@ -839,8 +839,6 @@ compiler.misc.user.selected.completion.failure=クラス名によるユーザー
# 0: collection of string
compiler.err.proc.no.explicit.annotation.processing.requested=クラス名''{0}''が受け入れられるのは、注釈処理が明示的にリクエストされた場合のみです
-compiler.err.proc.no.service=サービス・ローダーが使用できませんでしたが、注釈処理に必要です。
-
# 0: string, 1: string
compiler.err.proc.processor.bad.option.name=プロセッサ''{1}''によって指定されたオプション名''{0}''が不正です
@@ -2300,7 +2298,7 @@ compiler.misc.feature.flexible.constructors=柔軟なコンストラクタ
compiler.misc.feature.module.imports=モジュール・インポート
# L10N: do not localize: transitive
-compiler.misc.feature.java.base.transitive=java.baseの推移的修飾子
+compiler.misc.feature.java.base.transitive=java.baseのtransitive 修飾子
compiler.warn.underscore.as.identifier=リリース9から''_''はキーワードなので識別子として使用することはできません
@@ -2668,7 +2666,7 @@ compiler.misc.locn.module_path=アプリケーション・モジュール・パ
compiler.misc.cant.resolve.modules=モジュールを解決できません
-compiler.misc.bad.requires.flag=不正な必須フラグ: {0}
+compiler.misc.bad.requires.flag="requires java.base"のフラグが無効です: {0}
# 0: string
compiler.err.invalid.module.specifier=モジュール指定子は許可されません: {0}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_zh_CN.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_zh_CN.properties
index c841c3715fc..52a6ec23e51 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_zh_CN.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_zh_CN.properties
@@ -839,8 +839,6 @@ compiler.misc.user.selected.completion.failure=按类名列出的用户选择输
# 0: collection of string
compiler.err.proc.no.explicit.annotation.processing.requested=仅当显式请求批注处理时才接受类名称 ''{0}''
-compiler.err.proc.no.service=ServiceLoader 不可用, 但它是批注处理所必需的。
-
# 0: string, 1: string
compiler.err.proc.processor.bad.option.name=处理程序 ''{1}'' 提供的选项名称 ''{0}'' 错误
@@ -2300,7 +2298,7 @@ compiler.misc.feature.flexible.constructors=灵活构造器
compiler.misc.feature.module.imports=模块导入
# L10N: do not localize: transitive
-compiler.misc.feature.java.base.transitive=java.base 的过渡修饰符
+compiler.misc.feature.java.base.transitive=java.base 的 transitive 修饰符
compiler.warn.underscore.as.identifier=从发行版 9 开始, ''_'' 为关键字, 不能用作标识符
@@ -2668,7 +2666,7 @@ compiler.misc.locn.module_path=应用程序模块路径
compiler.misc.cant.resolve.modules=无法解析模块
-compiler.misc.bad.requires.flag=错误的请求标记：{0}
+compiler.misc.bad.requires.flag="requires java.base" 的标记无效：{0}
# 0: string
compiler.err.invalid.module.specifier=不允许模块说明符: {0}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_de.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_de.properties
index efcc594ca6c..0c67a60aa0a 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_de.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_de.properties
@@ -82,8 +82,6 @@ launcher.error=Fehler:\u0020
launcher.err.no.args=kein Pfad für Quelldatei
-launcher.err.security.manager=Quellcode-Launcher kann nicht mit aktiviertem Sicherheitsmanager verwendet werden
-
# 0: string
launcher.err.invalid.filename=ungültiger Pfad für Quelldatei: {0}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_ja.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_ja.properties
index 72e2478bff3..ef4d0f1f9e0 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_ja.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_ja.properties
@@ -82,8 +82,6 @@ launcher.error=エラー:\u0020
launcher.err.no.args=ソース・ファイルのパスがありません
-launcher.err.security.manager=セキュリティ・マネージャが有効な状態でソースコード・ランチャを使用することはできません
-
# 0: string
launcher.err.invalid.filename=ソース・ファイルの無効なパス: {0}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_zh_CN.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_zh_CN.properties
index 9382ac9e348..a442cfe1e68 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_zh_CN.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_zh_CN.properties
@@ -82,8 +82,6 @@ launcher.error=错误:\u0020
launcher.err.no.args=无源文件的路径
-launcher.err.security.manager=无法在启用安全管理器的情况下使用源代码启动程序
-
# 0: string
launcher.err.invalid.filename=源文件的路径无效：{0}
diff --git a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_de.properties b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_de.properties
index eebf34ce355..06ec470a877 100644
--- a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_de.properties
+++ b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_de.properties
@@ -65,17 +65,19 @@ main.extended.help.footer=Bei Optionen, die eine erfordern, ist de
main.runtime.image.linking.cap.enabled=aktiviert
main.runtime.image.linking.cap.disabled=deaktiviert
main.runtime.image.linking.cap.sect.header=Funktionen:
-main.runtime.image.linking.cap.msg=\ Assemblierung von Laufzeitimage {0}
+main.runtime.image.linking.cap.msg=\ Verknüpfung von Laufzeitimage {0}
error.prefix=Fehler:
warn.prefix=Warnung:
-err.runtime.link.not.linkable.runtime=Dieses JDK unterstützt keine Assemblierung vom aktuellen Laufzeitimage
-err.runtime.link.jdk.jlink.prohibited=Dieses JDK enthält keine als Pakete verpackten Module und kann nicht verwendet werden, um ein anderes Image mit dem Modul jdk.jlink zu erstellen
-err.runtime.link.packaged.mods=Dieses JDK enthält keine als Pakete verpackten Module. "--keep-packaged-modules" wird nicht unterstützt
-err.runtime.link.modified.file={0} wurde modifiziert
-err.runtime.link.patched.module=Datei {0} nicht im Modulimage gefunden. "--patch-module" wird beim Verknüpfen aus dem Laufzeitimage nicht unterstützt
-err.empty.module.path=leerer Modulpfad
+err.runtime.link.not.linkable.runtime=Dieses JDK unterstützt keine Verknüpfung vom aktuellen Laufzeitimage
+err.runtime.link.jdk.jlink.prohibited=Dieses JDK enthält keine verpackten Module und kann nicht verwendet werden, um ein anderes Image mit dem Modul jdk.jlink zu erstellen
+err.runtime.link.packaged.mods=Dieses JDK enthält keine verpackten Module. "--keep-packaged-modules" wird nicht unterstützt
+err.runtime.link.modified.file={0} wurde geändert
+err.runtime.link.patched.module=jlink unterstützt keine Verknüpfung vom Laufzeitimage unter einer gepatchten Laufzeit mit --patch-module
+err.no.module.path=--module-path Option muss mit --add-modules ALL-MODULE-PATH angegeben werden
+err.empty.module.path=Kein Modul im Modulpfad "{0}" mit --add-modules ALL-MODULE-PATH gefunden
+err.limit.modules=--limit-modules nicht mit --add-modules ALL-MODULE-PATH zulässig
err.jlink.version.mismatch=jlink-Version {0}.{1} stimmt nicht mit Ziel-java.base-Version {2}.{3} überein
err.automatic.module:automatisches Modul kann nicht mit jlink verwendet werden: {0} aus {1}
err.unknown.byte.order:unbekannte Bytereihenfolge {0}
@@ -116,5 +118,5 @@ no.suggested.providers=Option --bind-services ist angegeben. Keine weiteren Prov
suggested.providers.header=Vorgeschlagene Provider
providers.header=Provider
-runtime.link.info=Assemblierung basierend auf dem aktuellen Laufzeitimage
+runtime.link.info=Verknüpfung basierend auf dem aktuellen Laufzeitimage
runtime.link.jprt.path.extra=(Laufzeitimage)
diff --git a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_ja.properties b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_ja.properties
index a20a97bcfcb..85796abba7c 100644
--- a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_ja.properties
+++ b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_ja.properties
@@ -74,8 +74,10 @@ err.runtime.link.not.linkable.runtime=このJDKでは、現在のランタイム
err.runtime.link.jdk.jlink.prohibited=このJDKは、パッケージ化されたモジュールを含んでおらず、jdk.jlinkモジュールによる別のイメージの作成に使用できません
err.runtime.link.packaged.mods=このJDKにはパッケージ化されたモジュールがありません。--keep-packaged-modulesはサポートされていません
err.runtime.link.modified.file={0}が変更されました
-err.runtime.link.patched.module=ファイル{0}がモジュール・イメージに見つかりません。ランタイム・イメージからリンクする際、--patch-moduleはサポートされていません
-err.empty.module.path=空のモジュール・パス
+err.runtime.link.patched.module=--patch-moduleを使用してパッチ済ランタイムで実行する際、jlinkではランタイム・イメージからのリンクをサポートしていません
+err.no.module.path=--module-pathオプションは--add-modules ALL-MODULE-PATHで指定する必要があります
+err.empty.module.path=モジュール・パス''{0}''に--add-modules ALL-MODULE-PATHを使用したモジュールが見つかりません
+err.limit.modules=--limit-modulesは--add-modules ALL-MODULE-PATHとともに指定できません
err.jlink.version.mismatch=jlinkバージョン{0}.{1}がターゲットのjava.baseバージョン{2}.{3}と一致しません
err.automatic.module:jlinkでは自動モジュールは使用できません: {1}からの{0}
err.unknown.byte.order:不明なバイト順{0}
diff --git a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_zh_CN.properties b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_zh_CN.properties
index c6746c7705c..b027c4afaee 100644
--- a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_zh_CN.properties
+++ b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_zh_CN.properties
@@ -74,8 +74,10 @@ err.runtime.link.not.linkable.runtime=此 JDK 不支持从当前运行时映像
err.runtime.link.jdk.jlink.prohibited=此 JDK 不包含打包模块，无法用于使用 jdk.jlink 模块创建其他映像
err.runtime.link.packaged.mods=此 JDK 没有打包模块。不支持 --keep-packaged-modules
err.runtime.link.modified.file=已修改 {0}
-err.runtime.link.patched.module=在模块映像中未找到文件 {0}。从运行时映像链接时，不支持 --patch-module
-err.empty.module.path=空模块路径
+err.runtime.link.patched.module=当使用 --patch-module 在打补丁的运行时上运行时，jlink 不支持从当前运行时映像链接
+err.no.module.path=--module-path 选项必须与 --add-modules ALL-MODULE-PATH 一起指定
+err.empty.module.path=在随 --add-modules ALL-MODULE-PATH 提供的模块路径 ''{0}'' 中找不到模块
+err.limit.modules=不允许将 --limit-modules 与 --add-modules ALL-MODULE-PATH 一起使用
err.jlink.version.mismatch=jlink 版本 {0}.{1} 与目标 java.base 版本 {2}.{3} 不匹配
err.automatic.module:自动模块不能用于来自 {1} 的 jlink: {0}
err.unknown.byte.order:未知的字节顺序 {0}
diff --git a/src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod_de.properties b/src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod_de.properties
index 84abaee4ce3..a5896e94abb 100644
--- a/src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod_de.properties
+++ b/src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod_de.properties
@@ -57,7 +57,7 @@ main.opt.man-pages=Speicherort der Manpages
main.opt.target-platform=Zielplattform
main.opt.target-platform.arg=target-platform
main.opt.module-path=Modulpfad
-main.opt.hash-modules=Berechnet und erfasst Hashes zur Bindung eines in ein Package integrierten Moduls an Module, die dem angegebenen entsprechen und direkt oder indirekt davon abhängen. Die Hashes werden in der erstellten JMOD-Datei oder in einer JMOD- oder modularen JAR-Datei in dem Modulpfad erfasst, der im jmod-Hashbefehl angegeben ist.
+main.opt.hash-modules=Berechnet und erfasst Hashes zur Bindung eines verpackten Moduls an Module, die dem angegebenen entsprechen und direkt oder indirekt davon abhängen. Die Hashes werden in der erstellten JMOD-Datei oder in einer JMOD- oder modularen JAR-Datei in dem Modulpfad erfasst, der im jmod-Hashbefehl angegeben ist.
main.opt.do-not-resolve-by-default=Aus dem Standard-Root-Set von Modulen ausschließen
main.opt.warn-if-resolved=Hinweis für ein Tool, eine Warnung auszugeben, wenn das Modul aufgelöst wird, entweder "deprecated", "deprecated-for-removal" oder "incubating"
main.opt.date=Datum und Uhrzeit für die Zeitstempel von Einträgen, angegeben im erweiterten Datums-/Uhrzeitformat mit Zeitunterschied und optionaler Zeitzone nach ISO-8601. Beispiel: "2022-02-12T12:30:00-05:00"
diff --git a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/HelpResources_de.properties b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/HelpResources_de.properties
index f060abe314f..31d6e11d70c 100644
--- a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/HelpResources_de.properties
+++ b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/HelpResources_de.properties
@@ -25,8 +25,8 @@
#
MSG_Help=Verwendung: jpackage \n\nBeispielverwendungen:\n--------------\n Generiert ein für das Hostsystem geeignetes Anwendungspackage:\n Für eine modulare Anwendung:\n jpackage -n name -p modulePath -m moduleName/className\n Für eine nicht modulare Anwendung:\n jpackage -i inputDir -n name \\\n --main-class className --main-jar myJar.jar\n Aus einem vorab erstellten Anwendungsimage:\n jpackage -n name --app-image appImageDir\n Generiert ein Anwendungsimage:\n Für eine modulare Anwendung:\n jpackage --type app-image -n name -p modulePath \\\n -m moduleName/className\n Für eine nicht modulare Anwendung:\n jpackage --type app-image -i inputDir -n name \\\n --main-class className --main-jar myJar.jar\n Um eigene Optionen für jlink anzugeben, führen Sie jlink separat aus:\n jlink --output appRuntimeImage -p modulePath \\\n --add-modules moduleName \\\n --no-header-files [...]\n jpackage --type app-image -n name \\\n -m moduleName/className --runtime-image appRuntimeImage\n Generiert ein Java Runtime-Package:\n jpackage -n name --runtime-image \n{6}\nAllgemeine Optionen:\n @