Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8150360

augment/correct MethodHandle API documentation

    XMLWordPrintable

Details

    • b108
    • Not verified

    Description

      These two excerpts from the documentation of MethodHandles.tryFinally() contradict each other:

      "The pseudocode for the resulting adapter looks as follows. In the code, {@code V} represents the result type of the {@code try/finally} construct; {@code A}/{@code a}, the types and values of arguments to the resulting handle consumed by the cleanup; and {@code B}/{@code b}, those of arguments to the resulting handle discarded by the cleanup."

      "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"

      Also, several handle combinators' documentation should be extended with this hint:

      + * <p>
      + * Note: The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
      + * variable-arity method handle}, even if the original target method handle was.

      This applies to MH.bindTo(), MHs.insertArguments(), MHs.filterArguments(), MHs.filterReturnValue(), and any other combinator which (usually) leaves a trailing argument list invariant, and therefore may surprise users when it produces a non-varargs output from a varargs input.

      Attachments

        Issue Links

          Activity

            People

              mhaupt Michael Haupt
              mhaupt Michael Haupt
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: