JDK-8249680 : Using reflection to work with the elements of a preview API at run time deserves to be mentioned in the JavaSE API specification
  • Type: Enhancement
  • Component: core-libs
  • Sub-Component: java.lang:reflect
  • Affected Version: 16
  • Priority: P3
  • Status: New
  • Resolution: Unresolved
  • Submitted: 2020-07-17
  • Updated: 2020-07-17
Related Reports
Relates :  
JDK-8195734 - JEP 12: Preview Features
Description
JEP 12 (JDK-8195734) contains the following (as of July 17th 2020):

==================
Preview APIs are not "hidden" at run time, even when preview features are disabled. A sufficiently motivated program can use reflection to detect, instantiate, and invoke the elements of a preview API at run time, whether preview features are enabled or disabled. Using reflection to refer to standalone, essential, or convenient preview APIs allows a program to be compiled without enabling preview features, and without its class files being marked as depending on preview features. This implies that the program is expected to run on multiple Java releases -- one release where the preview API is found and exploited via reflection, and other releases where it is unavailable -- and this in turn implies that the program is being developed for distribution. It is very strongly recommended that any program which uses preview APIs is not distributed. The special rule that allows for "quiet" use of reflective preview APIs aims to accommodate frameworks that react properly to the presence of preview features in user code being tested on a new version of the framework (that is, the user code is not being distributed).
==================

However the normative specification of "java.lang.reflect" JavaSE API package doesn't seem to contain any related assertions. This important aspect of behavior explained in JEP12 deserves to be mentioned in the JavaSE API specification.
Comments
As major APIs start to appear in the JDK under the preview mechanism, I agree that reflective API specs (principally Core Reflection and Language Model) should clarify that preview APIs *are* discoverable and invokable via reflection, even when preview features are disabled. No reflective API has, or should have, special knowledge or handling for preview APIs. Example: Given the preview feature of Records, it is possible to obtain the Class object for `java.lang.Record`, or to invoke methods on a record object reflectively, without errors or warnings, even if preview features are disabled. The quote in the Description is advanced, in that contrasts use of a _reflective preview API_ (e.g. using `Class::isRecord` to see if user code is a record) with use of a _reflective permanent API_ (e.g. using `Class::getSuperclass` to see if user code's superclass is `java.lang.Record`, then calling `Class::getMethods` to operate the user code or its superclass). The relevant scenario for a Core Libs engineer reading this RFE is the latter one -- a preview API element like `java.lang.Record` or `String::translateEscapes` is not hidden from a power user who understands `java.lang.{Class, reflect}`.
17-07-2020