Summary

The proposed change is to explicitly state that IllegalArgumentException is thrown when MethodHandle's type would have parameters exceeding maxarity (255).

Problem

Many adapter methods of MethodHandles class explicitly specify IllegalArgumentException if the constraint is violated, but some don't.

The following methods in MethodHandles class don't explicitly specify that IllegalArgumentException will be thrown on violation of arity limits.

dropArgumentsToMatch,
empty,
explicitCastArguments,
permuteArguments,
varHandleInvoker,
varHandleExactInvoker,
exactInvoker,
invoker,
spreadInvoker.

Solution

Make the documentation more explicit about the implemented behavior.

Specification

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

@@ -71,6 +71,9 @@
   * <li>Combinator methods, which combine or transform pre-existing method handles into new ones.
   * <li>Other factory methods to create method handles that emulate other common JVM operations or control flow patterns.
   * </ul>
+  * A lookup, combinator, or factory method will fail and throw an
+  * {@code IllegalArgumentException} if the created method handle's type
+  * would have <a href="MethodHandle.html#maxarity">too many parameters</a>.
   *
   * @author John Rose, JSR 292 EG
   * @since 1.7

@@ -386,8 +389,9 @@
   * constant is not subject to security manager checks.
   * <li>If the looked-up method has a
   * <a href="MethodHandle.html#maxarity">very large arity</a>,
-  * the method handle creation may fail, due to the method handle
-  * type having too many parameters.
+  * the method handle creation may fail with an
+  * {@code IllegalArgumentException}, due to the method handle type having
+  * <a href="MethodHandle.html#maxarity">too many parameters.</a>
   * </ul>
   *