PreviewFeature on packages and modules

[Alex Buckley]

On 2/5/2021 2:55 AM, Jan Lahoda wrote:
>> On 2/4/2021 9:53 AM, Alex Buckley wrote:
>> We should probably switch "top-level classes" to "public classes, 
>> whether top level or nested". The preview module might not export a 
>> package, in which case it doesn't matter that we treat the package's 
>> public classes as preview (since they're inaccessible); but if the 
>> preview module does export a package, then we should recognize its 
>> public nested classes as part of the API alongside its public top 
>> level classes (consider j.l.i.MethodHandles.Lookup).
> 
> I'd point out it is not easy to refer to a nested class without first 
> referring to the enclosing class (could happen e.g. when the code can 
> refer to the nested class using simple name e.g. due to inheritance). 

I'm completely with you. My concern is that if JEP 12 focuses on 
[public] _top level_ classes in [an exported package of] a preview 
module, then Nikita will be along two minutes later to ask if [public] 
nested classes inside those top level classes are preview APIs too. The 
answer is "yes", so in some sense the [public] nested classes should be 
treated as having @PreviewFeature too. (Please don't respond yet. Please 
keep reading.)

> And showing warnings on both the enclosing and nested class may be 
> discouraging.

Again, you're right, and javac as a quality-of-implementation matter 
could choose to give only a warning for the enclosing class name.

> But there is a possibly bigger question: if we copy the flags from 
> modules to nested classes, should we copy them from preview classes (in 
> non-preview modules) to their nested classes? Or from preview classes to 
> their members and constructors? (This is very unlike e.g. deprecation, 
> which does not copy the flag to any enclosed element, AFAIK.)

Yes, we were heading for this question regardless of Nikita's question 
about packages and modules. Conceptually, putting @PreviewFeature on a 
top level class means that all of its public members and ctors are a 
preview API. Practically, I agree with your earlier comment that it's 
hard to use a member without using the enclosing class name. So, while 
JEP 12 will clarify that a preview module causes all its accessible 
public classes (top level or nested) to be in preview, I think javac 
need only copy preview status from module to top level classes in order 
to tell clients what they're using.

Alex