8355536: Create version constants to model preview language and vm features

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

@@ -25,23 +25,43 @@
 
 package java.lang.reflect;
 
+import java.lang.classfile.ClassFile;
+
+import jdk.internal.javac.PreviewFeature;
+
 /**
- * Class file format versions of the Java virtual machine.
- *
- * See the appropriate edition of <cite>The Java Virtual Machine
- * Specification</cite> for information about a particular class file
- * format version.
- *
- * <p>Note that additional class file format version constants will be
- * added to model future releases of the Java Virtual Machine
- * Specification.
+ * Class file format versions of the Java virtual machine.  Each class file
+ * format has a particular set of VM features.  See <cite>The Java Virtual
+ * Machine Specification, Section {@jvms 4.1}</cite> for the list of class
+ * file format versions supported by the current release. The JVMS also
+ * describes, for each VM feature, the versions that support that feature, if
+ * it is not supported by all class file format versions.
+ * <p>
+ * Future editions of the JVMS may retroactively loosen restrictions imposed on
+ * a class file format version; for example, the {@linkplain #RELEASE_1 version
+ * for 1.1} is later extended to allow invocations of static methods in
+ * interfaces, introduced by Java SE 8; such a class file might not run on the
+ * release that introduced its format version.  For each Java SE release, see
+ * the corresponding edition of the JVMS for requirements on class files to run
+ * on that Java SE release.
+ * <p>
+ * Additional class file format version constants will be added to model future
+ * class file formats defined by future releases of the JVMS.
+ * <p>
+ * A special constant, {@link #CURRENT_PREVIEW}, representing the
+ * preview VM features of the current Java SE release, is not a class file
+ * format version, but can be viewed as a future class file format version.
+ * Each of the preview VM features is described by a separate document on the
+ * site that hosts the corresponding edition of JVMS.  Unlike the features in
+ * class file format versions, the preview VM features are only supported when
+ * preview features are enabled, and are not {@linkplain #isSupported()
+ * supported by future releases}.
  *
  * @apiNote
- * The complete version used in a class file includes a major version
- * and a minor version; this enum only models the major version. A
- * Java virtual machine implementation is required to support a range
- * of major versions; see the corresponding edition of the <cite>The
- * Java Virtual Machine Specification</cite> for details.
+ * Each class file format version corresponds to exactly one major version and
+ * one or more minor versions.  Each major version corresponds to one class file
+ * format version, except for {@value ClassFile#JAVA_1_VERSION}, which {@link
+ * #RELEASE_0} and {@link #RELEASE_1} both correspond to.
  *
  * @since 20
  * @see System#getProperties System property {@code java.class.version}
@@ -50,8 +70,8 @@
 @SuppressWarnings("doclint:reference") // cross-module links
 public enum ClassFileFormatVersion {
     /*
-     * Summary of class file format evolution; previews are listed for
-     * convenience, but they are not modeled by this enum.
+     * Summary of class file format evolution; previews listed for convenience
+     *
      * 1.1: InnerClasses, Synthetic, Deprecated attributes
      * 1.2: ACC_STRICT modifier
      * 1.3: no changes
@@ -89,6 +109,7 @@ public enum ClassFileFormatVersion {
      *  22: no changes
      *  23: no changes
      *  24: no changes
+     *  25: no changes
      */
 
     /**
@@ -316,65 +337,97 @@ public enum ClassFileFormatVersion {
      * The version introduced by the Java Platform, Standard Edition
      * 21.
      *
-     * @since 21
-     *
      * @see <a
      * href="https://docs.oracle.com/javase/specs/jvms/se21/html/index.html">
      * <cite>The Java Virtual Machine Specification, Java SE 21 Edition</cite></a>
+     * @since 21
      */
     RELEASE_21(65),
 
     /**
      * The version introduced by the Java Platform, Standard Edition
      * 22.
      *
-     * @since 22
-     *
      * @see <a
      * href="https://docs.oracle.com/javase/specs/jvms/se22/html/index.html">
      * <cite>The Java Virtual Machine Specification, Java SE 22 Edition</cite></a>
+     * @since 22
      */
     RELEASE_22(66),
 
     /**
      * The version introduced by the Java Platform, Standard Edition
      * 23.
      *
-     * @since 23
-     *
      * @see <a
      * href="https://docs.oracle.com/javase/specs/jvms/se23/html/index.html">
      * <cite>The Java Virtual Machine Specification, Java SE 23 Edition</cite></a>
+     * @since 23
      */
     RELEASE_23(67),
 
     /**
      * The version introduced by the Java Platform, Standard Edition
      * 24.
      *
-     * @since 24
-     *
      * @see <a
      * href="https://docs.oracle.com/javase/specs/jvms/se24/html/index.html">
      * <cite>The Java Virtual Machine Specification, Java SE 24 Edition</cite></a>
+     * @since 24
      */
     RELEASE_24(68),
 
     /**
      * The version introduced by the Java Platform, Standard Edition
      * 25.
      *
-     * @since 25
-     *
      * @see <a
      * href="https://docs.oracle.com/javase/specs/jvms/se25/html/index.html">
      * <cite>The Java Virtual Machine Specification, Java SE 25 Edition</cite></a>
+     * @since 25
      */
     RELEASE_25(69),
-    ; // Reduce code churn when appending new constants
 
-    // Note to maintainers: when adding constants for newer releases,
-    // the implementation of latest() must be updated too.
+    // Note to maintainers: Add new constants right above.
+    // The implementation of latest() must be updated too.
+    /**
+     * An enum constant representing all preview VM features of the {@linkplain
+     * #latest() current Java SE release} in addition to those of the latest
+     * class file format version.  Unlike VM features associated to enum
+     * constants representing a class file format version, VM features
+     * associated to this enum constant are not {@linkplain #isSupported()
+     * supported} by later Java SE releases.
+     * <p>
+     * {@code class} files using any preview feature from the current Java SE
+     * release uses the same major version from that release, but uses the minor
+     * version {@value %04x ClassFile#PREVIEW_MINOR_VERSION} with all bits set
+     * to {@code 1}.  This Java Runtime Environment does not load any {@code
+     * class} file using preview features from other Java SE releases.
+     *
+     * @apiNote
+     * While this is not a class file format version, it can be considered as
+     * the class file format version of an arbitrary future Java SE release.
+     * Programmers should test their programs with preview features enabled to
+     * ensure the program is compatible with future Java SE releases.
+     * <p>
+     * This is a reflective preview API to allow tools running in Java runtime
+     * environments with no preview feature enabled to access information
+     * related to preview features.
+     * <p>
+     * As each Java SE release does not support preview features from any other
+     * release, this constant does not represent those features, and there is
+     * no constant representing such features this Java Runtime Environment is
+     * unaware of.  <b>Programmers must check the current Java SE version when
+     * accessing the preview VM features with this constant.</b>
+     *
+     * @see <a href="https://openjdk.org/jeps/12">
+     * JEP 12: Preview Features</a>
+     * @see <a href="https://docs.oracle.com/javase/specs">
+     * <cite>Java SE Specifications</cite></a>
+     * @since 25
+     */
+    @PreviewFeature(feature = PreviewFeature.Feature.LANGUAGE_MODEL, reflective = true)
+    CURRENT_PREVIEW(ClassFile.latestMajorVersion());
 
     private final int major;
 
@@ -389,6 +442,17 @@ public static ClassFileFormatVersion latest() {
         return RELEASE_25;
     }
 
+    /**
+     * {@return whether VM features associated with this enum constant will be
+     * supported by future Java SE releases}  Returns {@code false} only for
+     * {@link #CURRENT_PREVIEW}.
+     *
+     * @since 25
+     */
+    public boolean isSupported() {
+        return this != CURRENT_PREVIEW;
+    }
+
     /**
      * {@return the major class file version as an integer}
      * @jvms 4.1 The {@code ClassFile} Structure
@@ -436,11 +500,15 @@ public static ClassFileFormatVersion valueOf(Runtime.Version rv) {
      * runtime version has a {@linkplain Runtime.Version#feature()
      * feature} large enough to support this class file format version
      * and has no other elements set.
-     *
+     * <p>
      * Class file format versions greater than or equal to {@link
-     * RELEASE_6} have non-{@code null} results.
+     * #RELEASE_6} have non-{@code null} results.  {@link #isSupported()
+     * isSupported()} determines if runtime versions with greater
+     * feature support this class file format version.
      */
     public Runtime.Version runtimeVersion() {
+        if (this == CURRENT_PREVIEW)
+            return latest().runtimeVersion();
         // Starting with Java SE 6, the leading digit was the primary
         // way of identifying the platform version.
         if (this.compareTo(RELEASE_6) >= 0) {

src/java.base/share/classes/jdk/internal/javac/PreviewFeature.java

@@ -80,6 +80,10 @@ public enum Feature {
         KEY_DERIVATION,
         @JEP(number = 502, title = "Stable Values", status = "Preview")
         STABLE_VALUES,
+        /**
+         * Reflective preview APIs to access preview language and VM
+         * features as a whole.
+         */
         LANGUAGE_MODEL,
         /**
          * A key for testing.