PreviewFeature on packages and modules

[Jonathan Gibbons]

On 2/3/21 2:58 PM, Alex Buckley wrote:
> 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! :-)


I would expect this to be almost-zero cost in javadoc, since javadoc 
leverages javac.  For javac, I'll leave Jan to give the definitive 
answer, but I would expect it to be easy since every class knows its 
enclosing package and module.

-- Jon


>
> 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?