Summary

Method java.lang.constant.MethodTypeDesc::insertParameterTypes​ throws an exception that is not documented in its specification. The specification must be updated

Problem

Specification for method java.lang.constant.MethodTypeDesc::insertParameterTypes​ should state that it throws an exception if any parameter is a class descriptor of primitive type void.

Solution

Update the specification of method java.lang.constant.MethodTypeDesc::insertParameterTypes​ to state that the method throws an exception if any parameter is a class descriptor of the primitive type void. This will make the specification of this method very similar to that of java.lang.invoke.MethodType::insertParameterTypes​.

The remaining difference will be that in the case of the last method, if the resulting MethodType have more than 255 parameter slots, then an exception is thrown. This doesn't occur for method java.lang.constant.MethodTypeDesc::insertParameterTypes as there can be instances of j.l.c.MethodTypeDesc that can converted to String even if they have more that 255 parameter slots. Nevertheless if they are resolved to a j.l.i.MethodType, an exception will be thrown. For this reason, and as a clarification, an apiNote should be added to method java.lang.constant.ConstantDesc::resolveConstantDesc stating that a MethodTypeDesc can represent method type descriptors that are not representable by j.l.i.MethodType.

Specification

diff -r b99e97bc5040 -r 2fd7d561f4e9 src/java.base/share/classes/java/lang/constant/ConstantDesc.java
--- a/src/java.base/share/classes/java/lang/constant/ConstantDesc.java  Wed May 15 08:58:23 2019 -0400
+++ b/src/java.base/share/classes/java/lang/constant/ConstantDesc.java  Wed May 15 16:38:59 2019 -0400
@@ -97,6 +97,11 @@
      * @throws ReflectiveOperationException if a class, method, or field
      * could not be reflectively resolved in the course of resolution
      * @throws LinkageError if a linkage error occurs
+     *
+     * @apiNote {@linkplain MethodTypeDesc} can represent method type descriptors that are not representable by
+     * {@linkplain MethodType}, such as methods with more than 255 parameter slots, so attempts to resolve these may
+     * result in errors.
+     *
      * @jvms 5.4.3 Resolution
      * @jvms 5.4.4 Access Control
      */
diff -r b6ee58ec8814 -r cfa9fec971db src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java
--- a/src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java        Thu May 16 13:34:33 2019 -0400
+++ b/src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java        Fri May 17 09:34:40 2019 -0400
@@ -154,9 +154,11 @@
      * @param paramTypes {@link ClassDesc}s describing the new parameter types
      *                   to insert
      * @return a {@linkplain MethodTypeDesc} describing the desired method type
-     * @throws NullPointerException if any argument is {@code null}
+     * @throws NullPointerException if any argument or its contents are {@code null}
      * @throws IndexOutOfBoundsException if {@code pos} is outside the closed
      * range {[0, parameterCount]}
+     * @throws IllegalArgumentException if any element of {@code paramTypes}
+     * is a {@link ClassDesc} for {@code void}
      */
     MethodTypeDesc insertParameterTypes(int pos, ClassDesc... paramTypes);