On Mon, 15 Dec 2025 16:04:10 GMT, Chen Liang <[email protected]> wrote:
>> The 3 methods to determine conversions and subtyping on `java.lang.Class`,
>> which are `isInstance`, `cast`, and `isAssignableFrom`, have their
>> documentation from the earliest days of the Java Platform. During the
>> language evolution, a lot of terms have become inaccurate, such as
>> "assignment-compatible", which does not apply for primitive types, and the
>> out-of-date instanceof analogy with the upcoming patterns, in `isInstance`;
>> `isAssignableFrom` is not very clear about arrays; `cast` would also benefit
>> from more detailed explanations.
>>
>> In my facelift, I moved the subtyping description to `isAssignableFrom`, and
>> left the conversion stuff in `isInstance` and `cast`. I intentionally
>> avoided linking to too many JLS chapters to reduce confusions. I believe in
>> this shape, we have a good amount of easily comprehensible yet accurate
>> specification for all 3 methods, and users are welcome to read the linked
>> JLS chapters for more details and context.
>
> Chen Liang has updated the pull request incrementally with one additional
> commit since the last revision:
>
> Stage
src/java.base/share/classes/java/lang/Class.java line 739:
> 737: * Determines if the reference type represented by this {@code
> Class} object
> 738: * is the same as or a proper supertype of the class of the object
> specified
> 739: * by the argument. This method is the dynamic equivalent of the
> type
What do you think about something like the following, just to minimize the diff
with the original spec?
"This method is the dynamic equivalent of the Java language {@code instanceof}
type comparison operator (JLS {@jls15.20.2})"
(adding "type comparison" before the operator)
src/java.base/share/classes/java/lang/Class.java line 741:
> 739: * by the argument. This method is the dynamic equivalent of the
> type
> 740: * comparison operator of the {@code instanceof} Java keyword (JLS
> {@jls
> 741: * 15.20.2}). This method returns {@code true} if and only if this
> {@code
I think this ("This method returns.... without throwing a {@code
ClassCastException}") didn't need a change, did it? Because now it seems that
`isInstance` checks only the success of a narrowing reference conversion.
Because the following which is a widening reference conversion check returns
`true` but it seems to be excluded by the new javadoc:
`Animal.class.isInstance(new Dog())`.
src/java.base/share/classes/java/lang/Class.java line 748:
> 746: * Class} object without throwing a {@code ClassCastException}.
> 747: *
> 748: * <p>This method behaves as if:
Showing an example is a great idea! Shouldn't we use an example with the actual
`instanceof` type comparison operator here? Why use an example of
`isAssignableFrom` to the `isInstance` javadoc?
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/28684#discussion_r2660767325
PR Review Comment: https://git.openjdk.org/jdk/pull/28684#discussion_r2661907375
PR Review Comment: https://git.openjdk.org/jdk/pull/28684#discussion_r2661912045
