RFR 8198889 Clarify the throwing of exceptions from ConstantBootstraps.invoke

[mandy chung]

+1

Mandy

On 3/13/18 11:37 AM, Paul Sandoz wrote:
> Hi,
>
> Please review these minor tweaks to the specification of ConstantBootstraps.invoke to clarify the throwing of exceptions. This was the result of discussion with the JCK team.
>
> A CSR has also been filed and requires a reviewer.
>
>    https://bugs.openjdk.java.net/browse/JDK-8199540
>
> Thanks,
> Paul.
>
> diff -r 7c795d301dbf src/java.base/share/classes/java/lang/invoke/ConstantBootstraps.java
> --- a/src/java.base/share/classes/java/lang/invoke/ConstantBootstraps.java	Mon Mar 12 16:09:18 2018 -0700
> +++ b/src/java.base/share/classes/java/lang/invoke/ConstantBootstraps.java	Tue Mar 13 11:27:34 2018 -0700
> @@ -104,10 +104,10 @@
>        *
>        * @param lookup the lookup context describing the class performing the
>        * operation (normally stacked by the JVM)
> +     * @param name the name of the constant to return, which must exactly match
> +     * an enum constant in the specified type.
>        * @param type the {@code Class} object describing the enum type for which
>        * a constant is to be returned
> -     * @param name the name of the constant to return, which must exactly match
> -     * an enum constant in the specified type.
>        * @param <E> The enum type for which a constant value is to be returned
>        * @return the enum constant of the specified enum type with the
>        * specified name
> @@ -208,20 +208,25 @@
>       /**
>        * Returns the result of invoking a method handle with the provided
>        * arguments.
> +     * <p>
> +     * This method behaves as if the method handle to be invoked is the result
> +     * of adapting the given method handle, via {@link MethodHandle#asType}, to
> +     * adjust the return type to the desired type.
>        *
>        * @param lookup unused
>        * @param name unused
> -     * @param type the type of the value to be returned, which must be
> +     * @param type the desired type of the value to be returned, which must be
>        * compatible with the return type of the method handle
>        * @param handle the method handle to be invoked
>        * @param args the arguments to pass to the method handle, as if with
>        * {@link MethodHandle#invokeWithArguments}.  Each argument may be
>        * {@code null}.
>        * @return the result of invoking the method handle
> -     * @throws WrongMethodTypeException if the handle's return type cannot be
> -     * adjusted to the desired type
> -     * @throws ClassCastException if an argument cannot be converted by
> -     * reference casting
> +     * @throws WrongMethodTypeException if the handle's method type cannot be
> +     * adjusted to take the given number of arguments, or if the handle's return
> +     * type cannot be adjusted to the desired type
> +     * @throws ClassCastException if an argument or the result produced by
> +     * invoking the handle cannot be converted by reference casting
>        * @throws Throwable anything thrown by the method handle invocation
>        */
>       public static Object invoke(MethodHandles.Lookup lookup, String name, Class<?> type,
>