Improving compiler messages for preview API

[Alex Buckley]

On 8/5/2019 10:40 AM, Jonathan Gibbons wrote:
> What are the arguments for and against using a public Java SE annotation 
> for this (e.g. j.l.a.PreviewFeature) when the only reasonable/expected 
> usage is within Java SE and the JDK implementation.  There's a tiny tiny 
> code smell defining an annotation type that no other users of Java SE 
> will ever use. That being said, I guess it will enable non-JDK tools to 
> behave appropriately when such an annotation is found.

Some preview language features depend inexorably on APIs, so those APIs 
need to be in java.* (e.g. String::stripIndent for text blocks).

Use of those APIs when preview features are not enabled is extremely 
dangerous, because the APIs might change or disappear depending on the 
fate of the associated preview feature.

Leaving the developer notification up to individual compilers is 
inadequate. JEP 12 already mandates a policy for highlighting the 
changeability of these APIs -- terminal deprecation at birth. 
Conveniently, that required no JLS or compiler changes.

Joe has made a number of arguments, that I hope he will record in 
JDK-8226585, against using terminal-deprecation-at-birth. Per this 
thread, a compile-time error is even better than a warning when the 
developer fails to enable preview features.

The only way to get all Java compilers to give an error is with a JLS 
change and a Java SE annotation.

It would not be an error to _apply_ this annotation to declarations 
outside the Java SE API, but compilers would be required to give an 
error only when code uses an annotated element which is part of the Java 
SE API.

Alex