jdk-sandbox: comparison jdk/src/java.base/share/classes/java/lang/invoke/MethodHandles.java

equal deleted inserted replaced

-:00ec08e93b0c
+:e71e97060bf5
 * An incoming argument will be duplicated if its index appears
 * more than once in the array, and an incoming argument will be dropped
 * if its index does not appear in the array.
 * As in the case of {@link #dropArguments(MethodHandle,int,List) dropArguments},
 * incoming arguments which are not mentioned in the reordering array
-* are may be any type, as determined only by {@code newType}.
+* may be of any type, as determined only by {@code newType}.
 * <blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodType intfn1 = methodType(int.class, int.class);
 assert(add.type().equals(intfn2));
 MethodHandle twice = permuteArguments(add, intfn1, 0, 0);
 assert(twice.type().equals(intfn1));
 assert((int)twice.invokeExact(21) == 42);
 * }</pre></blockquote>
+* <p>
+* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
+* variable-arity method handle}, even if the original target method handle was.
 * @param target the method handle to invoke after arguments are reordered
 * @param newType the expected type of the new method handle
 * @param reorder an index array which controls the reordering
 * @return a method handle which delegates to the target after it
 *           drops unused arguments and moves and/or duplicates the other arguments
 * <p>
 * The {@code pos} argument selects which parameters are to be bound.
 * It may range between zero and <i>N-L</i> (inclusively),
 * where <i>N</i> is the arity of the target method handle
 * and <i>L</i> is the length of the values array.
+* <p>
+* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
+* variable-arity method handle}, even if the original target method handle was.
 * @param target the method handle to invoke after the argument is inserted
 * @param pos where to insert the argument (zero for the first)
 * @param values the series of arguments to insert
 * @return a method handle which inserts an additional argument,
 *         before calling the original method handle
 * A[i] filter[i](V[i]);
 * T adapter(P... p, V[i]... v[i], B... b) {
 *   return target(p..., f[i](v[i])..., b...);
 * }
 * }</pre></blockquote>
+* <p>
+* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
+* variable-arity method handle}, even if the original target method handle was.
 *
 * @param target the method handle to invoke after arguments are filtered
 * @param pos the position of the first argument to filter
 * @param filters method handles to call initially on filtered arguments
 * @return method handle which incorporates the specified argument filtering logic
 * is equivalent to {@code filterReturnValue(coll, mh)}.
 * If the filter method handle {@code coll} consumes one argument and produces
 * a non-void result, then {@code collectArguments(mh, N, coll)}
 * is equivalent to {@code filterArguments(mh, N, coll)}.
 * Other equivalences are possible but would require argument permutation.
+* <p>
+* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
+* variable-arity method handle}, even if the original target method handle was.
 *
 * @param target the method handle to invoke after filtering the subsequence of arguments
 * @param pos the position of the first adapter argument to pass to the filter,
 *            and/or the target argument which receives the result of the filter
 * @param filter method handle to call on the subsequence of arguments
 * void adapter3(A... a) {
 *   V v = target3(a...);
 *   filter3(v);
 * }
 * }</pre></blockquote>
+* <p>
+* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
+* variable-arity method handle}, even if the original target method handle was.
 * @param target the method handle to invoke before filtering the return value
 * @param filter method handle to call on the return value
 * @return method handle which incorporates the specified return value filtering logic
 * @throws NullPointerException if either argument is null
 * @throws IllegalArgumentException if the argument list of {@code filter}
 * T adapter2(A... a, B... b) {
 *   combiner2(a...);
 *   return target2(a..., b...);
 * }
 * }</pre></blockquote>
+* <p>
+* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
+* variable-arity method handle}, even if the original target method handle was.
 * @param target the method handle to invoke after arguments are combined
 * @param combiner method handle to call initially on the incoming arguments
 * @return method handle which incorporates the specified argument folding logic
 * @throws NullPointerException if either argument is null
 * @throws IllegalArgumentException if {@code combiner}'s return type
 * a {@code null}, zero, or {@code false} value of the required type is supplied as a placeholder.
 * The second argument is not present if the {@code target} handle has a {@code void} return type.
 * (Note that, except for argument type conversions, combinators represent {@code void} values in parameter lists
 * by omitting the corresponding paradoxical arguments, not by inserting {@code null} or zero values.)
 * <p>
-* The {@code target} and {@code cleanup} handles' return types must be the same. Their parameter type lists also
+* The {@code target} and {@code cleanup} handles must have the same corresponding argument and return types, except
-* must be the same, but the {@code cleanup} handle must accept one or two more leading parameters:<ul>
+* that the {@code cleanup} handle may omit trailing arguments. Also, the {@code cleanup} handle must have one or
+* two extra leading parameters:<ul>
 * <li>a {@code Throwable}, which will carry the exception thrown by the {@code target} handle (if any); and
 * <li>a parameter of the same type as the return type of both {@code target} and {@code cleanup}, which will carry
 * the result from the execution of the {@code target} handle.
 * This parameter is not present if the {@code target} returns {@code void}.
 * </ul>
 * T adapter2(Z... z, A... a, B... b) {
 *   combiner2(a...);
 *   return target2(z..., a..., b...);
 * }
 * }</pre></blockquote>
+* <p>
+* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
+* variable-arity method handle}, even if the original target method handle was.
 *
 * @param target the method handle to invoke after arguments are combined
 * @param pos the position at which to start folding and at which to insert the folding result; if this is {@code
 *            0}, the effect is the same as for {@link #foldArguments(MethodHandle, MethodHandle)}.
 * @param combiner method handle to call initially on the incoming arguments

changeset 36112	e71e97060bf5
parent 35772	044f660251cc
child 36114	a5ed9456c9be