RFR: 8361300: Document exceptions for Unsafe offset methods [v7]

[Chen Liang]

On Fri, 1 Aug 2025 20:19:33 GMT, Chen Liang <liach at openjdk.org> wrote:

>> src/java.base/share/classes/jdk/internal/misc/Unsafe.java line 1093:
>> 
>>> 1091:      * startup.  This should not be used to find fields in non-trusted code.
>>> 1092:      * Use the {@link #objectFieldOffset(Field) Field}-accepting version for
>>> 1093:      * arbitrary fields instead.
>> 
>> It’s also used to obtain offsets of fields in classes which have their fields filtered from reflection using `Reflection​::registerFieldsToFilter(…)`, such as fields in `java.lang.ClassLoader` or `java.lang.Module`.
>
> I don't think this is ever the intention of [JDK-8182487](https://bugs.openjdk.org/browse/JDK-8182487) (928ca49c21d7e571e88dd27cf47033bf88d2dc71) - it is a side effect, and you can always query the VM for a Field object if you are determined, or java.lang.invoke.MemberName can be used to obtain an offset for filtered fields too.

In an analogy, you could argue the existing `objectFieldOffset` can be used to obtain offsets of static fields in classes. Clearly that is a wrong way to use it; for internal APIs, we have the freedom to explicitly stop supporting some usages we deem deviating from our purpose, unlike the compatibility requirements imposed on public APIs like sun.misc.Unsafe.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25945#discussion_r2248808092