10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.invoke;
27
28
29 import java.util.*;
30
31 import static java.lang.invoke.MethodHandleStatics.*;
32
33 /**
34 * A method handle is a typed, directly executable reference to an underlying method,
35 * constructor, field, or similar low-level operation, with optional
36 * transformations of arguments or return values.
37 * These transformations are quite general, and include such patterns as
38 * {@linkplain #asType conversion},
39 * {@linkplain #bindTo insertion},
40 * {@linkplain java.lang.invoke.MethodHandles#dropArguments deletion},
41 * and {@linkplain java.lang.invoke.MethodHandles#filterArguments substitution}.
42 *
43 * <h1>Method handle contents</h1>
44 * Method handles are dynamically and strongly typed according to their parameter and return types.
45 * They are not distinguished by the name or the defining class of their underlying methods.
46 * A method handle must be invoked using a symbolic type descriptor which matches
47 * the method handle's own {@linkplain #type type descriptor}.
48 * <p>
49 * Every method handle reports its type descriptor via the {@link #type type} accessor.
459 this.form.prepare(); // TO DO: Try to delay this step until just before invocation.
460 }
461
462 /**
463 * Invokes the method handle, allowing any caller type descriptor, but requiring an exact type match.
464 * The symbolic type descriptor at the call site of {@code invokeExact} must
465 * exactly match this method handle's {@link #type type}.
466 * No conversions are allowed on arguments or return values.
467 * <p>
468 * When this method is observed via the Core Reflection API,
469 * it will appear as a single native method, taking an object array and returning an object.
470 * If this native method is invoked directly via
471 * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
472 * or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
473 * it will throw an {@code UnsupportedOperationException}.
474 * @param args the signature-polymorphic parameter list, statically represented using varargs
475 * @return the signature-polymorphic result, statically represented using {@code Object}
476 * @throws WrongMethodTypeException if the target's type is not identical with the caller's symbolic type descriptor
477 * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
478 */
479 public final native @PolymorphicSignature Object invokeExact(Object... args) throws Throwable;
480
481 /**
482 * Invokes the method handle, allowing any caller type descriptor,
483 * and optionally performing conversions on arguments and return values.
484 * <p>
485 * If the call site's symbolic type descriptor exactly matches this method handle's {@link #type type},
486 * the call proceeds as if by {@link #invokeExact invokeExact}.
487 * <p>
488 * Otherwise, the call proceeds as if this method handle were first
489 * adjusted by calling {@link #asType asType} to adjust this method handle
490 * to the required type, and then the call proceeds as if by
491 * {@link #invokeExact invokeExact} on the adjusted method handle.
492 * <p>
493 * There is no guarantee that the {@code asType} call is actually made.
494 * If the JVM can predict the results of making the call, it may perform
495 * adaptations directly on the caller's arguments,
496 * and call the target method handle according to its own exact type.
497 * <p>
498 * The resolved type descriptor at the call site of {@code invoke} must
499 * be a valid argument to the receivers {@code asType} method.
500 * In particular, the caller must specify the same argument arity
501 * as the callee's type,
502 * if the callee is not a {@linkplain #asVarargsCollector variable arity collector}.
503 * <p>
504 * When this method is observed via the Core Reflection API,
505 * it will appear as a single native method, taking an object array and returning an object.
506 * If this native method is invoked directly via
507 * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
508 * or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
509 * it will throw an {@code UnsupportedOperationException}.
510 * @param args the signature-polymorphic parameter list, statically represented using varargs
511 * @return the signature-polymorphic result, statically represented using {@code Object}
512 * @throws WrongMethodTypeException if the target's type cannot be adjusted to the caller's symbolic type descriptor
513 * @throws ClassCastException if the target's type can be adjusted to the caller, but a reference cast fails
514 * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
515 */
516 public final native @PolymorphicSignature Object invoke(Object... args) throws Throwable;
517
518 /**
519 * Private method for trusted invocation of a method handle respecting simplified signatures.
520 * Type mismatches will not throw {@code WrongMethodTypeException}, but could crash the JVM.
521 * <p>
522 * The caller signature is restricted to the following basic types:
523 * Object, int, long, float, double, and void return.
524 * <p>
525 * The caller is responsible for maintaining type correctness by ensuring
526 * that the each outgoing argument value is a member of the range of the corresponding
527 * callee argument type.
528 * (The caller should therefore issue appropriate casts and integer narrowing
529 * operations on outgoing argument values.)
530 * The caller can assume that the incoming result value is part of the range
531 * of the callee's return type.
532 * @param args the signature-polymorphic parameter list, statically represented using varargs
533 * @return the signature-polymorphic result, statically represented using {@code Object}
534 */
535 /*non-public*/ final native @PolymorphicSignature Object invokeBasic(Object... args) throws Throwable;
536
537 /**
538 * Private method for trusted invocation of a MemberName of kind {@code REF_invokeVirtual}.
539 * The caller signature is restricted to basic types as with {@code invokeBasic}.
540 * The trailing (not leading) argument must be a MemberName.
541 * @param args the signature-polymorphic parameter list, statically represented using varargs
542 * @return the signature-polymorphic result, statically represented using {@code Object}
543 */
544 /*non-public*/ static native @PolymorphicSignature Object linkToVirtual(Object... args) throws Throwable;
545
546 /**
547 * Private method for trusted invocation of a MemberName of kind {@code REF_invokeStatic}.
548 * The caller signature is restricted to basic types as with {@code invokeBasic}.
549 * The trailing (not leading) argument must be a MemberName.
550 * @param args the signature-polymorphic parameter list, statically represented using varargs
551 * @return the signature-polymorphic result, statically represented using {@code Object}
552 */
553 /*non-public*/ static native @PolymorphicSignature Object linkToStatic(Object... args) throws Throwable;
554
555 /**
556 * Private method for trusted invocation of a MemberName of kind {@code REF_invokeSpecial}.
557 * The caller signature is restricted to basic types as with {@code invokeBasic}.
558 * The trailing (not leading) argument must be a MemberName.
559 * @param args the signature-polymorphic parameter list, statically represented using varargs
560 * @return the signature-polymorphic result, statically represented using {@code Object}
561 */
562 /*non-public*/ static native @PolymorphicSignature Object linkToSpecial(Object... args) throws Throwable;
563
564 /**
565 * Private method for trusted invocation of a MemberName of kind {@code REF_invokeInterface}.
566 * The caller signature is restricted to basic types as with {@code invokeBasic}.
567 * The trailing (not leading) argument must be a MemberName.
568 * @param args the signature-polymorphic parameter list, statically represented using varargs
569 * @return the signature-polymorphic result, statically represented using {@code Object}
570 */
571 /*non-public*/ static native @PolymorphicSignature Object linkToInterface(Object... args) throws Throwable;
572
573 /**
574 * Performs a variable arity invocation, passing the arguments in the given list
575 * to the method handle, as if via an inexact {@link #invoke invoke} from a call site
576 * which mentions only the type {@code Object}, and whose arity is the length
577 * of the argument list.
578 * <p>
579 * Specifically, execution proceeds as if by the following steps,
580 * although the methods are not guaranteed to be called if the JVM
581 * can predict their effects.
582 * <ul>
583 * <li>Determine the length of the argument array as {@code N}.
584 * For a null reference, {@code N=0}. </li>
585 * <li>Determine the general type {@code TN} of {@code N} arguments as
586 * as {@code TN=MethodType.genericMethodType(N)}.</li>
587 * <li>Force the original target method handle {@code MH0} to the
588 * required type, as {@code MH1 = MH0.asType(TN)}. </li>
589 * <li>Spread the array into {@code N} separate arguments {@code A0, ...}. </li>
590 * <li>Invoke the type-adjusted method handle on the unpacked arguments:
|
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.invoke;
27
28
29 import java.util.*;
30 import jdk.internal.HotSpotIntrinsicCandidate;
31
32 import static java.lang.invoke.MethodHandleStatics.*;
33
34 /**
35 * A method handle is a typed, directly executable reference to an underlying method,
36 * constructor, field, or similar low-level operation, with optional
37 * transformations of arguments or return values.
38 * These transformations are quite general, and include such patterns as
39 * {@linkplain #asType conversion},
40 * {@linkplain #bindTo insertion},
41 * {@linkplain java.lang.invoke.MethodHandles#dropArguments deletion},
42 * and {@linkplain java.lang.invoke.MethodHandles#filterArguments substitution}.
43 *
44 * <h1>Method handle contents</h1>
45 * Method handles are dynamically and strongly typed according to their parameter and return types.
46 * They are not distinguished by the name or the defining class of their underlying methods.
47 * A method handle must be invoked using a symbolic type descriptor which matches
48 * the method handle's own {@linkplain #type type descriptor}.
49 * <p>
50 * Every method handle reports its type descriptor via the {@link #type type} accessor.
460 this.form.prepare(); // TO DO: Try to delay this step until just before invocation.
461 }
462
463 /**
464 * Invokes the method handle, allowing any caller type descriptor, but requiring an exact type match.
465 * The symbolic type descriptor at the call site of {@code invokeExact} must
466 * exactly match this method handle's {@link #type type}.
467 * No conversions are allowed on arguments or return values.
468 * <p>
469 * When this method is observed via the Core Reflection API,
470 * it will appear as a single native method, taking an object array and returning an object.
471 * If this native method is invoked directly via
472 * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
473 * or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
474 * it will throw an {@code UnsupportedOperationException}.
475 * @param args the signature-polymorphic parameter list, statically represented using varargs
476 * @return the signature-polymorphic result, statically represented using {@code Object}
477 * @throws WrongMethodTypeException if the target's type is not identical with the caller's symbolic type descriptor
478 * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
479 */
480 @HotSpotIntrinsicCandidate
481 public final native @PolymorphicSignature Object invokeExact(Object... args) throws Throwable;
482
483 /**
484 * Invokes the method handle, allowing any caller type descriptor,
485 * and optionally performing conversions on arguments and return values.
486 * <p>
487 * If the call site's symbolic type descriptor exactly matches this method handle's {@link #type type},
488 * the call proceeds as if by {@link #invokeExact invokeExact}.
489 * <p>
490 * Otherwise, the call proceeds as if this method handle were first
491 * adjusted by calling {@link #asType asType} to adjust this method handle
492 * to the required type, and then the call proceeds as if by
493 * {@link #invokeExact invokeExact} on the adjusted method handle.
494 * <p>
495 * There is no guarantee that the {@code asType} call is actually made.
496 * If the JVM can predict the results of making the call, it may perform
497 * adaptations directly on the caller's arguments,
498 * and call the target method handle according to its own exact type.
499 * <p>
500 * The resolved type descriptor at the call site of {@code invoke} must
501 * be a valid argument to the receivers {@code asType} method.
502 * In particular, the caller must specify the same argument arity
503 * as the callee's type,
504 * if the callee is not a {@linkplain #asVarargsCollector variable arity collector}.
505 * <p>
506 * When this method is observed via the Core Reflection API,
507 * it will appear as a single native method, taking an object array and returning an object.
508 * If this native method is invoked directly via
509 * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
510 * or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
511 * it will throw an {@code UnsupportedOperationException}.
512 * @param args the signature-polymorphic parameter list, statically represented using varargs
513 * @return the signature-polymorphic result, statically represented using {@code Object}
514 * @throws WrongMethodTypeException if the target's type cannot be adjusted to the caller's symbolic type descriptor
515 * @throws ClassCastException if the target's type can be adjusted to the caller, but a reference cast fails
516 * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
517 */
518 @HotSpotIntrinsicCandidate
519 public final native @PolymorphicSignature Object invoke(Object... args) throws Throwable;
520
521 /**
522 * Private method for trusted invocation of a method handle respecting simplified signatures.
523 * Type mismatches will not throw {@code WrongMethodTypeException}, but could crash the JVM.
524 * <p>
525 * The caller signature is restricted to the following basic types:
526 * Object, int, long, float, double, and void return.
527 * <p>
528 * The caller is responsible for maintaining type correctness by ensuring
529 * that the each outgoing argument value is a member of the range of the corresponding
530 * callee argument type.
531 * (The caller should therefore issue appropriate casts and integer narrowing
532 * operations on outgoing argument values.)
533 * The caller can assume that the incoming result value is part of the range
534 * of the callee's return type.
535 * @param args the signature-polymorphic parameter list, statically represented using varargs
536 * @return the signature-polymorphic result, statically represented using {@code Object}
537 */
538 @HotSpotIntrinsicCandidate
539 /*non-public*/ final native @PolymorphicSignature Object invokeBasic(Object... args) throws Throwable;
540
541 /**
542 * Private method for trusted invocation of a MemberName of kind {@code REF_invokeVirtual}.
543 * The caller signature is restricted to basic types as with {@code invokeBasic}.
544 * The trailing (not leading) argument must be a MemberName.
545 * @param args the signature-polymorphic parameter list, statically represented using varargs
546 * @return the signature-polymorphic result, statically represented using {@code Object}
547 */
548 @HotSpotIntrinsicCandidate
549 /*non-public*/ static native @PolymorphicSignature Object linkToVirtual(Object... args) throws Throwable;
550
551 /**
552 * Private method for trusted invocation of a MemberName of kind {@code REF_invokeStatic}.
553 * The caller signature is restricted to basic types as with {@code invokeBasic}.
554 * The trailing (not leading) argument must be a MemberName.
555 * @param args the signature-polymorphic parameter list, statically represented using varargs
556 * @return the signature-polymorphic result, statically represented using {@code Object}
557 */
558 @HotSpotIntrinsicCandidate
559 /*non-public*/ static native @PolymorphicSignature Object linkToStatic(Object... args) throws Throwable;
560
561 /**
562 * Private method for trusted invocation of a MemberName of kind {@code REF_invokeSpecial}.
563 * The caller signature is restricted to basic types as with {@code invokeBasic}.
564 * The trailing (not leading) argument must be a MemberName.
565 * @param args the signature-polymorphic parameter list, statically represented using varargs
566 * @return the signature-polymorphic result, statically represented using {@code Object}
567 */
568 @HotSpotIntrinsicCandidate
569 /*non-public*/ static native @PolymorphicSignature Object linkToSpecial(Object... args) throws Throwable;
570
571 /**
572 * Private method for trusted invocation of a MemberName of kind {@code REF_invokeInterface}.
573 * The caller signature is restricted to basic types as with {@code invokeBasic}.
574 * The trailing (not leading) argument must be a MemberName.
575 * @param args the signature-polymorphic parameter list, statically represented using varargs
576 * @return the signature-polymorphic result, statically represented using {@code Object}
577 */
578 @HotSpotIntrinsicCandidate
579 /*non-public*/ static native @PolymorphicSignature Object linkToInterface(Object... args) throws Throwable;
580
581 /**
582 * Performs a variable arity invocation, passing the arguments in the given list
583 * to the method handle, as if via an inexact {@link #invoke invoke} from a call site
584 * which mentions only the type {@code Object}, and whose arity is the length
585 * of the argument list.
586 * <p>
587 * Specifically, execution proceeds as if by the following steps,
588 * although the methods are not guaranteed to be called if the JVM
589 * can predict their effects.
590 * <ul>
591 * <li>Determine the length of the argument array as {@code N}.
592 * For a null reference, {@code N=0}. </li>
593 * <li>Determine the general type {@code TN} of {@code N} arguments as
594 * as {@code TN=MethodType.genericMethodType(N)}.</li>
595 * <li>Force the original target method handle {@code MH0} to the
596 * required type, as {@code MH1 = MH0.asType(TN)}. </li>
597 * <li>Spread the array into {@code N} separate arguments {@code A0, ...}. </li>
598 * <li>Invoke the type-adjusted method handle on the unpacked arguments:
|