8387304: [lworld] Review the specs of reflective preview APIs

src/java.base/share/classes/java/lang/Class.java

@@ -632,6 +632,13 @@ public static Class<?> forName(Module module, String name) {
      * {@code Class} object represents an interface, array type, primitive type,
      * or {@code void}, the result is {@code false}.
      *
+     * <p>This method returns {@code true} if and only if this {@code Class}
+     * object represents a class that uses preview features, and the class does
+     * not have the {@link AccessFlag#IDENTITY ACC_IDENTITY} flag set.
+     * The {@code ACC_IDENTITY} flag is considered always set for a class that
+     * does not use preview features; consequently, this method always returns
+     * {@code false} when preview features are disabled.
+     *
      * @jls value-objects-8.1.1.5 {@code value} Classes
      * @see AccessFlag#IDENTITY
      * @since 28
@@ -1369,7 +1376,7 @@ private Class<?> elementType() {
      *      {@code true}
      * <li> its interface modifier is always {@code false}, even when
      *      the component type is an interface
-     * <li> when preview features are enabled, its {@linkplain
+     * <li> when preview features are enabled, its {@link
      *      AccessFlag#IDENTITY identity} modifier is always true
      * </ul>
      * If this {@code Class} object represents a primitive type or
@@ -1379,9 +1386,39 @@ private Class<?> elementType() {
      * arrays, the values of other modifiers are {@code false} other
      * than as specified above.
      *
+     * <div class="preview-block">
+     *      <div class="preview-comment">
+     *          When preview features are enabled, if this {@code Class} object
+     *          represents a class that does not use preview features or an
+     *          array type, its {@code identity} modifier is always true.
+     *          <p>
+     *          When preview features are disabled, such a {@code Class} object
+     *          does not have its {@code identity} modifier set.
+     *      </div>
+     * </div>
+     *
      * <p> The modifier encodings are defined in section {@jvms 4.1}
      * of <cite>The Java Virtual Machine Specification</cite>.
      *
+     * @apiNote
+     * <div class="preview-block">
+     *      <div class="preview-comment">
+     *          Developers should be aware that the presence of the {@code
+     *          identity} modifier is dependent on whether preview features are
+     *          enabled, a status not accessible to programs.  The preferred way
+     *          to check for the identity status is to use {@link #isValue()
+     *          Class.isValue()}.
+     *          <p>
+     *          This snippet below checks whether a given {@code Class<?> clazz}
+     *          would have its {@code identity} modifier set when preview
+     *          features are enabled, yet behaves consistently regardless of
+     *          whether preview features are enabled.
+     *          {@snippet lang=java :
+     *          !clazz.isPrimitive() && !clazz.isValue() && !clazz.isInterface()
+     *          }
+     *      </div>
+     * </div>
+     *
      * @return the {@code int} representing the modifiers for this class
      * @see     java.lang.reflect.Modifier
      * @see #accessFlags()
@@ -1415,6 +1452,36 @@ private Class<?> elementType() {
      * For {@code Class} objects representing void, primitive types, and
      * arrays, access flags are absent other than as specified above.
      *
+     * <div class="preview-block">
+     *      <div class="preview-comment">
+     *          When preview features are enabled, if this {@code Class} object
+     *          represents a class that does not use preview features or an
+     *          array type, its flags always include {@code IDENTITY}.
+     *          <p>
+     *          When preview features are disabled, such a {@code Class} object
+     *          does not have the {@code IDENTITY} flag set.
+     *      </div>
+     * </div>
+     *
+     * @apiNote
+     * <div class="preview-block">
+     *      <div class="preview-comment">
+     *          Developers should be aware that the presence of the {@code
+     *          IDENTITY} flag is dependent on whether preview features are
+     *          enabled, a status not accessible to programs.  The preferred way
+     *          to check for the identity status is to use {@link #isValue()
+     *          Class.isValue()}.
+     *          <p>
+     *          This snippet below checks whether a given {@code Class<?> clazz}
+     *          would have its {@code IDENTITY} modifier set when preview
+     *          features are enabled, yet behaves consistently regardless of
+     *          whether preview features are enabled.
+     *          {@snippet lang=java :
+     *          !clazz.isPrimitive() && !clazz.isValue() && !clazz.isInterface()
+     *          }
+     *      </div>
+     * </div>
+     *
      * @see #getModifiers()
      * @jvms 4.1 The ClassFile Structure
      * @jvms 4.7.6 The InnerClasses Attribute

src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java

@@ -82,6 +82,11 @@ public sealed interface StackMapFrameInfo
 
     /**
      * {@return the expanded unset fields}
+     * <p>
+     * If a stack map frame in a {@code class} file has a non-empty list of
+     * unset fields, the {@code class} file must declare it uses preview
+     * features.  The list of unset fields is always empty for a stack map frame
+     * declared in a {@code class} file that does not use preview features.
      *
      * @jvms strict-fields-4.7.4 The {@code StackMapTable} Attribute
      * @since 28
@@ -107,6 +112,12 @@ public static StackMapFrameInfo of(Label target,
 
     /**
      * {@return a new stack map frame}
+     * <p>
+     * If a stack map frame in a {@code class} file has a non-empty list of
+     * unset fields, the {@code class} file must declare it uses preview
+     * features.  The list of unset fields is always empty for a stack map frame
+     * declared in a {@code class} file that does not use preview features.
+     *
      * @param target the location of the frame
      * @param locals the complete list of frame locals
      * @param stack the complete frame stack

src/java.base/share/classes/java/lang/reflect/AccessFlag.java

@@ -168,7 +168,13 @@ public enum AccessFlag {
     /**
      * The access flag {@code ACC_IDENTITY} with a mask value of
      * <code>{@value "0x%04x" ClassFile#ACC_IDENTITY}</code>.
+     * <p>
+     * If a class does not use preview features, the {@code ACC_IDENTITY} flag
+     * is considered always set for that class; if an interface or module
+     * descriptor does not use preview features, the {@code ACC_IDENTITY} flag
+     * is considered not set for that interface or module descriptor.
      *
+     * @see Class#isValue()
      * @jvms value-objects-4.1 Class access and property modifiers
      * @since 28
      */
@@ -280,6 +286,10 @@ public enum AccessFlag {
      * The access flag {@code ACC_STRICT_INIT}, with a mask value of
      * <code>{@value "0x%04x" ClassFile#ACC_STRICT_INIT}</code>.
      *
+     * <p>The {@code ACC_STRICT_INIT} flag is considered not set for a field
+     * declared in a class or interface that does not use preview features.
+     *
+     * @see Field#isStrictInit()
      * @jvms strict-fields-4.5 Field access and property flags
      * @since 28
      */

src/java.base/share/classes/java/lang/reflect/Field.java

@@ -285,11 +285,12 @@ public boolean isSynthetic() {
      * Returns {@code true} if this field is a strictly-initialized field;
      * returns {@code false} otherwise.
      *
-     * <p>This method returns {@code true} if and only if preview features are
-     * enabled and this field is a strictly-initialized field. The
-     * {@link AccessFlag#STRICT_INIT ACC_STRICT_INIT} flag is considered not set
-     * when preview features are disabled; consequently, this method always
-     * returns {@code false} when preview features are disabled.
+     * <p>This method returns {@code true} if and only if the class or interface
+     * that declares this field uses preview features and this field is a
+     * strictly-initialized field. The {@link AccessFlag#STRICT_INIT
+     * ACC_STRICT_INIT} flag is considered not set for a field declared in a
+     * class or interface that does not use preview features; consequently,
+     * this method always returns {@code false} when preview features are disabled.
      *
      * @return {@code true} if and only if this field is a strictly-initialized
      *         field, as defined by the Java Virtual Machine Specification

src/java.base/share/classes/java/util/Objects.java

@@ -196,6 +196,12 @@ public static String toIdentityString(Object o) {
      * {@code false}. All other objects, including arrays, are identity objects
      * and the result will be {@code true}.
      *
+     * <p>This method returns {@code false} if and only if the parameter is
+     * {@code null} or if the parameter represents a value object when preview
+     * features are enabled.  Value objects do not exist when preview features
+     * are disabled; consequently, this method behaves the same as {@link
+     * #nonNull Objects.nonNull} when preview features are disabled.
+     *
      * @apiNote
      * If the parameter is {@code null}, there is no object
      * and hence no identity; the result is {@code false}.