diff --git a/closed/src/java.se/share/specs/jni/design.md b/closed/src/java.se/share/specs/jni/design.md index 13bb9b45e7..ff86253285 100644 --- a/closed/src/java.se/share/specs/jni/design.md +++ b/closed/src/java.se/share/specs/jni/design.md @@ -106,6 +106,14 @@ same class loader. The VM internally maintains a list of loaded native libraries for each class loader. Vendors should choose native library names that minimize the chance of name clashes. +The method `System.loadLibrary` and the related methods `System.load`, +`System.mapLibraryName`, `Runtime.loadLibrary`, and `Runtime.load` are *restricted*: +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). + Support for both dynamically and statically linked libraries, and their respective lifecycle management *"load"* and *"unload"* function hooks are detailed in the [Invocation API section on *Library and Version @@ -116,7 +124,9 @@ Management*](invocation.html#library-and-version-management). The JNI defines a 1:1 mapping from the name of a `native` method declared in Java to the name of a native method residing in a native library. The VM uses this mapping to dynamically link a Java invocation of a `native` method to the corresponding -implementation in the native library. +implementation in the native library. This linking operation is *restricted*: its outcome +depends on whether the module of the class that declares the native method has native access +enabled, determined as if by invocation of [`Module.isNativeAccessEnabled`](../../api/java.base/java/lang/Module.html#isNativeAccessEnabled()). The mapping produces a native method name by concatenating the following components derived from a `native` method declaration: @@ -220,6 +230,8 @@ library-calling convention on a given platform. For example, UNIX systems use the C calling convention, while Win32 systems use \_\_stdcall. Native methods can also be explicitly linked using the [`RegisterNatives` function](functions.html#registering-native-methods). +The explicit linking of a native method with `RegisterNatives` is not affected +by whether native access is enabled for any module. Be aware that `RegisterNatives` can change the documented behavior of the JVM (including cryptographic algorithms, correctness, security, type safety), by changing the native code to be executed for a given native Java method. @@ -470,11 +482,12 @@ implemented internally. #### Calling Caller-Sensitive Methods -A small number of Java methods have a special property called caller sensitivity. +A number of Java methods have a special property called caller sensitivity. A _caller-sensitive_ method can behave differently depending on the identity of its immediate caller. -For example, [AccessibleObject::canAccess](../../api/java.base/java/lang/reflect/AccessibleObject.html#canAccess(java.lang.Object)) -needs to know the caller to determine accessibility. +For example, [`AccessibleObject.canAccess`](../../api/java.base/java/lang/reflect/AccessibleObject.html#canAccess(java.lang.Object)) +needs to know the caller to determine accessibility. All *restricted methods*, +specified by the Java SE Platform Specification, are also caller-sensitive. When native code calls such a method, there may not be any Java caller on the call stack. It is the responsibility of the programmer to know whether the Java