RFR: 8263102: Expand documention of Method.isBridge [v2]
Stuart Marks
smarks at openjdk.java.net
Tue Mar 9 02:02:15 UTC 2021
On Sat, 6 Mar 2021 17:44:18 GMT, Joe Darcy <darcy at openjdk.org> wrote:
>> The existing documentation of Method.isBridge isn't terribly helpful to the reader. This RFE proposes to given a common example of how bridge methods are used. The JLS does *not* have a section discussing bridge methods in detail; bridge methods are a compilation technique for lowering the Java language to the JVM, they are not a language feature per se. The example given is not exhaustive; there can be and are other uses of bridge methods.
>>
>> Once the text is agreed to; I'll update the copyright year as well.
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
>
> Improve linkage for isSynethetic.
src/java.base/share/classes/java/lang/reflect/Method.java line 593:
> 591: * result. (While the Java language specification forbids a class
> 592: * declaring two methods with the same parameter types but a
> 593: * different return type, the virtual machine does not.)
I'm of two minds about this. This is certainly a good example of a bridge method. It doesn't motivate _why_ a bridge method is necessary in this case. It think it's because the language says you should be able to write code like
EnumSet<E> es2 = es.clone();
so there needs to be a method defined in the class file whose return type is assignment-compatible with `EnumSet`. However, a `clone` method that returns `Object` is the only one that can override the `Object::clone` method. Thus, a something is necessary to span this gap -- a bridge method.
On the other hand, this might be too much detail for here. This is a really obscure location. It seems like somewhere else would be better, and where a full explanation with examples can be provided.
src/java.base/share/classes/java/lang/reflect/Method.java line 597:
> 595: * <p>Bridge methods may also be used by Java compiler in other
> 596: * circumstances to span across difference in Java Language
> 597: * semantics and JVM semantics.
If you decide to put less detail here, you could start with this statement. I think the main point is that there are some semantic gaps between methods in the Java language and in the JVM; bridge methods are necessary to "span" this gap. You might simply list some examples without explaining them fully.
Would this be "used by **a** Java compiler" or "used by **the** Java compiler?
-------------
PR: https://git.openjdk.java.net/jdk/pull/2852
More information about the core-libs-dev
mailing list