Re: 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  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.
+ * 
+ * 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,

Re: RFR 8198889 Clarify the throwing of exceptions from ConstantBootstraps.invoke

[Lance Andersen]

Changes look reasonable Paul…

Best
Lance
> On Mar 13, 2018, at 2:37 PM, 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  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.
> + * 
> + * 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,
> 

 
  

 Lance Andersen| 
Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
lance.ander...@oracle.com