RFR: 8338596: Clarify handling of restricted and caller-sensitive methods [v2]

[Maurizio Cimadamore]

On Thu, 19 Sep 2024 17:21:30 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Move restricted method page to `java.lang`
>>   Update restricted method page
>
> src/java.base/share/classes/java/lang/doc-files/RestrictedMethods.html line 43:
> 
>> 41: <p>When a restricted method is invoked by <a href="../../../../specs/jni/index.html">JNI code</a>,
>> 42:     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>
>> 43:     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>
> 
>> there is no caller class on the stack
> 
> I feel like this could be a little more elaborate. I'm not sure if it's clear enough which 'stack' this is talking about, and what it means for a class to be on the stack, considering a reader who doesn't know that the caller of a caller-sensitive method is determined through a stack walk.
> 
> Maybe this could be a vague blanket statement instead, like:
> 
> Suggestion:
> 
>     and a Java caller can not be determined, it is as if the restricted method call occurred in an <em>unnamed module</em>.</p>
> 
> 
> Unfortunately, there doesn't seem to be a central place we can link to that describes how a caller for a caller sensitive method is determined, and in which cases it can not be determined (because there is no caller), which we could link to from here. There's a short discussion of caller sensitive methods [here](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/invoke/MethodHandles.Lookup.html#callsens), but it doesn't explain how the caller is determined.

I agree this text is not great. I borrowed it largely from:

https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/reflect/AccessibleObject.html#canAccess(java.lang.Object)

But it's true that it refers to a lot of "magic" terminology that is not really explained anywhere. Unfortunately, explaining what a caller sensitive method is does not belong in here either (maybe at some point we should have another static page for that :-) ).

I agree that a vague statement looks better in here.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/21067#discussion_r1767608463