When this method is observed via the Core Reflection API, it will appear as a single native method, taking an object array and returning an object. If this native method is invoked directly via java.lang.reflect.Method.invoke, via JNI, or indirectly via Lookup.unreflect, it will throw an UnsupportedOperationException.

If the call site's symbolic type descriptor exactly matches this method handle's type, the call proceeds as if by invokeExact.

Otherwise, the call proceeds as if this method handle were first adjusted by calling asType to adjust this method handle to the required type, and then the call proceeds as if by invokeExact on the adjusted method handle.

There is no guarantee that the asType call is actually made. If the JVM can predict the results of making the call, it may perform adaptations directly on the caller's arguments, and call the target method handle according to its own exact type.

The resolved type descriptor at the call site of invoke must be a valid argument to the receivers asType method. In particular, the caller must specify the same argument arity as the callee's type, if the callee is not a variable arity collector.

When this method is observed via the Core Reflection API, it will appear as a single native method, taking an object array and returning an object. If this native method is invoked directly via java.lang.reflect.Method.invoke, via JNI, or indirectly via Lookup.unreflect, it will throw an UnsupportedOperationException.

Specifically, execution proceeds as if by the following steps, although the methods are not guaranteed to be called if the JVM can predict their effects.

• Determine the length of the argument array as N. For a null reference, N=0.
• Collect the N elements of the array as a logical argument list, each argument statically typed as an Object.
• Determine, as M, the parameter count of the type of this method handle.
• Determine the general type TN of N arguments or M arguments, if smaller than N, as TN=MethodType.genericMethodType(Math.min(N, M)).
• If N is greater than M, perform the following checks and actions to shorten the logical argument list:
  • Check that this method handle has variable arity with a trailing parameter of some array type A[]. If not, fail with a WrongMethodTypeException.
  • Collect the trailing elements (there are N-M+1 of them) from the logical argument list into a single array of type A[], using asType conversions to convert each trailing argument to type A.
  • If any of these conversions proves impossible, fail with either a ClassCastException if any trailing element cannot be cast to A or a NullPointerException if any trailing element is null and A is not a reference type.
  • Replace the logical arguments gathered into the array of type A[] with the array itself, thus shortening the argument list to length M. This final argument retains the static type A[].
  • Adjust the type TN by changing the Nth parameter type from Object to A[].
• Force the original target method handle MH0 to the required type, as MH1 = MH0.asType(TN).
• Spread the argument list into N separate arguments A0, ....
• Invoke the type-adjusted method handle on the unpacked arguments: MH1.invokeExact(A0, ...).
• Take the return value as an Object reference.

If the target method handle has variable arity, and the argument list is longer than that arity, the excess arguments, starting at the position of the trailing array argument, will be gathered (if possible, as if by asType conversions) into an array of the appropriate type, and invocation will proceed on the shortened argument list. In this way, jumbo argument lists which would spread into more than 254 slots can still be processed uniformly.

Unlike the generic invocation mode, which can "recycle" an array argument, passing it directly to the target method, this invocation mode always creates a new array parameter, even if the original array passed to invokeWithArguments would have been acceptable as a direct argument to the target method. Even if the number M of actual arguments is the arity N, and the last argument is dynamically a suitable array of type A[], it will still be boxed into a new one-element array, since the call site statically types the argument as Object, not an array type. This is not a special rule for this method, but rather a regular effect of the rules for variable-arity invocation.

Because of the action of the asType step, the following argument conversions are applied as necessary:

• reference casting
• unboxing
• widening primitive conversions
• variable arity conversion

The result returned by the call is boxed if it is a primitive, or forced to null if the return type is void.

Unlike the signature polymorphic methods invokeExact and invoke, invokeWithArguments can be accessed normally via the Core Reflection API and JNI. It can therefore be used as a bridge between native or reflective code and method handles.

This method is also equivalent to the following code:

Copy

  invokeWithArguments(arguments.toArray())

Jumbo-sized lists are acceptable if this method handle has variable arity. See invokeWithArguments(Object[]) for details.

If the original type and new type are equal, returns this.

The new method handle, when invoked, will perform the following steps:

• Convert the incoming argument list to match the original method handle's argument list.
• Invoke the original method handle on the converted argument list.
• Convert any result returned by the original method handle to the return type of new method handle.

This method provides the crucial behavioral difference between invokeExact and plain, inexact invoke. The two methods perform the same steps when the caller's type descriptor exactly matches the callee's, but when the types differ, plain invoke also calls asType (or some internal equivalent) in order to match up the caller's and callee's types.

If the current method is a variable arity method handle argument list conversion may involve the conversion and collection of several arguments into an array, as described elsewhere. In every other case, all conversions are applied pairwise, which means that each argument or return value is converted to exactly one argument or return value (or no return value). The applied conversions are defined by consulting the corresponding component types of the old and new method handle types.

Let T0 and T1 be corresponding new and old parameter types, or old and new return types. Specifically, for some valid index i, let T0=newType.parameterType(i) and T1=this.type().parameterType(i). Or else, going the other way for return values, let T0=this.type().returnType() and T1=newType.returnType(). If the types are the same, the new method handle makes no change to the corresponding argument or return value (if any). Otherwise, one of the following conversions is applied if possible:

• If T0 and T1 are references, then a cast to T1 is applied. (The types do not need to be related in any particular way. This is because a dynamic value of null can convert to any reference type.)
• If T0 and T1 are primitives, then a Java method invocation conversion (JLS 5.3) is applied, if one exists. (Specifically, T0 must convert to T1 by a widening primitive conversion.)
• If T0 is a primitive and T1 a reference, a Java casting conversion (JLS 5.5) is applied if one exists. (Specifically, the value is boxed from T0 to its wrapper class, which is then widened as needed to T1.)
• If T0 is a reference and T1 a primitive, an unboxing conversion will be applied at runtime, possibly followed by a Java method invocation conversion (JLS 5.3) on the primitive value. (These are the primitive widening conversions.) T0 must be a wrapper class or a supertype of one. (In the case where T0 is Object, these are the conversions allowed by java.lang.reflect.Method.invoke.) The unboxing conversion must have a possibility of success, which means that if T0 is not itself a wrapper class, there must exist at least one wrapper class TW which is a subtype of T0 and whose unboxed primitive value can be widened to T1.
• If the return type T1 is marked as void, any returned value is discarded
• If the return type T0 is void and T1 a reference, a null value is introduced.
• If the return type T0 is void and T1 a primitive, a zero value is introduced.

The method handle conversion cannot be made if any one of the required pairwise conversions cannot be made.

At runtime, the conversions applied to reference arguments or return values may require additional runtime checks which can fail. An unboxing operation may fail because the original reference is null, causing a NullPointerException. An unboxing operation or a reference cast may also fail on a reference to an object of the wrong type, causing a ClassCastException. Although an unboxing operation may accept several kinds of wrappers, if none are available, a ClassCastException will be thrown.

If the array element type differs from any of the corresponding argument types on the original target, the original target is adapted to take the array elements directly, as if by a call to asType.

When called, the adapter replaces a trailing array argument by the array's elements, each as its own argument to the target. (The order of the arguments is preserved.) They are converted pairwise by casting and/or unboxing to the types of the trailing parameters of the target. Finally the target is called. What the target eventually returns is returned unchanged by the adapter.

Before calling the target, the adapter verifies that the array contains exactly enough elements to provide a correct argument count to the target method handle. (The array may also be null when zero elements are required.)

When the adapter is called, the length of the supplied array argument is queried as if by array.length or arraylength bytecode. If the adapter accepts a zero-length trailing array argument, the supplied array argument can either be a zero-length array or null; otherwise, the adapter will throw a NullPointerException if the array is null and throw an IllegalArgumentException if the array does not have the correct number of elements.

Here are some simple examples of array-spreading method handles:

Copy

MethodHandle equals = publicLookup()
  .findVirtual(String.class, "equals", methodType(boolean.class, Object.class));
assert( (boolean) equals.invokeExact("me", (Object)"me"));
assert(!(boolean) equals.invokeExact("me", (Object)"thee"));
// spread both arguments from a 2-array:
MethodHandle eq2 = equals.asSpreader(Object[].class, 2);
assert( (boolean) eq2.invokeExact(new Object[]{ "me", "me" }));
assert(!(boolean) eq2.invokeExact(new Object[]{ "me", "thee" }));
// try to spread from anything but a 2-array:
for (int n = 0; n <= 10; n++) {
  Object[] badArityArgs = (n == 2 ? new Object[0] : new Object[n]);
  try { assert((boolean) eq2.invokeExact(badArityArgs) && false); }
  catch (IllegalArgumentException ex) { } // OK
}
// spread both arguments from a String array:
MethodHandle eq2s = equals.asSpreader(String[].class, 2);
assert( (boolean) eq2s.invokeExact(new String[]{ "me", "me" }));
assert(!(boolean) eq2s.invokeExact(new String[]{ "me", "thee" }));
// spread second arguments from a 1-array:
MethodHandle eq1 = equals.asSpreader(Object[].class, 1);
assert( (boolean) eq1.invokeExact("me", new Object[]{ "me" }));
assert(!(boolean) eq1.invokeExact("me", new Object[]{ "thee" }));
// spread no arguments from a 0-array or null:
MethodHandle eq0 = equals.asSpreader(Object[].class, 0);
assert( (boolean) eq0.invokeExact("me", (Object)"me", new Object[0]));
assert(!(boolean) eq0.invokeExact("me", (Object)"thee", (Object[])null));
// asSpreader and asCollector are approximate inverses:
for (int n = 0; n <= 2; n++) {
    for (Class<?> a : new Class<?>[]{Object[].class, String[].class, CharSequence[].class}) {
        MethodHandle equals2 = equals.asSpreader(a, n).asCollector(a, n);
        assert( (boolean) equals2.invokeWithArguments("me", "me"));
        assert(!(boolean) equals2.invokeWithArguments("me", "thee"));
    }
}
MethodHandle caToString = publicLookup()
  .findStatic(Arrays.class, "toString", methodType(String.class, char[].class));
assertEquals("[A, B, C]", (String) caToString.invokeExact("ABC".toCharArray()));
MethodHandle caString3 = caToString.asCollector(char[].class, 3);
assertEquals("[A, B, C]", (String) caString3.invokeExact('A', 'B', 'C'));
MethodHandle caToString2 = caString3.asSpreader(char[].class, 2);
assertEquals("[A, B, C]", (String) caToString2.invokeExact('A', "BC".toCharArray()));

This method behaves very much like asSpreader(Class, int), but accepts an additional spreadArgPos argument to indicate at which position in the parameter list the spreading should take place.

If the array type differs from the final argument type on the original target, the original target is adapted to take the array type directly, as if by a call to asType.

When called, the adapter replaces its trailing arrayLength arguments by a single new array of type arrayType, whose elements comprise (in order) the replaced arguments. Finally the target is called. What the target eventually returns is returned unchanged by the adapter.

(The array may also be a shared constant when arrayLength is zero.)

(Note: The arrayType is often identical to the last parameter type of the original target. It is an explicit argument for symmetry with asSpreader, and also to allow the target to use a simple Object as its last parameter type.)

In order to create a collecting adapter which is not restricted to a particular number of collected arguments, use asVarargsCollector or withVarargs instead.

Here are some examples of array-collecting method handles:

Copy

MethodHandle deepToString = publicLookup()
  .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
assertEquals("[won]",   (String) deepToString.invokeExact(new Object[]{"won"}));
MethodHandle ts1 = deepToString.asCollector(Object[].class, 1);
assertEquals(methodType(String.class, Object.class), ts1.type());
//assertEquals("[won]", (String) ts1.invokeExact(         new Object[]{"won"})); //FAIL
assertEquals("[[won]]", (String) ts1.invokeExact((Object) new Object[]{"won"}));
// arrayType can be a subtype of Object[]
MethodHandle ts2 = deepToString.asCollector(String[].class, 2);
assertEquals(methodType(String.class, String.class, String.class), ts2.type());
assertEquals("[two, too]", (String) ts2.invokeExact("two", "too"));
MethodHandle ts0 = deepToString.asCollector(Object[].class, 0);
assertEquals("[]", (String) ts0.invokeExact());
// collectors can be nested, Lisp-style
MethodHandle ts22 = deepToString.asCollector(Object[].class, 3).asCollector(String[].class, 2);
assertEquals("[A, B, [C, D]]", ((String) ts22.invokeExact((Object)'A', (Object)"B", "C", "D")));
// arrayType can be any primitive array type
MethodHandle bytesToString = publicLookup()
  .findStatic(Arrays.class, "toString", methodType(String.class, byte[].class))
  .asCollector(byte[].class, 3);
assertEquals("[1, 2, 3]", (String) bytesToString.invokeExact((byte)1, (byte)2, (byte)3));
MethodHandle longsToString = publicLookup()
  .findStatic(Arrays.class, "toString", methodType(String.class, long[].class))
  .asCollector(long[].class, 1);
assertEquals("[123]", (String) longsToString.invokeExact((long)123));

Note: The resulting adapter is never a variable-arity method handle, even if the original target method handle was.

This method behaves very much like asCollector(Class, int), but differs in that its collectArgPos argument indicates at which position in the parameter list arguments should be collected. This index is zero-based.

The type and behavior of the adapter will be the same as the type and behavior of the target, except that certain invoke and asType requests can lead to trailing positional arguments being collected into target's trailing parameter. Also, the last parameter type of the adapter will be arrayType, even if the target has a different last parameter type.

This transformation may return this if the method handle is already of variable arity and its trailing parameter type is identical to arrayType.

When called with invokeExact, the adapter invokes the target with no argument changes. (Note: This behavior is different from a fixed arity collector, since it accepts a whole array of indeterminate length, rather than a fixed number of arguments.)

When called with plain, inexact invoke, if the caller type is the same as the adapter, the adapter invokes the target as with invokeExact. (This is the normal behavior for invoke when types match.)

Otherwise, if the caller and adapter arity are the same, and the trailing parameter type of the caller is a reference type identical to or assignable to the trailing parameter type of the adapter, the arguments and return values are converted pairwise, as if by asType on a fixed arity method handle.

Otherwise, the arities differ, or the adapter's trailing parameter type is not assignable from the corresponding caller type. In this case, the adapter replaces all trailing arguments from the original trailing argument position onward, by a new array of type arrayType, whose elements comprise (in order) the replaced arguments.

The caller type must provide at least enough arguments, and of the correct type, to satisfy the target's requirement for positional arguments before the trailing array argument. Thus, the caller must supply, at a minimum, N-1 arguments, where N is the arity of the target. Also, there must exist conversions from the incoming arguments to the target's arguments. As with other uses of plain invoke, if these basic requirements are not fulfilled, a WrongMethodTypeException may be thrown.

In all cases, what the target eventually returns is returned unchanged by the adapter.

In the final case, it is exactly as if the target method handle were temporarily adapted with a fixed arity collector to the arity required by the caller type. (As with asCollector, if the array length is zero, a shared constant may be used instead of a new array. If the implied call to asCollector would throw an IllegalArgumentException or WrongMethodTypeException, the call to the variable arity adapter must throw WrongMethodTypeException.)

The behavior of asType is also specialized for variable arity adapters, to maintain the invariant that plain, inexact invoke is always equivalent to an asType call to adjust the target type, followed by invokeExact. Therefore, a variable arity adapter responds to an asType request by building a fixed arity collector, if and only if the adapter and requested type differ either in arity or trailing argument type. The resulting fixed arity collector has its type further adjusted (if necessary) to the requested type by pairwise conversion, as if by another application of asType.

When a method handle is obtained by executing an ldc instruction of a CONSTANT_MethodHandle constant, and the target method is marked as a variable arity method (with the modifier bit 0x0080), the method handle will accept multiple arities, as if the method handle constant were created by means of a call to asVarargsCollector.

In order to create a collecting adapter which collects a predetermined number of arguments, and whose type reflects this predetermined number, use asCollector instead.

No method handle transformations produce new method handles with variable arity, unless they are documented as doing so. Therefore, besides asVarargsCollector and withVarargs, all methods in MethodHandle and MethodHandles will return a method handle with fixed arity, except in the cases where they are specified to return their original operand (e.g., asType of the method handle's own type).

Calling asVarargsCollector on a method handle which is already of variable arity will produce a method handle with the same type and behavior. It may (or may not) return the original variable arity method handle.

Here is an example, of a list-making variable arity method handle:

Copy

MethodHandle deepToString = publicLookup()
  .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
MethodHandle ts1 = deepToString.asVarargsCollector(Object[].class);
assertEquals("[won]",   (String) ts1.invokeExact(    new Object[]{"won"}));
assertEquals("[won]",   (String) ts1.invoke(         new Object[]{"won"}));
assertEquals("[won]",   (String) ts1.invoke(                      "won" ));
assertEquals("[[won]]", (String) ts1.invoke((Object) new Object[]{"won"}));
// findStatic of Arrays.asList(...) produces a variable arity method handle:
MethodHandle asList = publicLookup()
  .findStatic(Arrays.class, "asList", methodType(List.class, Object[].class));
assertEquals(methodType(List.class, Object[].class), asList.type());
assert(asList.isVarargsCollector());
assertEquals("[]", asList.invoke().toString());
assertEquals("[1]", asList.invoke(1).toString());
assertEquals("[two, too]", asList.invoke("two", "too").toString());
String[] argv = { "three", "thee", "tee" };
assertEquals("[three, thee, tee]", asList.invoke(argv).toString());
assertEquals("[three, thee, tee]", asList.invoke((Object[])argv).toString());
List ls = (List) asList.invoke((Object)argv);
assertEquals(1, ls.size());
assertEquals("[three, thee, tee]", Arrays.toString((Object[])ls.get(0)));

Discussion: These rules are designed as a dynamically-typed variation of the Java rules for variable arity methods. In both cases, callers to a variable arity method or method handle can either pass zero or more positional arguments, or else pass pre-collected arrays of any length. Users should be aware of the special role of the final argument, and of the effect of a type match on that final argument, which determines whether or not a single trailing argument is interpreted as a whole array or a single element of an array to be collected. Note that the dynamic type of the trailing argument has no effect on this decision, only a comparison between the symbolic type descriptor of the call site and the type descriptor of the method handle.

• a call to asVarargsCollector
• a call to a lookup method which resolves to a variable arity Java method or constructor
• an ldc instruction of a CONSTANT_MethodHandle which resolves to a variable arity Java method or constructor

If the current method handle is not of variable arity, the current method handle is returned. This is true even if the current method handle could not be a valid input to asVarargsCollector.

Otherwise, the resulting fixed-arity method handle has the same type and behavior of the current method handle, except that isVarargsCollector will be false. The fixed-arity method handle may (or may not) be the previous argument to asVarargsCollector.

Here is an example, of a list-making variable arity method handle:

Copy

MethodHandle asListVar = publicLookup()
  .findStatic(Arrays.class, "asList", methodType(List.class, Object[].class))
  .asVarargsCollector(Object[].class);
MethodHandle asListFix = asListVar.asFixedArity();
assertEquals("[1]", asListVar.invoke(1).toString());
Exception caught = null;
try { asListFix.invoke((Object)1); }
catch (Exception ex) { caught = ex; }
assert(caught instanceof ClassCastException);
assertEquals("[two, too]", asListVar.invoke("two", "too").toString());
try { asListFix.invoke("two", "too"); }
catch (Exception ex) { caught = ex; }
assert(caught instanceof WrongMethodTypeException);
Object[] argv = { "three", "thee", "tee" };
assertEquals("[three, thee, tee]", asListVar.invoke(argv).toString());
assertEquals("[three, thee, tee]", asListFix.invoke(argv).toString());
assertEquals(1, ((List) asListVar.invoke((Object)argv)).size());
assertEquals("[three, thee, tee]", asListFix.invoke((Object)argv).toString());

When called, the bound handle inserts the given value x as a new leading argument to the target. The other arguments are also passed unchanged. What the target eventually returns is returned unchanged by the bound handle.

The reference x must be convertible to the first parameter type of the target.

Note: Because method handles are immutable, the target method handle retains its original type and behavior.

Note: The resulting adapter is never a variable-arity method handle, even if the original target method handle was.

Copy

"MethodHandle" + type().toString()

(Note: Future releases of this API may add further information to the string representation. Therefore, the present syntax should not be parsed by applications.)