8177276: MethodHandles.insertArguments doesn't specify IllegalArgumentException on index mismatch

Correct MethodHandles.insertArguments spec

Reviewed-by: psandoz, mchung, ntv

src/java.base/share/classes/java/lang/invoke/MethodHandles.java

@@ -3483,6 +3483,11 @@ assert((int)twice.invokeExact(21) == 42);
      * @return a method handle which inserts an additional argument,
      *         before calling the original method handle
      * @throws NullPointerException if the target or the {@code values} array is null
+     * @throws IllegalArgumentException if (@code pos) is less than {@code 0} or greater than
+     *         {@code N - L} where {@code N} is the arity of the target method handle and {@code L}
+     *         is the length of the values array.
+     * @throws ClassCastException if an argument does not match the corresponding bound parameter
+     *         type.
      * @see MethodHandle#bindTo
      */
     public static

test/jdk/java/lang/invoke/MethodHandlesInsertArgumentsTest.java

@@ -42,6 +42,8 @@ import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 
+import static java.lang.invoke.MethodType.methodType;
+
 import static org.junit.Assert.*;
 
 public class MethodHandlesInsertArgumentsTest extends MethodHandlesTest {
@@ -88,4 +90,43 @@ public class MethodHandlesInsertArgumentsTest extends MethodHandlesTest {
             System.out.println("result: "+res2List);
         assertEquals(resList, res2List);
     }
+
+    private static MethodHandle methodHandle = null;
+    static {
+        try {
+            methodHandle = MethodHandles.lookup().findVirtual(
+                                               MethodHandlesInsertArgumentsTest.class,
+                                               "testMethod",
+                                               methodType(void.class, String.class, String.class));
+        } catch(ReflectiveOperationException ex) {
+            throw new InternalError(ex);
+        }
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testInsertArgumentsInvalidPos() {
+        countTest();
+        MethodHandles.insertArguments(methodHandle, -1, "First", "Second");
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testInsertArgumentsTooManyParams() {
+        countTest();
+        MethodHandles.insertArguments(methodHandle, 1, "First", "Second", "Third");
+    }
+
+    @Test(expected = ClassCastException.class)
+    public void testInsertArgumentsPosZero() {
+        countTest();
+        MethodHandles.insertArguments(methodHandle, 0, "First");
+    }
+
+    @Test(expected = ClassCastException.class)
+    public void testInsertArgumentsIncorrectParam() {
+        countTest();
+        MethodHandles.insertArguments(methodHandle, 1, "First", new Object());
+    }
+
+    void testMethod(String a, String b) {
+    }
 }