Summary
--------

JEP 12 "Preview Features" has been updated to define _Preview APIs_, and to clarify the use of classes which are declared using preview language features. The JDK's Java compiler, javac, needs to be updated to match these updates to JEP 12, and to adhere more precisely to JEP 12 overall.


Problem
--------

javac needs to be updated to match the updated requirements of JEP 12.


Solution
--------

Change javac as follows:

1. Preview APIs are split into two broad groups: normal and reflective. Normal preview APIs are subdivided by JEP 12 into three kinds -- essential, convenient, standalone -- for expository purposes; however, javac is interested only in the fact that code uses a normal preview API versus a reflective preview API, and not in which kind of normal preview API. The critical point is that normal preview APIs can only be used with the --enable-preview flag, while reflective preview APIs may be used without the --enable-preview flag.

2. Adhere to a long-standing JEP 12 requirement to provide a suppressible warning when code uses a class declared using a preview language feature. (Example. Consider the declaration `record Point(...) {}` which uses a preview language feature and must therefore be compiled with --enable-preview. The result is `Point.class`, a class file that can only be used with --enable-preview. Accordingly, to compile code that uses Point, such as `Point p = new Point(...)`, it has always been necessary to run javac with --enable-preview. However, JEP 12 further intended that any use of a preview language feature should generate a warning: direct use (`record ...`) generates an non-suppressible warning, and indirect use (`Point p = new Point(...)`) generates a suppressible warning. The latter was unfortunately not generated in JDK 15.)

3. Mark class files as depending on preview features (minor_version 65535) only if they need it. In JDK 15, all class files produced by javac when --enable-preview flag was provided were marked as depending on preview features -- even if the code in a class made no use of preview features. In JDK 16, only classes that use preview features will have their class files marked.


Specification
--------

Where use of a preview feature is detected (or use of a class declared using a preview language feature), javac behaves as shown in the table below. "Suppression" means that `@SuppressWarnings("preview")` is applied in the source code at the point where the preview feature (or a class declared using a preview language feature) is used/invoked/overridden.

<br/>
<table>
<tr>
<td>Use of ...</td>
<td><pre>--enable-preview</pre> <pre>No Suppression</pre></td>
<td><pre>--enable-preview</pre> <pre>Suppression</pre></td>
<td><pre>No --enable-preview</pre> <pre>No Suppression</pre></td>
<td><pre>No --enable-preview</pre> <pre>Suppression</pre></td>
</tr>

<tr>
<td>Preview language feature</td>
<td>mandatory warning</td>
<td>mandatory warning</td>
<td><strong>error</strong></td>
<td><strong>error</strong></td>
</tr>

<tr>
<td>A class declared using a preview language feature</td>
<td>mandatory warning</td>
<td>no warning</td>
<td><strong>error</strong></td>
<td><strong>error</strong></td>
</tr>

<tr>
<td>Normal preview API</td>
<td>mandatory warning [1]</td>
<td>no warning</td>
<td><strong>error</strong> [1]</td>
<td><strong>error</strong> [1]</td>
</tr>

<tr>
<td>Reflective preview API</td>
    <td>mandatory warning</td>
<td>no warning</td>
<td>mandatory warning</td>
<td>no warning</td>
</tr>

</table>

[1] Referring to a normal preview API _in the same module_ is allowed without a warning / error (--enable-preview / no --enable-preview, respectively) See "Special rules for declarations of preview APIs" in JEP 12.

The table above describes behavior that has existed in JEP 12 since inception, and subsumes a more limited table that described behavior for "APIs associated with preview language features" in an earlier CSR (JDK-8231411). The formulation of the table above is as follows:

- The rows "Preview language feature" and "A class declared using a preview language feature" describe longstanding behavior from JEP 12, prior to it dealing with APIs in any way.
- The row "Normal preview API" corresponds to the "Essential" row in the earlier CSR.
- The row "Reflective preview API" corresponds to the "Non-essential" row in the earlier CSR.

The precise output of javac for a "mandatory warning" is unchanged from JDK 15:

- With -Xlint:preview, a warning on each occurrence.
- With -Xlint:-preview, a summary at the end of the compilation, stating preview features have been used.

The default setting for the `preview` lint is unchanged from JDK 15:

- -Xlint:preview when no --enable-preview is present.
- -Xlint:-preview when --enable-preview is present.

An explicit -Xlint setting overrides this default.

javac marks a class file as depending on preview features (minor_version 65535) under the following conditions:

- The corresponding source code uses a preview language feature, or a class declared using a preview language feature, or a normal preview API. (Use of a reflective preview API is exempt; see "Special rule for use of reflective preview APIs" in JEP 12.)
- The corresponding source code is part of a preview API. (See "Special rules for declarations of preview APIs" in JEP 12.)
- javac uses a preview VM feature in the generated class file.

This is a change from JDK 15, where all class files are marked as depending on preview features when compiling with --enable-preview.