8338596: Clarify handling of restricted and caller-sensitive methods

mcimadamore · hns · mcimadamore · commit f4dccfd4cf35 · 2024-10-15T09:10:13.000Z
Co-authored-by: Hannes Wallnöfer &lt;hannesw@openjdk.org&gt;
Reviewed-by: alanb, jvernee
diff --git a/src/java.base/share/classes/java/lang/doc-files/RestrictedMethods.html b/src/java.base/share/classes/java/lang/doc-files/RestrictedMethods.html
@@ -0,0 +1,53 @@
+<!doctype html>
+<!--
+ Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+ This code is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License version 2 only, as
+ published by the Free Software Foundation.  Oracle designates this
+ particular file as subject to the "Classpath" exception as provided
+ by Oracle in the LICENSE file that accompanied this code.
+
+ This code is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ version 2 for more details (a copy is included in the LICENSE file that
+ accompanied this code).
+
+ You should have received a copy of the GNU General Public License version
+ 2 along with this work; if not, write to the Free Software Foundation,
+ Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+ Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ or visit www.oracle.com if you need additional information or have any
+ questions.
+-->
+<html lang="en">
+<head>
+    <title>Restricted methods</title>
+</head>
+<body>
+<h1 id="restricted">Restricted methods</h1>
+<p>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 <em>restricted methods</em>.</p>
+<p>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 <a href="{@docRoot}/java.base/java/lang/ModuleLayer.Controller.html#enableNativeAccess(java.lang.Module)"><code>ModuleLayer.Controller.enableNativeAccess(java.lang.Module)</code></a>.</p>
+<p>When a restricted method is invoked by <a href="{@docRoot}/../specs/jni/index.html">JNI code</a>,
+    or from an <a href="{@docRoot}/java.base/java/lang/foreign/Linker.html#upcallStub(java.lang.invoke.MethodHandle,java.lang.foreign.FunctionDescriptor,java.lang.foreign.Arena,java.lang.foreign.Linker.Option...)">upcall stub</a>
+    and there is no caller class on the stack, it is as if the restricted method call occurred in an <em>unnamed module</em>.</p>
+<p>In the reference implementation, access to restricted methods can be granted to
+    specific modules using the command line option <code>--enable-native-access=M1,M2, ... Mn</code>,
+    where <code>M1</code>, <code>M2</code>, <code>... Mn</code> are module names (for the unnamed module,
+    the special value <code>ALL-UNNAMED</code> 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 <code>--illegal-native-access</code>. If this option is not specified,
+    illegal access to restricted methods will result in runtime warnings.</p>
+</body>
+</html>
diff --git a/src/java.base/share/classes/java/lang/foreign/package-info.java b/src/java.base/share/classes/java/lang/foreign/package-info.java
@@ -128,49 +128,9 @@
  * {@linkplain java.lang.foreign.SegmentAllocator#allocateFrom(java.lang.String) converting}
  * Java strings into zero-terminated, UTF-8 strings, as demonstrated in the above example.
  *
- * <h2 id="restricted">Restricted methods</h2>
- *
- * Some methods in this package are considered <em>restricted</em>. Restricted methods
- * are typically used to bind native foreign data and/or functions to first-class
- * Java API elements which can then be used directly by clients. For instance the
- * restricted method {@link java.lang.foreign.MemorySegment#reinterpret(long)} can be
- * used to create a fresh segment with the same address and temporal bounds, but with
- * the provided size. This can be useful to resize memory segments obtained when
- * interacting with native functions.
- * <p>
- * Binding foreign data and/or functions is generally unsafe and, if done incorrectly,
- * can result in VM crashes, or memory corruption when the bound Java API element
- * is accessed. For instance, incorrectly resizing a native memory segment using
- * {@link java.lang.foreign.MemorySegment#reinterpret(long)} can lead to a JVM crash, or,
- * worse, lead to silent memory corruption when attempting to access the resized segment.
- * For these reasons, it is crucial for code that calls a restricted method to never pass
- * arguments that might cause incorrect binding of foreign data and/or functions to
- * a Java API.
- * <p>
- * 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 {@link java.lang.ModuleLayer.Controller#enableNativeAccess(java.lang.Module)}.
- * <p>
- * For every class in this package, unless specified otherwise, any method arguments of
- * reference type must not be {@code null}, and any null argument will elicit a
- * {@code NullPointerException}. This fact is not individually documented for methods of
- * this API.
- *
  * @apiNote Usual memory model guarantees (see {@jls 17.4}) do not apply when accessing
  * native memory segments as these segments are backed by off-heap regions of memory.
  *
- * @implNote
- * In the reference implementation, access to restricted methods can be granted to
- * specific modules using the command line option {@code --enable-native-access=M1,M2, ... Mn},
- * where {@code M1}, {@code M2}, {@code ... Mn} are module names (for the unnamed module,
- * the special value {@code 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 {@code --illegal-native-access}. If this option is not specified,
- * illegal access to restricted methods will result in runtime warnings.
- *
  * @spec jni/index.html Java Native Interface Specification
  *
  * @since 22
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
@@ -2642,19 +2642,31 @@ public void addRestrictedInfo(ExecutableElement forWhat, Content target) {
             //in Java platform:
             var restrictedDiv = HtmlTree.DIV(HtmlStyles.restrictedBlock);
             restrictedDiv.setId(htmlIds.forRestrictedSection(forWhat));
-            String name = forWhat.getSimpleName().toString();
+            var name = forWhat.getSimpleName().toString();
             var nameCode = HtmlTree.CODE(Text.of(name));
-            String leadingNoteKey = "doclet.RestrictedLeadingNote";
-            Content leadingNote =
-                    contents.getContent(leadingNoteKey, nameCode);
-            restrictedDiv.add(HtmlTree.SPAN(HtmlStyles.restrictedLabel,
-                    leadingNote));
-            Content note1 = contents.getContent("doclet.RestrictedTrailingNote1", nameCode);
+            var restrictedMethodLink = getRestrictedMethodDocLink();
+            var leadingNoteKey = "doclet.RestrictedLeadingNote";
+            var leadingNote = contents.getContent(leadingNoteKey, nameCode, restrictedMethodLink);
+            restrictedDiv.add(HtmlTree.SPAN(HtmlStyles.restrictedLabel, leadingNote));
+            var note1 = contents.getContent("doclet.RestrictedTrailingNote1", nameCode);
             restrictedDiv.add(HtmlTree.DIV(HtmlStyles.restrictedComment, note1));
-            Content note2 = contents.getContent("doclet.RestrictedTrailingNote2", nameCode);
+            var note2 = contents.getContent("doclet.RestrictedTrailingNote2", nameCode);
             restrictedDiv.add(HtmlTree.DIV(HtmlStyles.restrictedComment, note2));
             target.add(restrictedDiv);
         }
     }
 
+    private Content getRestrictedMethodDocLink() {
+        var restrictedMethodLabel = contents.getContent("doclet.RestrictedMethod");
+        var javaLang = utils.elementUtils.getPackageElement("java.lang");
+        if (utils.isIncluded(javaLang)) {
+            var restrictedDocPath = pathToRoot
+                    .resolve(docPaths.forPackage(javaLang))
+                    .resolve(DocPaths.DOC_FILES)
+                    .resolve(DocPaths.RESTRICTED_DOC);
+            return links.createLink(restrictedDocPath, restrictedMethodLabel);
+        }
+        return restrictedMethodLabel;
+    }
+
 }
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
@@ -424,7 +424,8 @@ doclet.ReflectivePreviewAPI={0} refers to one or more reflective preview APIs:
 doclet.UsesDeclaredUsingPreview={0} refers to one or more types which are declared using a preview feature of the Java language: {1}.
 doclet.PreviewTrailingNote1=Programs can only use {0} when preview features are enabled.
 doclet.PreviewTrailingNote2=Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
-doclet.RestrictedLeadingNote={0} is a restricted method of the Java platform.
+doclet.RestrictedMethod=restricted method
+doclet.RestrictedLeadingNote={0} is a {1} of the Java platform.
 doclet.RestrictedTrailingNote1=Programs can only use {0} when access to restricted methods is enabled.
 doclet.RestrictedTrailingNote2=Restricted methods are unsafe, and, if used incorrectly, might crash \
     the JVM or result in memory corruption.
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocPaths.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocPaths.java
@@ -163,6 +163,9 @@ public static DocPath indexN(int n) {
     /** The name of the file for restricted methods. */
     public static final DocPath RESTRICTED_LIST = DocPath.create("restricted-list.html");
 
+    /** The name of the doc-file for restricted methods. */
+    public static final DocPath RESTRICTED_DOC = DocPath.create("RestrictedMethods.html");
+
     /** The name of the directory for the resource files. */
     public static final DocPath RESOURCE_FILES = DocPath.create("resource-files");
 
