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

[Maurizio Cimadamore]

On Thu, 19 Sep 2024 02:59:39 GMT, David Holmes <dholmes at openjdk.org> wrote:

> As I wrote in the CSR request for the JEP:
> 
> > I think each method that is restricted and/or caller-sensitive should specify what happens when called when there is no caller context. We should use `AccessibleObject::canAccess` as an exemplar here:
> > https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/reflect/AccessibleObject.html#canAccess(java.lang.Object)
> > I have no doubt other caller-sensitive methods have failed to do this to date, but that should be fixed.
> 
> This has to be mentioned in e.g. the javadoc for `System.loadLibrary`.

I don't disagree that the javadoc for `System::loadLibrary` is lacking. But we're conflating two aspects here. One is to say which module is used to perform the "enable native access check". And I think such a specification belongs to where we talk about _all_ restricted methods (as done in this PR). I tend to view native access enablement as orthogonal to the specification of "hat does the method do?". But perhaps that ship has sailed when we added `@throws IllegalCallerException` on all restricted methods, so perhaps it is part of the method contract after all...

Then there's the question of: JNI libraries are associated with class loaders. The class loader affected by a `System::loadLibrary` is typically derived from the class loader of the caller class. But what if there's no "caller class" ? This is, IMHO, something that `System::loadLibrary`'s javadoc should address (as this is interesting behavior re. what this method does). And I claim that this is outside the scope of this PR.

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

PR Comment: https://git.openjdk.org/jdk/pull/21067#issuecomment-2360857418