JEP draft: Prepare to Restrict The Use of JNI

[Volker Simonis]

On Thu, Aug 24, 2023 at 5:16 AM Maurizio Cimadamore
<maurizio.cimadamore at oracle.com> wrote:
>
> Hi Volker.
>
> On 24/08/2023 13:05, Volker Simonis wrote:
> > I think it is a little unfortunate that the specification of
> > "Restricted Methods" is buried in the documentation of the
> > java.lang.foreign package [1] which is "only" a preview feature. Apart
> > from there it is mentioned neither in the Java Language Specification
> > nor in the JVM specification (as far as I can see).
> There is no change to the Java language, nor any change to the JVM
> behavior. This is why restricted methods aren't (and shouldn't) covered
> there.
> >
> > If "Restricted Methods" will be used more broadly and enforced by the
> > SE specification it think it makes sense to introduce a new,
> > @Documented annotation (e.g. @Restricted) to make the restricted
> > nature of specific methods more explicit. This would also make it
> > possible for tools like compilers/IDEs to flag this methods at
> > development/build time (similar to @Deprecated). Just mentioning that
> > a method is restricted somewhere down in their API documentation ( see
> > e.g. java.lang.foreign.Linker.nativeLinker()) doesn't seem to reflect
> > the impact of this attribute.
>
> I agree, this is something we have considered. Unfortunately there is
> the usual dilemma here: if the annotation is public, then you can add it
> to your 3rd party methods, which is a moral hazard (after all,
> restricted methods are a JDK concept).
>

I'm not a module expert but can't we create a public, documented
annotation in a package which is only exported to the core JDK modules
with the help of a qualified export?

> That said, an internal annotation like `@PreviewFeature` could be enough
> to provide javac support along the lines you describe.
>

Yes, that would be enough for javac but not for IDEs and external tools.

> As to the fact that restricted methods are for now described in the
> java.lang.foreign package, I agree it's a bit suboptimal (especially
> moving forward) - even though, for now, you only really care about
> restricted methods if you use the FFM API, really.
>
> Once restricted methods start to show up elsewhere, we could perhaps
> pull up the definition of restricted methods in a separate page,
> similarly to what was done for value based:
>
> https://download.java.net/java/early_access/jdk21/docs/api/java.base/java/lang/doc-files/ValueBased.html
>
> And link to that same page across the JDK API, rather than have the
> section embedded in the java.lang.foreign package description.
>
> Maurizio
>
>
>