Summary

Fix the self-contradictory specification in java.lang.invoke.ConstantBoostraps::explicitCast when value is null and dstType is primitive.

Problem

Parts of the specification of explicitCast, including one paragraph and the @throws clause, indicate ClassCastException is thrown for a null value and a primitive dstType. This is contradictory to the "The result is the same as when using the following code" block below and the actual behavior, which returns the zero value of the primitive type instead.

Solution

Correct the wrong parts of the specification to eliminate this contradiction, using the specified "following code" behavior uniformly, which is already the long-standing implementation behavior.

Specification

--- a/src/java.base/share/classes/java/lang/invoke/ConstantBootstraps.java
+++ b/src/java.base/share/classes/java/lang/invoke/ConstantBootstraps.java
@@ -373,13 +373,14 @@ public static VarHandle arrayVarHandle(MethodHandles.Lookup lookup, String name,
      *     {@code dstType}, or, if {@code dstType} is {@code boolean},
      *     to {@code int}, which is then converted to either {@code true}
      *     or {@code false} depending on whether the least-significant-bit
-     *     is 1 or 0 respectively. If the runtime type of {@code value} is
-     *     not a primitive wrapper type a {@link ClassCastException} is thrown.
+     *     is 1 or 0 respectively.  If {@code value} is null, the zero value for
+     *     the {@code dstType} is returned.  Otherwise, a {@link ClassCastException}
+     *     is thrown.
      * </ol>
      * <p>
      * The result is the same as when using the following code:
@@ -397,8 +398,8 @@ public static VarHandle arrayVarHandle(MethodHandles.Lookup lookup, String name,
      * @return the converted value
      * @throws ClassCastException when {@code dstType} is {@code void},
      *         when a cast per (1) fails, or when {@code dstType} is a primitive type
-     *         and the runtime type of {@code value} is not a primitive wrapper type
-     *         (such as {@link Integer})
+     *         and {@code value} is not null and its runtime type is not a primitive
+     *         wrapper type (such as {@link Integer})
      *
      * @since 15
      */