JEP draft: Prepare to Restrict The Use of JNI

[Maurizio Cimadamore]

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).

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

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