Initial push

mcimadamore · Sep 18, 2024 · 7ce8344 · 7ce8344
1 parent 0c36177
commit 7ce8344
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 42 deletions.
diff --git a/src/java.base/share/classes/java/lang/foreign/doc-files/RestrictedMethods.html b/src/java.base/share/classes/java/lang/foreign/doc-files/RestrictedMethods.html
@@ -0,0 +1,71 @@
+<!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>
+
+Some methods in the Java SE API 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 <a href="../MemorySegment.html#reinterpret(long)"><code>MemorySegment.reinterpret(long)</code></a>
+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
+    <a href="../MemorySegment.html#reinterpret(long)"><code>MemorySegment.reinterpret(long)</code></a>
+    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>
+<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="../../ModuleLayer.Controller.html#enableNativeAccess(java.lang.Module)"><code>ModuleLayer.Controller.enableNativeAccess(java.lang.Module)</code></a>.
+</p>
+    When a restricted method is invoked by <a href="../../../../specs/jni/index.html">JNI code</a>,
+    or from an <a href="../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>
+    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/...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
@@ -2644,9 +2644,12 @@ public void addRestrictedInfo(ExecutableElement forWhat, Content target) {
             restrictedDiv.setId(htmlIds.forRestrictedSection(forWhat));
             String name = forWhat.getSimpleName().toString();
             var nameCode = HtmlTree.CODE(Text.of(name));
+            var restrictedSectionPath = replaceDocRootDir(contents.getContent("doclet.Restricted.url").toString());
+            var restrictedSectionLink = links.createLink(DocPath.create(restrictedSectionPath),
+                                                   contents.getContent("doclet.Restricted.text"));
             String leadingNoteKey = "doclet.RestrictedLeadingNote";
             Content leadingNote =
-                    contents.getContent(leadingNoteKey, nameCode);
+                    contents.getContent(leadingNoteKey, nameCode, restrictedSectionLink);
             restrictedDiv.add(HtmlTree.SPAN(HtmlStyles.restrictedLabel,
                     leadingNote));
             Content note1 = contents.getContent("doclet.RestrictedTrailingNote1", nameCode);

diff --git a/...doc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties b/...doc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
@@ -424,7 +424,9 @@ 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.Restricted.url={@docRoot}/java.base/java/lang/foreign/doc-files/RestrictedMethods.html
+doclet.Restricted.text=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.