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 The Java Virtual + * Machine Specification, Section {@jvms 4.1} 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. + *
+ * 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. + *
+ * Additional class file format version constants will be added to model future + * class file formats defined by future releases of the JVMS. + *
+ * 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 The - * Java Virtual Machine Specification 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} @@ -364,17 +381,53 @@ public enum ClassFileFormatVersion { + /** + * 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. + *
+ * {@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. + *
+ * This is a reflective preview API to allows tools running in Java runtime + * environments with no preview feature enabled to access information + * related to preview features. + *
+ * 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. Programmers must check the current Java SE version when + * accessing the preview VM features with this constant. + * + * @see + * JEP 12: Preview Features + * @see + * Java SE Specifications + * @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 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. - * + *
* 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() { diff --git a/src/java.compiler/share/classes/javax/lang/model/SourceVersion.java b/src/java.compiler/share/classes/javax/lang/model/SourceVersion.java index 6bc1dab1f8ab7..e670d756220d7 100644 --- a/src/java.compiler/share/classes/javax/lang/model/SourceVersion.java +++ b/src/java.compiler/share/classes/javax/lang/model/SourceVersion.java @@ -25,15 +25,26 @@ package javax.lang.model; /** * Source versions of the Java programming language. * * See the appropriate edition of * The Java Language Specification * for information about a particular source version. - * - *
Note that additional source version constants will be added to - * model future releases of the language. + *
+ * Additional source version constants will be added to model future releases + * of the language. + *
+ * A special constant, {@link #CURRENT_PREVIEW}, representing the + * preview language features of the current Java SE release, is not a source + * version, but can be viewed as a future source version. Each of the preview + * language features is described by a separate document on the site that hosts + * the corresponding edition of JLS. Unlike the features in source versions, + * the preview language features are only supported when preview features are + * enabled, and are not {@linkplain #isSupported() supported by future + * releases}. * * @since 1.6 * @see java.lang.reflect.ClassFileFormatVersion @@ -463,12 +457,45 @@ public enum SourceVersion { + /** + * An enum constant representing all preview language features of the + * {@linkplain #latest() current Java SE release} in addition to those of + * the latest source version. Unlike language features associated to enum + * constants representing a source version, language features associated to + * this enum constant are not {@linkplain #isSupported() supported} by later + * Java SE releases. + * + * @apiNote + * While this is not a source version, it can be considered as the source + * version of an arbitrary future Java SE release. Programmers should test + * compiling their programs with preview features enabled to ensure the + * program is compatible with future Java SE releases. + *
+ * This is a reflective preview API to allows tools running in Java runtime + * environments with no preview feature enabled to access information + * related to preview features. + *
+ * 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. Programmers must check the current Java SE version when + * accessing the preview language features with this constant. + * + * @see + * JEP 12: Preview Features + * @see + * Java SE Specifications + * @since 25 + */ + @PreviewFeature(feature = PreviewFeature.Feature.LANGUAGE_MODEL, reflective = true) + CURRENT_PREVIEW; /** * {@return the latest source version that can be modeled} @@ -746,18 +773,34 @@ public static SourceVersion valueOf(Runtime.Version rv) { return valueOf("RELEASE_" + rv.feature()); } + /** + * {@return whether language 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 the least runtime version that supports this source * version; otherwise {@code null}} The returned runtime version * has a {@linkplain Runtime.Version#feature() feature} large * enough to support this source version and has no other elements * set. - * + *
* Source versions greater than or equal to {@link RELEASE_6} - * have non-{@code null} results. + * have non-{@code null} results. {@link #isSupported() isSupported()} + * determines if runtime versions with greater feature support this source + * version. + * * @since 18 */ public Runtime.Version runtimeVersion() {