Improving compiler messages for preview API

[Alex Buckley]

On 8/5/2019 11:19 AM, Jonathan Gibbons wrote:
> On 08/05/2019 11:07 AM, Jonathan Gibbons wrote:
>> On 08/05/2019 10:52 AM, Alex Buckley wrote:
>>> 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
>>
>> Your last point is a good one, and duly noted.
>>
>> To the rest, yes, while other users may not want to *use* the 
>> annotation type, it is definitely of interest to them, and to the 
>> tools that they may use, that the annotation has been provided on API 
>> related to preview features.
>>
>> -- Jon
> 
> I note that I would want to use the annotation on non-Java SE API, and 
> the com.sun.source.tree API in particular, where we define the compiler 
> AST classes, including any new elements for preview features.

To be clear about this case, a compiler would be required to do nothing 
about the use of such an API -- no warning, no error. The definition of 
java.lang.annotation.PreviewFeature will refer to marking "essential" 
and "reflective" Java SE APIs connected with preview features; the 
annotation has no meaning if applied to a non-Java SE API.

Alex