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 illegal. 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.
- * 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. - *
- * 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)}. - *
- * 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 illegal. 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 index fdf05489168..9bb1ebaaf62 100644 --- 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 abstract class HtmlDocletWriter { //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 index 6141ce46fe8..bb001912229 100644 --- 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 index 5ae2d159072..47cf3e81ebe 100644 --- 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 class DocPaths { /** 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");