8338596: Clarify handling of restricted and caller-sensitive methods
Co-authored-by: Hannes Wallnöfer <hannesw@openjdk.org> Reviewed-by: alanb, jvernee
This commit is contained in:
Maurizio Cimadamore
parent
3b8a2f8c45
commit
f4dccfd4cf
@ -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>
|
||||
@ -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
|
||||
|
||||
@ -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;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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");
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user