30 
  31 import java.util.Arrays;
  32 import java.util.Objects;
  33 
  34 import static java.lang.invoke.MethodHandleStatics.*;
  35 
  36 /**
  37  * A method handle is a typed, directly executable reference to an underlying method,
  38  * constructor, field, or similar low-level operation, with optional
  39  * transformations of arguments or return values.
  40  * These transformations are quite general, and include such patterns as
  41  * {@linkplain #asType conversion},
  42  * {@linkplain #bindTo insertion},
  43  * {@linkplain java.lang.invoke.MethodHandles#dropArguments deletion},
  44  * and {@linkplain java.lang.invoke.MethodHandles#filterArguments substitution}.
  45  *
  46  * <h1>Method handle contents</h1>
  47  * Method handles are dynamically and strongly typed according to their parameter and return types.
  48  * They are not distinguished by the name or the defining class of their underlying methods.
  49  * A method handle must be invoked using a symbolic type descriptor which matches
  50  * the method handle's own {@linkplain #type type descriptor}.
  51  * <p>
  52  * Every method handle reports its type descriptor via the {@link #type type} accessor.
  53  * This type descriptor is a {@link java.lang.invoke.MethodType MethodType} object,
  54  * whose structure is a series of classes, one of which is
  55  * the return type of the method (or {@code void.class} if none).
  56  * <p>
  57  * A method handle's type controls the types of invocations it accepts,
  58  * and the kinds of transformations that apply to it.
  59  * <p>
  60  * A method handle contains a pair of special invoker methods
  61  * called {@link #invokeExact invokeExact} and {@link #invoke invoke}.
  62  * Both invoker methods provide direct access to the method handle's
  63  * underlying method, constructor, field, or other operation,
  64  * as modified by transformations of arguments and return values.
  65  * Both invokers accept calls which exactly match the method handle's own type.
  66  * The plain, inexact invoker also accepts a range of other call types.
  67  * <p>
  68  * Method handles are immutable and have no visible state.
  69  * Of course, they can be bound to underlying methods or data which exhibit state.
  70  * With respect to the Java Memory Model, any method handle will behave
  71  * as if all of its (internal) fields are final variables.  This means that any method
  72  * handle made visible to the application will always be fully formed.

 451     public MethodType type() {
 452         return type;
 453     }
 454 
 455     /**
 456      * Package-private constructor for the method handle implementation hierarchy.
 457      * Method handle inheritance will be contained completely within
 458      * the {@code java.lang.invoke} package.
 459      */
 460     // @param type type (permanently assigned) of the new method handle
 461     /*non-public*/ MethodHandle(MethodType type, LambdaForm form) {
 462         this.type = Objects.requireNonNull(type);
 463         this.form = Objects.requireNonNull(form).uncustomize();
 464 
 465         this.form.prepare();  // TO DO:  Try to delay this step until just before invocation.
 466     }
 467 
 468     /**
 469      * Invokes the method handle, allowing any caller type descriptor, but requiring an exact type match.
 470      * The symbolic type descriptor at the call site of {@code invokeExact} must
 471      * exactly match this method handle's {@link #type type}.
 472      * No conversions are allowed on arguments or return values.
 473      * <p>
 474      * When this method is observed via the Core Reflection API,
 475      * it will appear as a single native method, taking an object array and returning an object.
 476      * If this native method is invoked directly via
 477      * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
 478      * or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
 479      * it will throw an {@code UnsupportedOperationException}.
 480      * @param args the signature-polymorphic parameter list, statically represented using varargs
 481      * @return the signature-polymorphic result, statically represented using {@code Object}
 482      * @throws WrongMethodTypeException if the target's type is not identical with the caller's symbolic type descriptor
 483      * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
 484      */
 485     @HotSpotIntrinsicCandidate
 486     public final native @PolymorphicSignature Object invokeExact(Object... args) throws Throwable;
 487 
 488     /**
 489      * Invokes the method handle, allowing any caller type descriptor,
 490      * and optionally performing conversions on arguments and return values.
 491      * <p>
 492      * If the call site's symbolic type descriptor exactly matches this method handle's {@link #type type},
 493      * the call proceeds as if by {@link #invokeExact invokeExact}.
 494      * <p>
 495      * Otherwise, the call proceeds as if this method handle were first
 496      * adjusted by calling {@link #asType asType} to adjust this method handle
 497      * to the required type, and then the call proceeds as if by
 498      * {@link #invokeExact invokeExact} on the adjusted method handle.
 499      * <p>
 500      * There is no guarantee that the {@code asType} call is actually made.
 501      * If the JVM can predict the results of making the call, it may perform
 502      * adaptations directly on the caller's arguments,
 503      * and call the target method handle according to its own exact type.
 504      * <p>
 505      * The resolved type descriptor at the call site of {@code invoke} must
 506      * be a valid argument to the receivers {@code asType} method.
 507      * In particular, the caller must specify the same argument arity
 508      * as the callee's type,
 509      * if the callee is not a {@linkplain #asVarargsCollector variable arity collector}.
 510      * <p>
 511      * When this method is observed via the Core Reflection API,
 512      * it will appear as a single native method, taking an object array and returning an object.

  30 
  31 import java.util.Arrays;
  32 import java.util.Objects;
  33 
  34 import static java.lang.invoke.MethodHandleStatics.*;
  35 
  36 /**
  37  * A method handle is a typed, directly executable reference to an underlying method,
  38  * constructor, field, or similar low-level operation, with optional
  39  * transformations of arguments or return values.
  40  * These transformations are quite general, and include such patterns as
  41  * {@linkplain #asType conversion},
  42  * {@linkplain #bindTo insertion},
  43  * {@linkplain java.lang.invoke.MethodHandles#dropArguments deletion},
  44  * and {@linkplain java.lang.invoke.MethodHandles#filterArguments substitution}.
  45  *
  46  * <h1>Method handle contents</h1>
  47  * Method handles are dynamically and strongly typed according to their parameter and return types.
  48  * They are not distinguished by the name or the defining class of their underlying methods.
  49  * A method handle must be invoked using a symbolic type descriptor which matches
  50  * the method handle's own {@linkplain #type() type descriptor}.
  51  * <p>
  52  * Every method handle reports its type descriptor via the {@link #type() type} accessor.
  53  * This type descriptor is a {@link java.lang.invoke.MethodType MethodType} object,
  54  * whose structure is a series of classes, one of which is
  55  * the return type of the method (or {@code void.class} if none).
  56  * <p>
  57  * A method handle's type controls the types of invocations it accepts,
  58  * and the kinds of transformations that apply to it.
  59  * <p>
  60  * A method handle contains a pair of special invoker methods
  61  * called {@link #invokeExact invokeExact} and {@link #invoke invoke}.
  62  * Both invoker methods provide direct access to the method handle's
  63  * underlying method, constructor, field, or other operation,
  64  * as modified by transformations of arguments and return values.
  65  * Both invokers accept calls which exactly match the method handle's own type.
  66  * The plain, inexact invoker also accepts a range of other call types.
  67  * <p>
  68  * Method handles are immutable and have no visible state.
  69  * Of course, they can be bound to underlying methods or data which exhibit state.
  70  * With respect to the Java Memory Model, any method handle will behave
  71  * as if all of its (internal) fields are final variables.  This means that any method
  72  * handle made visible to the application will always be fully formed.

 451     public MethodType type() {
 452         return type;
 453     }
 454 
 455     /**
 456      * Package-private constructor for the method handle implementation hierarchy.
 457      * Method handle inheritance will be contained completely within
 458      * the {@code java.lang.invoke} package.
 459      */
 460     // @param type type (permanently assigned) of the new method handle
 461     /*non-public*/ MethodHandle(MethodType type, LambdaForm form) {
 462         this.type = Objects.requireNonNull(type);
 463         this.form = Objects.requireNonNull(form).uncustomize();
 464 
 465         this.form.prepare();  // TO DO:  Try to delay this step until just before invocation.
 466     }
 467 
 468     /**
 469      * Invokes the method handle, allowing any caller type descriptor, but requiring an exact type match.
 470      * The symbolic type descriptor at the call site of {@code invokeExact} must
 471      * exactly match this method handle's {@link #type() type}.
 472      * No conversions are allowed on arguments or return values.
 473      * <p>
 474      * When this method is observed via the Core Reflection API,
 475      * it will appear as a single native method, taking an object array and returning an object.
 476      * If this native method is invoked directly via
 477      * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
 478      * or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
 479      * it will throw an {@code UnsupportedOperationException}.
 480      * @param args the signature-polymorphic parameter list, statically represented using varargs
 481      * @return the signature-polymorphic result, statically represented using {@code Object}
 482      * @throws WrongMethodTypeException if the target's type is not identical with the caller's symbolic type descriptor
 483      * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
 484      */
 485     @HotSpotIntrinsicCandidate
 486     public final native @PolymorphicSignature Object invokeExact(Object... args) throws Throwable;
 487 
 488     /**
 489      * Invokes the method handle, allowing any caller type descriptor,
 490      * and optionally performing conversions on arguments and return values.
 491      * <p>
 492      * If the call site's symbolic type descriptor exactly matches this method handle's {@link #type() type},
 493      * the call proceeds as if by {@link #invokeExact invokeExact}.
 494      * <p>
 495      * Otherwise, the call proceeds as if this method handle were first
 496      * adjusted by calling {@link #asType asType} to adjust this method handle
 497      * to the required type, and then the call proceeds as if by
 498      * {@link #invokeExact invokeExact} on the adjusted method handle.
 499      * <p>
 500      * There is no guarantee that the {@code asType} call is actually made.
 501      * If the JVM can predict the results of making the call, it may perform
 502      * adaptations directly on the caller's arguments,
 503      * and call the target method handle according to its own exact type.
 504      * <p>
 505      * The resolved type descriptor at the call site of {@code invoke} must
 506      * be a valid argument to the receivers {@code asType} method.
 507      * In particular, the caller must specify the same argument arity
 508      * as the callee's type,
 509      * if the callee is not a {@linkplain #asVarargsCollector variable arity collector}.
 510      * <p>
 511      * When this method is observed via the Core Reflection API,
 512      * it will appear as a single native method, taking an object array and returning an object.