PreviewFeature on packages and modules

[Alex Buckley]

On 2/3/2021 1:30 PM, Jan Lahoda wrote:
> One thing to note here is e.g. @Deprecated on a package does not 
> automatically deprecate the classes belonging to the given package. 
> Here, we have a package annotated with @PreviewFeature, but not a class 
> annotated as a preview feature, and the preview flag is not propagated 
> from packages to classes, similarly to the deprecated flag. But we can 
> surely make this particular flag to propagate to the classes in the 
> package, if desired.

Thanks for the info. I agree that a package being annotated with 
@PreviewFeature is misleading, since like package deprecation, it's a 
no-op. However, a module being annotated with @PreviewFeature ought to 
have a visible effect if another module `requires` it. If Nikita puts 
Main.java in a module that `requires jdk.neshkeev`, then I'd expect a 
warning/error.

This thread is really about whether explicitly designating a module as a 
preview API implicitly designates every class within the module as a 
preview API. JEP 12 doesn't directly answer that question. It only says 
that every class within the preview module is "participating", and what 
happens if a class _explicitly_ designated as preview is used by other code.

The other way of asking the question is: Should a preview module be able 
to contain non-preview classes? (Where every preview class in the module 
would be marked with @PreviewFeature, and any class not so marked would 
be non-preview.)  First issue: you could "silently" use such non-preview 
classes from code on the classpath without a `requires` clause to 
trigger a warning/error for use of the preview module itself. This 
"silent" use feels undesirable, given the preview module's non-final 
status.  Second issue: preview classes and non-preview classes could 
live in the same package (since preview classes aren't forced into a 
dedicated namespace like incubating classes) -- that's legitimate when a 
few preview classes are added to a classic package in java.base, but we 
didn't really envisage a handful of non-preview classes hanging out in a 
vast crowd of preview classes in a preview module.

In sum, there's a strong case for saying that everything in a preview 
module has preview status. (Where marking anything in the module with 
@PreviewFeature is legal but redundant.) This would be convenient for 
preview API designers, who could write @PreviewFeature once and have it 
trickle down.

I suspect this is either very painful to implement in javac/javadoc, or 
very easy. Jan, please tell us which! :-)

Alex

>> On 2/3/2021 8:00 AM, Nikita Eshkeev wrote:
>>> The PreviewFeature 
>>> (https://github.com/openjdk/jdk/blob/master/src/java.base/share/classes/jdk/internal/javac/PreviewFeature.java 
>>> <https://github.com/openjdk/jdk/blob/master/src/java.base/share/classes/jdk/internal/javac/PreviewFeature.java>) 
>>> annotation can be applied to modules and packages. But I don't get 
>>> any compile-time errors/warnings when I try to use code that is 
>>> inside of either a package or a module that is annotated with 
>>> PreviewFeature.
>>> What I did
>>> 1. I added a new module to openjdk with the "jdk.neshkeev" name
>>> 2. I added module-info.java, package-info.java and 
>>> MyPreviewClass.java (which is just an empty class)
>>> 3. I annotated both module-info.java and package-info.java with 
>>> PreviewFeature
>>> 4. I exported jdk.internal.javac package to jdk.neshkeev in 
>>> module-info.java of java.base
>>> 5. `make images` the jdk's source code
>>> 6. I created Main.java with the following content
>>> class Main {
>>>   {
>>>     new jdk.neshkeev.MyPreviewClass();
>>>   }
>>> }
>>> 7. I compiled Main.java with my openjdk that was built in the step 5.
>>> Here is the link to my openjdk fork with the jdk.neshkeev module: 
>>> https://github.com/neshkeev/jdk <https://github.com/neshkeev/jdk>
>>> What is expected
>>> Since MyPreviewClass is inside of the package that is annotated with 
>>> PreviewFeature and it is also inside of the module that is also 
>>> annotated with PreviewFeature I expect to get compile time 
>>> errors/warnings. I believe that compile-time errors/warnings should 
>>> arise since Main.java can't be considered as participating source code
>>> What happened
>>> No compile-time errors/warnings occurred
>>> Is this a bug?