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

[Jorn Vernee]

On Mon, 23 Sep 2024 11:45:23 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> It is documented by the CS JEP: https://openjdk.org/jeps/176
>> 
>>> It discovers its caller's class by invoking the sun.reflect.Reflection.getCallerClass method.
>> 
>> CS set the precedent here and the terminology.
>
>> I think "can not be determined" just begs questions. Is this a JDK limitation, something I'm doing wrong, or something else, ... if you see what I mean.
> 
> I think saying 'no caller class on the stack' has the same effect though, unless someone knows how the implementation works (which may not be unreasonable), and is aware of the scenario where a java method is called from a new native thread. I thought it would look cleaner to have this be more 'explicitly unspecified' instead. But, maybe having something (vague or not), is better than nothing...

> It is documented by the CS JEP: https://openjdk.org/jeps/176

I read the JEP, but it only refers to `sun.reflect.Reflection.getCallerClass`, which is an internal API that I don't expect external users to know about/understand.

To be clear: I don't think we should explain exactly how CS methods determine the caller. IMO, the fact that this is implemented using a stack walk is an implementation detail that users shouldn't have to know about (and it seems plausible for VM implementations to use other mechanisms).

In lieu of that, I think it would be better to say that: in general (depending on the VM impl) there may be cases in which the caller can not be determined, and then as an example explicitly enumerate the cases in which the caller class can not be determined. That explanation can then be linked to from the CS methods.

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

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