Improving compiler messages for preview API

[Alex Buckley]

On 8/8/2019 5:08 PM, Maurizio Cimadamore wrote:
> Ideally, what you want is to add @Preview in a non-exported package, 
> (pretty much as @ForceInline) so that it can be used wherever (including 
> non SE APIs) in the JDK (provided the package is qualified-exported 
> accordingly) - and that takes care of the fact that the annotation could 
> not be placed on code outside of the JDK.

This was Joe's initial intent -- jdk.internal.Preview to be precise -- 
but it would be inappropriate for such an annotation type to be 
@Documented and show up in the javadoc on String::stripIndent. There is 
also the other problem you raise:
> what the compiler should do when encountering a method 
> marked with @Preview, if @Preview itself is not part of the Java SE API 
> - meaning a spec (e.g. JLS) cant really refer to it. But, is there a 
> need for the spec to refer to it? Could we get away with saying that 
> "there must be a way to mark preview API methods" without saying _what_ 
> way that is?

The JLS is not and cannot be "open". In order for the JLS to mandate an 
error (or even a warning) about use of a preview-feature-connected API, 
the Java SE Platform has to be the ultimate authority for identifying 
such APIs. The identification must be normative, though it can be 
lightweight -- a simple mention of "Text Blocks (JEP 355)" in the 
Platform JSR is enough to get String::stripIndent on the list. Now, I 
would be mostly OK with dropping the SE-defined @PreviewFeature 
annotation if compiler vendors were eager to incorporate knowledge of 
such Platform-identified APIs, but it was made clear (internally) that 
javac did not want to do this. So, we have a marker annotation (in SE), 
and we have some consensus about wanting an error when identified APIs 
(in SE) are used without enabling preview features, and those two design 
choices work together. Let's not spend more time pondering how non-SE 
APIs can play in the preview sandpit please.

Alex