PreviewFeature on packages and modules

[Jan Lahoda]

On 03. 02. 21 23:58, 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! :-)


Propagating the preview flag from module to (top-level, presumably) 
classes seems to be fairly easy when compiling against classfiles. 
Propagating the flag from packages to classes would be more difficult, 
as the preview flag is commonly not read for packages - if we were to 
change that, we would need start reading all package-info.class files, 
with possible implications on performance.


Jan


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