Improving compiler messages for preview API

[Alex Buckley]

On 8/7/2019 1:30 PM, Jonathan Gibbons wrote:
> While I accept that you may not be concerned with non-SE API, I note 
> that the APIs I'm talking about are public documented supported JDK 
> APIs, and not just compiler-internal APIs.
There is an SE-oriented variant of supported compiler APIs: what JEP 12 
calls "reflective" APIs. For example, if record types preview in SE 14, 
then should associated methods in Core Reflection such as 
Class::isRecord be marked @PreviewFeature?

On the one hand, no -- enthusiastic framework authors should be able to 
use Class::isRecord to handle user-defined records in an appropriate 
way, without the framework's own classes having to be compiled and run 
with --enable-preview. On the other hand, yes -- the possibility of 
records changing in future means that any class's use of Class::isRecord 
should be strictly boxed in by having to enable preview features; 
framework authors can use MRJARs to separate 14-era class files from the 
rest.

One option is to say that use of essential @PreviewFeature APIs without 
--enable-preview gets an error, but use of reflective @PreviewFeature 
APIs without --enable-preview gets a warning -- but now that warning 
needs to be defined and engineered, and there will be requests to handle 
non-SE APIs in the same manner as reflective SE APIs. So, I plan to 
stick with JEP 12's current policy and treat essential and reflective 
APIs the same: their use requires --enable-preview.

Alex