skip to content

Release Train & Preview Stages

A feature release ships every six months, vendors name some of them LTS, and a feature can spend releases in preview or incubation first. Interviewers ask what that means for choosing a version.

part ofJavaread it →
on this pageshow

questions

2

What do preview and incubating mean for a Java feature, how do you enable each, and how does a feature leave that stage?

level: middleimportance: should knowfreq 38%

answer

  1. complete versus not yet proven
  2. opt in twice
  3. all 16 bits of minor_version
  4. the jdk.incubator prefix
  5. new JEP to finalize, JBS issue to remove

basics

~20 s

Preview means complete but impermanent language, VM or API features, enabled with --enable-preview; incubating means less proven APIs or tools in jdk.incubator modules, resolved with --add-modules. Either goes final through a new JEP or gets removed.

solid answer

~40 s

A preview feature (JEP 12) is a language, VM or API feature that is fully specified and implemented but not yet permanent. You opt in twice: `javac --release 27 --enable-preview`, then `java --enable-preview`, because javac marks a class that uses the feature `71.65535` and a JVM refuses it without the flag or on any other release. An incubating feature (JEP 11) is a less proven API or tool in a `jdk.incubator` module, outside Java SE; class-path code asks for it with `--add-modules`, and its class files are not marked. A preview leaves through a new JEP without the `(Preview)` suffix, or through a JBS issue that removes it. An incubating API is renamed out of `jdk.incubator` when promoted, or its module is removed.

code

java · 8 lines
java
public class PreviewDemo {
    public static void main(String[] args) {
        Object value = 5;
        if (value instanceof int number) { // a primitive type pattern: preview at JDK 27
            System.out.println(number + 1);
        }
    }
}

go deeper

for a junior

Recall the two words and their flags: preview features need --enable-preview at compile and run time, and incubating APIs live in jdk.incubator modules reached with --add-modules. Know that neither is permanent yet.

for a middle

Explain what the compiler does once the flag permits it: it marks each class that uses a preview feature with minor_version 65535, and the JVM refuses those without the flag or on another release. Contrast that with unmarked incubator class files.

for a senior

Show the operational consequences: preview class files tie a build to one JDK release, so an upgrade forces a rebuild and possibly a rewrite, and incubating APIs may change or vanish even between update releases.

for a principal

Treat it as a policy decision: the gain from early features and feedback against pinning libraries and deployments to one release, and whether preview use is allowed in code you distribute or only where you control the deployment.

## Two stages, two different promises Both stages put a new feature into a General Availability JDK so developers can try it before it is permanent. They differ in how finished the feature must be and in how hard the JDK makes it to depend on. | | Preview (JEP 12) | Incubating (JEP 11) | |---|---|---| | Covers | Language, VM and Java SE API features | APIs and tools only | | Maturity | Complete; could credibly go final with no further changes | Not yet sufficiently proven | | Java SE status | Enumerated by Java SE, supported by every implementation of that release | Outside Java SE, in a JDK module | | Names | The form intended as final, with no temporary packages; an API may still be renamed | `jdk.incubator.` prefix on module and packages | | Opt-in | `--enable-preview`, all or nothing | `--add-modules`, per module | | Class file | Marked, tied to one release | Not marked | **Preview does not mean experimental.** JEP 12 says a preview feature must not be experimental, risky, incomplete or unstable, and separates it from HotSpot's experimental features, which `-XX:+UnlockExperimentalVMOptions` unlocks. What it lacks is permanence. ## Using a preview feature Preview features are off at both ends, so you **opt in twice**: 1. **Compile** with `javac --release 27 --enable-preview App.java`. Without the flag, using one is a compile error such as `LazyConstant is a preview API and is disabled by default`. With the flag but no `--release` or `-source`, javac refuses, and with `--release 26` it reports `invalid source release 26 with --enable-preview`. 2. **Run** with `java --enable-preview App`. Without the flag, the JVM throws `UnsupportedClassVersionError: Preview features are not enabled for App (class file version 71.65535)`. The link between the two is the class file. At JDK 27 it carries version `71.65535`, meaning `minor_version` has all 16 bits set (JVMS 4.1); JDK 25 writes `69.65535` and refuses it without the flag in the same way. Several consequences follow: - **All or nothing.** JEP 12 says an implementation must not allow preview features to be enabled individually. - **Tied to one release.** A `69.65535` class from JDK 25 fails on JDK 27 even with the flag. You recompile, and the source may no longer compile. Choosing an LTS does not change this. - **Use sets the mark, not the flag.** A class compiled with the flag that uses no preview feature is `71.0` and loads normally. `@SuppressWarnings("preview")` does not change that: a class that uses the feature stays `71.65535`. - **The API gate is at compile time.** javac blocks a normal preview API, but the class exists at run time: `Class.forName("java.lang.LazyConstant")` works without the flag on JDK 27. Reflective preview APIs are the compile-time exception, allowed with a warning and leaving the class file unmarked. - **Finding dependents.** `-Xlog:class+preview` logs each loaded class that depends on the running release's preview features. JEP 12 says these class files should not be distributed beyond the control of the developer who chose preview features. ## Using an incubating API An **incubator module**, such as `jdk.incubator.vector`, ships in the JDK image but is not resolved by default for class-path code. `--add-modules` is the module system's general option for adding root modules (JEP 261): ```bash javac --add-modules jdk.incubator.vector App.java java --add-modules jdk.incubator.vector App ``` A modular application writes `requires jdk.incubator.vector;` instead. What you see: - **Without the option,** plain `javac` reports `package jdk.incubator.vector is not visible`, and `java` throws `NoClassDefFoundError`; `--enable-preview` does not help the run. javac 27 under `--release 27` finds the package with no option and no warning, so a clean compile there does not prove the run will work. - **Warnings** appear at run time and from plain `javac`; under `--release 27` javac prints none, even with the option. `-Xlint:-incubating` silences javac's, and JEP 11 says the warning cannot be suppressed at other times. - **No class-file lock.** The class is ordinary, so one compiled on JDK 25 runs on JDK 27 with the option. It breaks when the module or API has changed, and JEP 11 allows that even between update releases. ## How a feature leaves the stage A preview feature has three paths under JEP 12: - **Re-preview.** A new JEP, usually titled `(Second Preview)`, is required even with zero changes. Two rounds is the stated norm and some features take more: Structured Concurrency is in its seventh preview at JDK 27. - **Finalize.** A new JEP whose title drops the suffix, with no `(Final)` added. Code then needs no flag, but class files from the preview stage must be recompiled. - **Remove.** A JBS issue, with no JEP. String Templates previewed in JDK 21 and 22, then was withdrawn, and JDK 23 did not include it. An incubating feature has its own (JEP 11): - **Promote.** A new JEP, with packages renamed out of `jdk.incubator`, so adopters must at least change imports. The HTTP Client went from `jdk.incubator.http` in JDK 9 and 10 to `java.net.http` in JDK 11. The Foreign Function & Memory API, after incubating in JDK 17 and 18, went to preview in JDK 19 and final in JDK 22. - **Remove.** No JEP is necessary; the module may be silently removed. JEP 11 expects a small number of feature releases of incubation, though the Vector API, at its twelfth incubator in JDK 27, is waiting on Project Valhalla.

  • Why does Java mark a preview class file in minor_version rather than with an attribute or an access flag?
    JEP 12 prefers `minor_version` because `access_flags` is already busy, and a custom attribute or special constant pool entry would be read too late, since constant pool processing may depend on whether preview features are enabled. All 16 bits are set deliberately, because a single bit such as `61.1` could be misread as the version after `61.0`.
  • Why must javac's --enable-preview be paired with --release N when the flag takes no version of its own?
    The flag's meaning changes from one JDK to the next, so spelling out the release sets the expectation that the code is tied to it and may not compile on the next. A version on the flag would mislead, suggesting support for a later release's preview features, which are unknown when the compiler ships. `-source N` is accepted too.
  • Why are Java preview features usually re-previewed in the next release, sometimes with no changes at all?
    The train leaves little room. Only about three months separate the release of JDK N from the branch for N+1, and the three months after that branch are reserved for stabilization, not redesign. So JEP 12 assumes an owner will almost always re-preview to gather more feedback, and it requires a new JEP even with zero changes.
  • Can a Java preview feature depend on an incubating API?
    Not as part of the feature: JEP 12 says a preview feature must not rely on an incubating API, because an incubating API is not part of Java SE. An implementation is different: javac or HotSpot may use incubating APIs internally, and a preview feature may be informally advertised alongside one.

  • Preview features are experimental or unfinished, so they are lower quality than final ones.
  • You can enable a single preview feature with a flag that names it.
  • A preview class compiled on JDK 25 runs on JDK 27 if you pass --enable-preview.
  • Running with --enable-preview also resolves incubator modules, so --add-modules is unnecessary.
  • An incubating API keeps its package name when it is promoted.
  • Adding @SuppressWarnings("preview") removes the need for --enable-preview at run time.

Preview features (JEP 12)
Java 12
Incubator modules (JEP 11)
Java 9
Class file minor_version 65535 preview marker
Java 12
--add-modules option
Java 9
--enable-preview option
Java 11

Assumes JDK 27, where a class file that depends on preview features is version 71.65535; JDK 25 writes 69.65535 under the same rules.

context

open as a page

What is Java's time-based release model, how do its version numbers read, and who declares a release LTS?

level: middleimportance: should knowfreq 52%

basics

~20 s

Java ships a feature release every six months, numbered feature.interim.update.patch so the number counts release cycles, not compatibility. LTS is a support promise that JDK vendors declare for chosen releases, not a stage of the release process.

open as a page