# HG changeset patch # User mhaupt # Date 1456208274 -3600 # Node ID e71e97060bf5de07aa252a56c5671705b69e1e53 # Parent 00ec08e93b0c09c3d94bbdf61b196096f6146138 8150360: augment/correct MethodHandle API documentation Reviewed-by: psandoz diff -r 00ec08e93b0c -r e71e97060bf5 jdk/src/java.base/share/classes/java/lang/invoke/MethodHandle.java --- a/jdk/src/java.base/share/classes/java/lang/invoke/MethodHandle.java Tue Feb 23 09:52:56 2016 +0800 +++ b/jdk/src/java.base/share/classes/java/lang/invoke/MethodHandle.java Tue Feb 23 07:17:54 2016 +0100 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2008, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -1026,6 +1026,9 @@ .asCollector(long[].class, 1); assertEquals("[123]", (String) longsToString.invokeExact((long)123)); * } + *

+ * Note: The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector + * variable-arity method handle}, even if the original target method handle was. * @param arrayType often {@code Object[]}, the type of the array argument which will collect the arguments * @param arrayLength the number of arguments to collect into a new array argument * @return a new method handle which collects some trailing argument @@ -1067,6 +1070,9 @@ swWrite4.invoke('W', 'X', 'Y', 'Z', 3, 1); assertEquals("BCPQRSZ", swr.toString()); * } + *

+ * Note: The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector + * variable-arity method handle}, even if the original target method handle was. * @param collectArgPos the zero-based position in the parameter list at which to start collecting. * @param arrayType often {@code Object[]}, the type of the array argument which will collect the arguments * @param arrayLength the number of arguments to collect into a new array argument @@ -1356,8 +1362,11 @@ * The reference {@code 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: Because method handles are immutable, the target method handle + * retains its original type and behavior. + *

+ * Note: The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector + * variable-arity method handle}, even if the original target method handle was. * @param x the value to bind to the first argument of the target * @return a new method handle which prepends the given value to the incoming * argument list, before calling the original method handle diff -r 00ec08e93b0c -r e71e97060bf5 jdk/src/java.base/share/classes/java/lang/invoke/MethodHandles.java --- a/jdk/src/java.base/share/classes/java/lang/invoke/MethodHandles.java Tue Feb 23 09:52:56 2016 +0800 +++ b/jdk/src/java.base/share/classes/java/lang/invoke/MethodHandles.java Tue Feb 23 07:17:54 2016 +0100 @@ -2139,7 +2139,7 @@ * 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}. * 

{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
@@ -2157,6 +2157,9 @@
 assert(twice.type().equals(intfn1));
 assert((int)twice.invokeExact(21) == 42);
      * }
+ *

+ * Note: 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 @@ -2421,6 +2424,9 @@ * It may range between zero and N-L (inclusively), * where N is the arity of the target method handle * and L is the length of the values array. + *

+ * Note: 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 @@ -2647,6 +2653,9 @@ * return target(p..., f[i](v[i])..., b...); * } * } + *

+ * Note: 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 @@ -2791,6 +2800,9 @@ * 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. + *

+ * Note: 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, @@ -2887,6 +2899,9 @@ * filter3(v); * } * } + *

+ * Note: 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 @@ -2981,6 +2996,9 @@ * return target2(a..., b...); * } * } + *

+ * Note: 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 @@ -3828,8 +3846,9 @@ * (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.) *

- * The {@code target} and {@code cleanup} handles' return types must be the same. Their parameter type lists also - * must be the same, but the {@code cleanup} handle must accept one or two more leading parameters: