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

[David Holmes]

On Mon, 23 Sep 2024 09:33:27 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> I suggested the current wording here: https://github.com/openjdk/jdk/pull/21067#discussion_r1767316787
>> 
>> I think 'no caller on the stack' is too vague. AFAICT, the mechanism by which a CS method determines its caller is not documented (if it is, we should link to that here). Also, I think a user might reasonably ask: "In which cases would there not be a caller class on the stack?". So, I suggested the blanket statement instead, rather than leaning on poorly defined concepts.
>
> We use "no caller class" in the CS methods, maybe it could be improved. 
> 
> 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.

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.

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

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