Summary
-------

The javadoc should specify more clearly how restricted method checks are applied when a restricted method is called from foreign code and there is no Java class in the caller stack.

Problem
-------

During the CSR review for [JEP 472](https://openjdk.org/jeps/472) it was noted that the [JNI specification](https://docs.oracle.com/en/java/javase/23/docs/specs/jni/design.html#calling-caller-sensitive-methods) states that, when caller sensitive methods are called from JNI code (e.g. during an upcall), it is up to the caller sensitive method being called to specify what happens when no Java class exists on the caller stack. This situation can arise e.g. if a caller sensitive method is called from a new thread forked from foreign code -- either via JNI or FFM. Since restricted methods behave as caller sensitive methods -- the restricted method check depends on the module of the caller class -- it is important for javadoc of restricted methods to specify how the restricted method check works when there is no Java class in the caller stack. Ideally such description should appear in a centralized place, where restricted methods are introduced.

Now, as part of [JEP 454](https://openjdk.org/jeps/454), some changes to javadoc were made, so that javadoc now displays a "banner" for all restricted methods. Here's an example:

[Linker::downcallHandle](https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/lang/foreign/Linker.html#downcallHandle(java.lang.foreign.MemorySegment,java.lang.foreign.FunctionDescriptor,java.lang.foreign.Linker.Option...))

However, the explanation of what restricted methods are is left to the package javadoc here:

[java.lang.foreign package](https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/lang/foreign/package-summary.html#restricted)

While a description of what happens when a restricted method is called with no Java class on the caller stack could be provided here, doing so would be problematic:

 * the package javadoc description of restricted methods is easily discoverable;
 * now that other methods outside the `java.lang.foreign` package (i.e. `System::loadLibrary`) have been also made restricted, describing restricted methods in the package javadoc for `java.lang.foreign` feels out of place;
 * the description in the `java.lang.foreign` package javadoc feels very FFM-centric.

Solution
--------

The solution is to add a link from the restricted method javadoc banner to a static page that contains detailed information on what restricted methods are, and what command line options can be used to control access to them. This static page can also be used to include information on what happens when a restricted method is called and there's no Java class on the caller stack. Since the static page is linked directly from the javadoc details page of a restricted method, it is easily discoverable. Also, the static page should not live in `java.lang.foreign` but in `java.lang`, and the contents of this page should be applicable to *all* restricted methods, not just to FFM-specific restricted methods.

Specification
-------------

This is the new static page describing restricted methods:

[Retsricted methods static page](https://cr.openjdk.org/~mcimadamore/jdk/restricted_javadoc_section/docs/api/java.base/java/lang/doc-files/RestrictedMethods.html)

And this is an example of the new link from the restricted banner in the method javadoc to the new page:

[Linker::downcallHandle](https://cr.openjdk.org/~mcimadamore/jdk/restricted_javadoc_section/docs/api/java.base/java/lang/foreign/Linker.html#downcallHandle(java.lang.foreign.MemorySegment,java.lang.foreign.FunctionDescriptor,java.lang.foreign.Linker.Option...))

For completeness, the contents of the restricted method javadoc page is included below:

```
Various methods in the Java SE API allow Java code to interoperate with resources outside the Java runtime
in such a way that the runtime cannot prove correct or safe use of the resources. These methods can,
when used incorrectly, violate the integrity of the Java Virtual Machine, but are conditionally made available
to users, as they provide essential functionality. They are known as *restricted methods*.

Given the potential danger of restricted methods, the Java runtime issues a warning on
the standard error stream every time a restricted method is invoked. Such warnings can
be disabled by granting access to restricted methods to selected modules. This can be
done either via implementation-specific command line options or programmatically, e.g.
by calling `ModuleLayer.Controller.enableNativeAccess(java.lang.Module)`.

When a restricted method is invoked by JNI code, or from an *upcall stub* and there is
no caller class on the stack, it is as if the restricted method call occurred in an *unnamed module*.

In the reference implementation, access to restricted methods can be granted to
specific modules using the command line option `--enable-native-access=M1,M2, ... Mn`,
where `M1, M2, ... Mn` are module names (for the unnamed module,
the special value `ALL-UNNAMED` can be used).  Access to restricted methods
from modules not listed by that option is deemed <em>illegal</em>. Clients can
control how access to restricted methods is handled, using the command line
option `--illegal-native-access`. If this option is not specified,
illegal access to restricted methods will result in runtime warnings.</p>
```

The JNI specification is also updated, as follows, to include a reference to the new javadoc restricted method page:

```
--- a/closed/src/java.se/share/specs/jni/design.md
+++ b/closed/src/java.se/share/specs/jni/design.md
@@ -111,8 +111,10 @@ The method `System.loadLibrary` and the related methods `System.load`,
 their behavior depends on whether the module of their caller has native access enabled,
 determined as if by invocation of
 [`Module.isNativeAccessEnabled`](../../api/java.base/java/lang/Module.html#isNativeAccessEnabled()).
-For more information on restricted methods, see the Java SE Platform Specification
-and [Calling Caller-Sensitive Methods](#calling-caller-sensitive-methods).
+For more information on restricted methods, see the Java SE Platform Specification,
+the [Restricted Methods](../../api/java.base/java/lang/doc-files/RestrictedMethods.html) page
+in the API Specification and the [Calling Caller-Sensitive Methods](#calling-caller-sensitive-methods)
+section below.
```