jdk/src/java.base/share/classes/java/lang/invoke/MethodHandle.java
author vlivanov
Wed, 10 Sep 2014 19:19:47 +0400
changeset 26466 3bbb6a284bd4
parent 25991 e48157b42439
child 26467 d69abed3a07d
permissions -rw-r--r--
8049555: Move varargsArray from sun.invoke.util package to java.lang.invoke Reviewed-by: psandoz, iignatyev
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     1
/*
16030
265a0d86c9ff 7087570: java.lang.invoke.MemberName information wrong for method handles created with findConstructor
kmo
parents: 14342
diff changeset
     2
 * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     4
 *
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    10
 *
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    15
 * accompanied this code).
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    16
 *
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
    23
 * questions.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    24
 */
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    25
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
    26
package java.lang.invoke;
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    27
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    28
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
    29
import java.util.*;
24572
5c9e5961d21c 8037210: Get rid of char-based descriptions 'J' of basic types
vlivanov
parents: 22960
diff changeset
    30
import java.lang.invoke.LambdaForm.BasicType;
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
    31
import sun.misc.Unsafe;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
    32
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
    33
import static java.lang.invoke.MethodHandleStatics.*;
24572
5c9e5961d21c 8037210: Get rid of char-based descriptions 'J' of basic types
vlivanov
parents: 22960
diff changeset
    34
import static java.lang.invoke.LambdaForm.BasicType.*;
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
    35
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    36
/**
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    37
 * A method handle is a typed, directly executable reference to an underlying method,
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
    38
 * constructor, field, or similar low-level operation, with optional
7051
1c545d70a157 6964498: JSR 292 invokedynamic sites need local bootstrap methods
jrose
parents: 5725
diff changeset
    39
 * transformations of arguments or return values.
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
    40
 * These transformations are quite general, and include such patterns as
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
    41
 * {@linkplain #asType conversion},
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
    42
 * {@linkplain #bindTo insertion},
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
    43
 * {@linkplain java.lang.invoke.MethodHandles#dropArguments deletion},
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
    44
 * and {@linkplain java.lang.invoke.MethodHandles#filterArguments substitution}.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    45
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
    46
 * <h1>Method handle contents</h1>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
    47
 * Method handles are dynamically and strongly typed according to their parameter and return types.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
    48
 * They are not distinguished by the name or the defining class of their underlying methods.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
    49
 * A method handle must be invoked using a symbolic type descriptor which matches
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
    50
 * the method handle's own {@linkplain #type type descriptor}.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    51
 * <p>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
    52
 * Every method handle reports its type descriptor via the {@link #type type} accessor.
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
    53
 * This type descriptor is a {@link java.lang.invoke.MethodType MethodType} object,
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    54
 * whose structure is a series of classes, one of which is
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
    55
 * the return type of the method (or {@code void.class} if none).
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    56
 * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    57
 * A method handle's type controls the types of invocations it accepts,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    58
 * and the kinds of transformations that apply to it.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    59
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    60
 * A method handle contains a pair of special invoker methods
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
    61
 * called {@link #invokeExact invokeExact} and {@link #invoke invoke}.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    62
 * Both invoker methods provide direct access to the method handle's
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    63
 * underlying method, constructor, field, or other operation,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    64
 * as modified by transformations of arguments and return values.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    65
 * Both invokers accept calls which exactly match the method handle's own type.
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
    66
 * The plain, inexact invoker also accepts a range of other call types.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    67
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    68
 * Method handles are immutable and have no visible state.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    69
 * Of course, they can be bound to underlying methods or data which exhibit state.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    70
 * With respect to the Java Memory Model, any method handle will behave
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    71
 * as if all of its (internal) fields are final variables.  This means that any method
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    72
 * handle made visible to the application will always be fully formed.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    73
 * This is true even if the method handle is published through a shared
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    74
 * variable in a data race.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    75
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    76
 * Method handles cannot be subclassed by the user.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    77
 * Implementations may (or may not) create internal subclasses of {@code MethodHandle}
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    78
 * which may be visible via the {@link java.lang.Object#getClass Object.getClass}
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    79
 * operation.  The programmer should not draw conclusions about a method handle
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    80
 * from its specific class, as the method handle class hierarchy (if any)
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    81
 * may change from time to time or across implementations from different vendors.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    82
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
    83
 * <h1>Method handle compilation</h1>
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
    84
 * A Java method call expression naming {@code invokeExact} or {@code invoke}
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    85
 * can invoke a method handle from Java source code.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    86
 * From the viewpoint of source code, these methods can take any arguments
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    87
 * and their result can be cast to any return type.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    88
 * Formally this is accomplished by giving the invoker methods
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
    89
 * {@code Object} return types and variable arity {@code Object} arguments,
8350
2479a9688a39 7016520: JSR 292 rules for polymorphic signature processing must be in package-info
jrose
parents: 8346
diff changeset
    90
 * but they have an additional quality called <em>signature polymorphism</em>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    91
 * which connects this freedom of invocation directly to the JVM execution stack.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    92
 * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    93
 * As is usual with virtual methods, source-level calls to {@code invokeExact}
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
    94
 * and {@code invoke} compile to an {@code invokevirtual} instruction.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    95
 * More unusually, the compiler must record the actual argument types,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    96
 * and may not perform method invocation conversions on the arguments.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    97
 * Instead, it must push them on the stack according to their own unconverted types.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
    98
 * The method handle object itself is pushed on the stack before the arguments.
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
    99
 * The compiler then calls the method handle with a symbolic type descriptor which
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   100
 * describes the argument and return types.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   101
 * <p>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   102
 * To issue a complete symbolic type descriptor, the compiler must also determine
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   103
 * the return type.  This is based on a cast on the method invocation expression,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   104
 * if there is one, or else {@code Object} if the invocation is an expression
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   105
 * or else {@code void} if the invocation is a statement.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   106
 * The cast may be to a primitive type (but not {@code void}).
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   107
 * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   108
 * As a corner case, an uncasted {@code null} argument is given
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   109
 * a symbolic type descriptor of {@code java.lang.Void}.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   110
 * The ambiguity with the type {@code Void} is harmless, since there are no references of type
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   111
 * {@code Void} except the null reference.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   112
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   113
 * <h1>Method handle invocation</h1>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   114
 * The first time a {@code invokevirtual} instruction is executed
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   115
 * it is linked, by symbolically resolving the names in the instruction
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   116
 * and verifying that the method call is statically legal.
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   117
 * This is true of calls to {@code invokeExact} and {@code invoke}.
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   118
 * In this case, the symbolic type descriptor emitted by the compiler is checked for
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   119
 * correct syntax and names it contains are resolved.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   120
 * Thus, an {@code invokevirtual} instruction which invokes
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   121
 * a method handle will always link, as long
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   122
 * as the symbolic type descriptor is syntactically well-formed
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   123
 * and the types exist.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   124
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   125
 * When the {@code invokevirtual} is executed after linking,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   126
 * the receiving method handle's type is first checked by the JVM
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   127
 * to ensure that it matches the symbolic type descriptor.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   128
 * If the type match fails, it means that the method which the
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   129
 * caller is invoking is not present on the individual
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   130
 * method handle being invoked.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   131
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   132
 * In the case of {@code invokeExact}, the type descriptor of the invocation
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   133
 * (after resolving symbolic type names) must exactly match the method type
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   134
 * of the receiving method handle.
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   135
 * In the case of plain, inexact {@code invoke}, the resolved type descriptor
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   136
 * must be a valid argument to the receiver's {@link #asType asType} method.
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   137
 * Thus, plain {@code invoke} is more permissive than {@code invokeExact}.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   138
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   139
 * After type matching, a call to {@code invokeExact} directly
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   140
 * and immediately invoke the method handle's underlying method
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   141
 * (or other behavior, as the case may be).
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   142
 * <p>
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   143
 * A call to plain {@code invoke} works the same as a call to
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   144
 * {@code invokeExact}, if the symbolic type descriptor specified by the caller
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   145
 * exactly matches the method handle's own type.
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   146
 * If there is a type mismatch, {@code invoke} attempts
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   147
 * to adjust the type of the receiving method handle,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   148
 * as if by a call to {@link #asType asType},
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   149
 * to obtain an exactly invokable method handle {@code M2}.
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   150
 * This allows a more powerful negotiation of method type
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   151
 * between caller and callee.
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   152
 * <p>
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   153
 * (<em>Note:</em> The adjusted method handle {@code M2} is not directly observable,
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   154
 * and implementations are therefore not required to materialize it.)
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   155
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   156
 * <h1>Invocation checking</h1>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   157
 * In typical programs, method handle type matching will usually succeed.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   158
 * But if a match fails, the JVM will throw a {@link WrongMethodTypeException},
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   159
 * either directly (in the case of {@code invokeExact}) or indirectly as if
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   160
 * by a failed call to {@code asType} (in the case of {@code invoke}).
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   161
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   162
 * Thus, a method type mismatch which might show up as a linkage error
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   163
 * in a statically typed program can show up as
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   164
 * a dynamic {@code WrongMethodTypeException}
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   165
 * in a program which uses method handles.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   166
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   167
 * Because method types contain "live" {@code Class} objects,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   168
 * method type matching takes into account both types names and class loaders.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   169
 * Thus, even if a method handle {@code M} is created in one
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   170
 * class loader {@code L1} and used in another {@code L2},
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   171
 * method handle calls are type-safe, because the caller's symbolic type
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   172
 * descriptor, as resolved in {@code L2},
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   173
 * is matched against the original callee method's symbolic type descriptor,
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   174
 * as resolved in {@code L1}.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   175
 * The resolution in {@code L1} happens when {@code M} is created
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   176
 * and its type is assigned, while the resolution in {@code L2} happens
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   177
 * when the {@code invokevirtual} instruction is linked.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   178
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   179
 * Apart from the checking of type descriptors,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   180
 * a method handle's capability to call its underlying method is unrestricted.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   181
 * If a method handle is formed on a non-public method by a class
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   182
 * that has access to that method, the resulting handle can be used
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   183
 * in any place by any caller who receives a reference to it.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   184
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   185
 * Unlike with the Core Reflection API, where access is checked every time
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   186
 * a reflective method is invoked,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   187
 * method handle access checking is performed
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   188
 * <a href="MethodHandles.Lookup.html#access">when the method handle is created</a>.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   189
 * In the case of {@code ldc} (see below), access checking is performed as part of linking
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   190
 * the constant pool entry underlying the constant method handle.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   191
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   192
 * Thus, handles to non-public methods, or to methods in non-public classes,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   193
 * should generally be kept secret.
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   194
 * They should not be passed to untrusted code unless their use from
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   195
 * the untrusted code would be harmless.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   196
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   197
 * <h1>Method handle creation</h1>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   198
 * Java code can create a method handle that directly accesses
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   199
 * any method, constructor, or field that is accessible to that code.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   200
 * This is done via a reflective, capability-based API called
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   201
 * {@link java.lang.invoke.MethodHandles.Lookup MethodHandles.Lookup}
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   202
 * For example, a static method handle can be obtained
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   203
 * from {@link java.lang.invoke.MethodHandles.Lookup#findStatic Lookup.findStatic}.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   204
 * There are also conversion methods from Core Reflection API objects,
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   205
 * such as {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect}.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   206
 * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   207
 * Like classes and strings, method handles that correspond to accessible
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   208
 * fields, methods, and constructors can also be represented directly
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   209
 * in a class file's constant pool as constants to be loaded by {@code ldc} bytecodes.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   210
 * A new type of constant pool entry, {@code CONSTANT_MethodHandle},
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   211
 * refers directly to an associated {@code CONSTANT_Methodref},
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7556
diff changeset
   212
 * {@code CONSTANT_InterfaceMethodref}, or {@code CONSTANT_Fieldref}
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7556
diff changeset
   213
 * constant pool entry.
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   214
 * (For full details on method handle constants,
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   215
 * see sections 4.4.8 and 5.4.3.5 of the Java Virtual Machine Specification.)
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   216
 * <p>
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   217
 * Method handles produced by lookups or constant loads from methods or
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   218
 * constructors with the variable arity modifier bit ({@code 0x0080})
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   219
 * have a corresponding variable arity, as if they were defined with
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   220
 * the help of {@link #asVarargsCollector asVarargsCollector}.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   221
 * <p>
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   222
 * A method reference may refer either to a static or non-static method.
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   223
 * In the non-static case, the method handle type includes an explicit
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   224
 * receiver argument, prepended before any other arguments.
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   225
 * In the method handle's type, the initial receiver argument is typed
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   226
 * according to the class under which the method was initially requested.
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   227
 * (E.g., if a non-static method handle is obtained via {@code ldc},
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   228
 * the type of the receiver is the class named in the constant pool entry.)
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   229
 * <p>
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   230
 * Method handle constants are subject to the same link-time access checks
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   231
 * their corresponding bytecode instructions, and the {@code ldc} instruction
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   232
 * will throw corresponding linkage errors if the bytecode behaviors would
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   233
 * throw such errors.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   234
 * <p>
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   235
 * As a corollary of this, access to protected members is restricted
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   236
 * to receivers only of the accessing class, or one of its subclasses,
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   237
 * and the accessing class must in turn be a subclass (or package sibling)
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   238
 * of the protected member's defining class.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   239
 * If a method reference refers to a protected non-static method or field
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   240
 * of a class outside the current package, the receiver argument will
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   241
 * be narrowed to the type of the accessing class.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   242
 * <p>
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   243
 * When a method handle to a virtual method is invoked, the method is
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   244
 * always looked up in the receiver (that is, the first argument).
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   245
 * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   246
 * A non-virtual method handle to a specific virtual method implementation
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   247
 * can also be created.  These do not perform virtual lookup based on
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   248
 * receiver type.  Such a method handle simulates the effect of
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   249
 * an {@code invokespecial} instruction to the same method.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   250
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   251
 * <h1>Usage examples</h1>
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   252
 * Here are some examples of usage:
20877
83ea903d5cf1 8026183: minor documentation problems in java.lang.invoke
rriggs
parents: 20535
diff changeset
   253
 * <blockquote><pre>{@code
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   254
Object x, y; String s; int i;
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   255
MethodType mt; MethodHandle mh;
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   256
MethodHandles.Lookup lookup = MethodHandles.lookup();
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   257
// mt is (char,char)String
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   258
mt = MethodType.methodType(String.class, char.class, char.class);
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   259
mh = lookup.findVirtual(String.class, "replace", mt);
7556
4a5711d43948 6979327: method handle invocation should use casts instead of type parameters to specify return type
jrose
parents: 7555
diff changeset
   260
s = (String) mh.invokeExact("daddy",'d','n');
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   261
// invokeExact(Ljava/lang/String;CC)Ljava/lang/String;
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   262
assertEquals(s, "nanny");
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   263
// weakly typed invocation (using MHs.invoke)
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   264
s = (String) mh.invokeWithArguments("sappy", 'p', 'v');
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   265
assertEquals(s, "savvy");
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   266
// mt is (Object[])List
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   267
mt = MethodType.methodType(java.util.List.class, Object[].class);
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   268
mh = lookup.findStatic(java.util.Arrays.class, "asList", mt);
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   269
assert(mh.isVarargsCollector());
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   270
x = mh.invoke("one", "two");
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   271
// invoke(Ljava/lang/String;Ljava/lang/String;)Ljava/lang/Object;
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   272
assertEquals(x, java.util.Arrays.asList("one","two"));
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   273
// mt is (Object,Object,Object)Object
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   274
mt = MethodType.genericMethodType(3);
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   275
mh = mh.asType(mt);
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   276
x = mh.invokeExact((Object)1, (Object)2, (Object)3);
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   277
// invokeExact(Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   278
assertEquals(x, java.util.Arrays.asList(1,2,3));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   279
// mt is ()int
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   280
mt = MethodType.methodType(int.class);
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   281
mh = lookup.findVirtual(java.util.List.class, "size", mt);
7556
4a5711d43948 6979327: method handle invocation should use casts instead of type parameters to specify return type
jrose
parents: 7555
diff changeset
   282
i = (int) mh.invokeExact(java.util.Arrays.asList(1,2,3));
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   283
// invokeExact(Ljava/util/List;)I
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   284
assert(i == 3);
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7556
diff changeset
   285
mt = MethodType.methodType(void.class, String.class);
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7556
diff changeset
   286
mh = lookup.findVirtual(java.io.PrintStream.class, "println", mt);
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7556
diff changeset
   287
mh.invokeExact(System.out, "Hello, world.");
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   288
// invokeExact(Ljava/io/PrintStream;Ljava/lang/String;)V
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
   289
 * }</pre></blockquote>
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   290
 * Each of the above calls to {@code invokeExact} or plain {@code invoke}
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   291
 * generates a single invokevirtual instruction with
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   292
 * the symbolic type descriptor indicated in the following comment.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   293
 * In these examples, the helper method {@code assertEquals} is assumed to
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 20534
diff changeset
   294
 * be a method which calls {@link java.util.Objects#equals(Object,Object) Objects.equals}
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   295
 * on its arguments, and asserts that the result is true.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   296
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   297
 * <h1>Exceptions</h1>
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   298
 * The methods {@code invokeExact} and {@code invoke} are declared
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   299
 * to throw {@link java.lang.Throwable Throwable},
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   300
 * which is to say that there is no static restriction on what a method handle
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   301
 * can throw.  Since the JVM does not distinguish between checked
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   302
 * and unchecked exceptions (other than by their class, of course),
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   303
 * there is no particular effect on bytecode shape from ascribing
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   304
 * checked exceptions to method handle invocations.  But in Java source
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   305
 * code, methods which perform method handle calls must either explicitly
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   306
 * throw {@code Throwable}, or else must catch all
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   307
 * throwables locally, rethrowing only those which are legal in the context,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   308
 * and wrapping ones which are illegal.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   309
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   310
 * <h1><a name="sigpoly"></a>Signature polymorphism</h1>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   311
 * The unusual compilation and linkage behavior of
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   312
 * {@code invokeExact} and plain {@code invoke}
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   313
 * is referenced by the term <em>signature polymorphism</em>.
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   314
 * As defined in the Java Language Specification,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   315
 * a signature polymorphic method is one which can operate with
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   316
 * any of a wide range of call signatures and return types.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   317
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   318
 * In source code, a call to a signature polymorphic method will
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   319
 * compile, regardless of the requested symbolic type descriptor.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   320
 * As usual, the Java compiler emits an {@code invokevirtual}
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   321
 * instruction with the given symbolic type descriptor against the named method.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   322
 * The unusual part is that the symbolic type descriptor is derived from
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   323
 * the actual argument and return types, not from the method declaration.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   324
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   325
 * When the JVM processes bytecode containing signature polymorphic calls,
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   326
 * it will successfully link any such call, regardless of its symbolic type descriptor.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   327
 * (In order to retain type safety, the JVM will guard such calls with suitable
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   328
 * dynamic type checks, as described elsewhere.)
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   329
 * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   330
 * Bytecode generators, including the compiler back end, are required to emit
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   331
 * untransformed symbolic type descriptors for these methods.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   332
 * Tools which determine symbolic linkage are required to accept such
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   333
 * untransformed descriptors, without reporting linkage errors.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   334
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   335
 * <h1>Interoperation between method handles and the Core Reflection API</h1>
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   336
 * Using factory methods in the {@link java.lang.invoke.MethodHandles.Lookup Lookup} API,
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   337
 * any class member represented by a Core Reflection API object
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   338
 * can be converted to a behaviorally equivalent method handle.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   339
 * For example, a reflective {@link java.lang.reflect.Method Method} can
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   340
 * be converted to a method handle using
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   341
 * {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect}.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   342
 * The resulting method handles generally provide more direct and efficient
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   343
 * access to the underlying class members.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   344
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   345
 * As a special case,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   346
 * when the Core Reflection API is used to view the signature polymorphic
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   347
 * methods {@code invokeExact} or plain {@code invoke} in this class,
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   348
 * they appear as ordinary non-polymorphic methods.
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   349
 * Their reflective appearance, as viewed by
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   350
 * {@link java.lang.Class#getDeclaredMethod Class.getDeclaredMethod},
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   351
 * is unaffected by their special status in this API.
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   352
 * For example, {@link java.lang.reflect.Method#getModifiers Method.getModifiers}
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   353
 * will report exactly those modifier bits required for any similarly
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   354
 * declared method, including in this case {@code native} and {@code varargs} bits.
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   355
 * <p>
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   356
 * As with any reflected method, these methods (when reflected) may be
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   357
 * invoked via {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}.
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   358
 * However, such reflective calls do not result in method handle invocations.
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   359
 * Such a call, if passed the required argument
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   360
 * (a single one, of type {@code Object[]}), will ignore the argument and
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   361
 * will throw an {@code UnsupportedOperationException}.
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   362
 * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   363
 * Since {@code invokevirtual} instructions can natively
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   364
 * invoke method handles under any symbolic type descriptor, this reflective view conflicts
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   365
 * with the normal presentation of these methods via bytecodes.
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   366
 * Thus, these two native methods, when reflectively viewed by
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   367
 * {@code Class.getDeclaredMethod}, may be regarded as placeholders only.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   368
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   369
 * In order to obtain an invoker method for a particular type descriptor,
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   370
 * use {@link java.lang.invoke.MethodHandles#exactInvoker MethodHandles.exactInvoker},
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   371
 * or {@link java.lang.invoke.MethodHandles#invoker MethodHandles.invoker}.
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   372
 * The {@link java.lang.invoke.MethodHandles.Lookup#findVirtual Lookup.findVirtual}
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   373
 * API is also able to return a method handle
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   374
 * to call {@code invokeExact} or plain {@code invoke},
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   375
 * for any specified type descriptor .
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   376
 *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   377
 * <h1>Interoperation between method handles and Java generics</h1>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   378
 * A method handle can be obtained on a method, constructor, or field
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   379
 * which is declared with Java generic types.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   380
 * As with the Core Reflection API, the type of the method handle
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   381
 * will constructed from the erasure of the source-level type.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   382
 * When a method handle is invoked, the types of its arguments
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   383
 * or the return value cast type may be generic types or type instances.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   384
 * If this occurs, the compiler will replace those
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   385
 * types by their erasures when it constructs the symbolic type descriptor
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   386
 * for the {@code invokevirtual} instruction.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   387
 * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   388
 * Method handles do not represent
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   389
 * their function-like types in terms of Java parameterized (generic) types,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   390
 * because there are three mismatches between function-like types and parameterized
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   391
 * Java types.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   392
 * <ul>
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   393
 * <li>Method types range over all possible arities,
20529
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   394
 * from no arguments to up to the  <a href="MethodHandle.html#maxarity">maximum number</a> of allowed arguments.
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   395
 * Generics are not variadic, and so cannot represent this.</li>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   396
 * <li>Method types can specify arguments of primitive types,
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   397
 * which Java generic types cannot range over.</li>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   398
 * <li>Higher order functions over method handles (combinators) are
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   399
 * often generic across a wide range of function types, including
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   400
 * those of multiple arities.  It is impossible to represent such
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   401
 * genericity with a Java type parameter.</li>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   402
 * </ul>
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   403
 *
20529
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   404
 * <h1><a name="maxarity"></a>Arity limits</h1>
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   405
 * The JVM imposes on all methods and constructors of any kind an absolute
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   406
 * limit of 255 stacked arguments.  This limit can appear more restrictive
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   407
 * in certain cases:
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   408
 * <ul>
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   409
 * <li>A {@code long} or {@code double} argument counts (for purposes of arity limits) as two argument slots.
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   410
 * <li>A non-static method consumes an extra argument for the object on which the method is called.
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   411
 * <li>A constructor consumes an extra argument for the object which is being constructed.
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   412
 * <li>Since a method handle&rsquo;s {@code invoke} method (or other signature-polymorphic method) is non-virtual,
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   413
 *     it consumes an extra argument for the method handle itself, in addition to any non-virtual receiver object.
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   414
 * </ul>
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   415
 * These limits imply that certain method handles cannot be created, solely because of the JVM limit on stacked arguments.
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   416
 * For example, if a static JVM method accepts exactly 255 arguments, a method handle cannot be created for it.
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   417
 * Attempts to create method handles with impossible method types lead to an {@link IllegalArgumentException}.
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   418
 * In particular, a method handle&rsquo;s type must not have an arity of the exact maximum 255.
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   419
 *
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   420
 * @see MethodType
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   421
 * @see MethodHandles
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   422
 * @author John Rose, JSR 292 EG
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   423
 */
8821
2836ee97ee27 6839872: remove implementation inheritance from JSR 292 APIs
jrose
parents: 8350
diff changeset
   424
public abstract class MethodHandle {
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   425
    static { MethodHandleImpl.initStatics(); }
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   426
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   427
    /**
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   428
     * Internal marker interface which distinguishes (to the Java compiler)
8350
2479a9688a39 7016520: JSR 292 rules for polymorphic signature processing must be in package-info
jrose
parents: 8346
diff changeset
   429
     * those methods which are <a href="MethodHandle.html#sigpoly">signature polymorphic</a>.
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   430
     */
8350
2479a9688a39 7016520: JSR 292 rules for polymorphic signature processing must be in package-info
jrose
parents: 8346
diff changeset
   431
    @java.lang.annotation.Target({java.lang.annotation.ElementType.METHOD})
7051
1c545d70a157 6964498: JSR 292 invokedynamic sites need local bootstrap methods
jrose
parents: 5725
diff changeset
   432
    @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   433
    @interface PolymorphicSignature { }
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   434
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   435
    private final MethodType type;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   436
    /*private*/ final LambdaForm form;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   437
    // form is not private so that invokers can easily fetch it
20527
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   438
    /*private*/ MethodHandle asTypeCache;
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   439
    // asTypeCache is not private so that invokers can easily fetch it
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   440
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   441
    /**
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   442
     * Reports the type of this method handle.
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   443
     * Every invocation of this method handle via {@code invokeExact} must exactly match this type.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   444
     * @return the method handle type
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   445
     */
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   446
    public MethodType type() {
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   447
        return type;
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   448
    }
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   449
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   450
    /**
8821
2836ee97ee27 6839872: remove implementation inheritance from JSR 292 APIs
jrose
parents: 8350
diff changeset
   451
     * Package-private constructor for the method handle implementation hierarchy.
2836ee97ee27 6839872: remove implementation inheritance from JSR 292 APIs
jrose
parents: 8350
diff changeset
   452
     * Method handle inheritance will be contained completely within
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   453
     * the {@code java.lang.invoke} package.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   454
     */
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   455
    // @param type type (permanently assigned) of the new method handle
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   456
    /*non-public*/ MethodHandle(MethodType type, LambdaForm form) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   457
        type.getClass();  // explicit NPE
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   458
        form.getClass();  // explicit NPE
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   459
        this.type = type;
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   460
        this.form = form;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   461
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   462
        form.prepare();  // TO DO:  Try to delay this step until just before invocation.
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   463
    }
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   464
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7556
diff changeset
   465
    /**
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   466
     * Invokes the method handle, allowing any caller type descriptor, but requiring an exact type match.
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   467
     * The symbolic type descriptor at the call site of {@code invokeExact} must
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   468
     * exactly match this method handle's {@link #type type}.
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   469
     * No conversions are allowed on arguments or return values.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   470
     * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   471
     * When this method is observed via the Core Reflection API,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   472
     * it will appear as a single native method, taking an object array and returning an object.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   473
     * If this native method is invoked directly via
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   474
     * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   475
     * or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   476
     * it will throw an {@code UnsupportedOperationException}.
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   477
     * @param args the signature-polymorphic parameter list, statically represented using varargs
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   478
     * @return the signature-polymorphic result, statically represented using {@code Object}
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   479
     * @throws WrongMethodTypeException if the target's type is not identical with the caller's symbolic type descriptor
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   480
     * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   481
     */
7556
4a5711d43948 6979327: method handle invocation should use casts instead of type parameters to specify return type
jrose
parents: 7555
diff changeset
   482
    public final native @PolymorphicSignature Object invokeExact(Object... args) throws Throwable;
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   483
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   484
    /**
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   485
     * Invokes the method handle, allowing any caller type descriptor,
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   486
     * and optionally performing conversions on arguments and return values.
7051
1c545d70a157 6964498: JSR 292 invokedynamic sites need local bootstrap methods
jrose
parents: 5725
diff changeset
   487
     * <p>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   488
     * If the call site's symbolic type descriptor exactly matches this method handle's {@link #type type},
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   489
     * the call proceeds as if by {@link #invokeExact invokeExact}.
7051
1c545d70a157 6964498: JSR 292 invokedynamic sites need local bootstrap methods
jrose
parents: 5725
diff changeset
   490
     * <p>
1c545d70a157 6964498: JSR 292 invokedynamic sites need local bootstrap methods
jrose
parents: 5725
diff changeset
   491
     * Otherwise, the call proceeds as if this method handle were first
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   492
     * adjusted by calling {@link #asType asType} to adjust this method handle
7051
1c545d70a157 6964498: JSR 292 invokedynamic sites need local bootstrap methods
jrose
parents: 5725
diff changeset
   493
     * to the required type, and then the call proceeds as if by
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   494
     * {@link #invokeExact invokeExact} on the adjusted method handle.
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   495
     * <p>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   496
     * There is no guarantee that the {@code asType} call is actually made.
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   497
     * If the JVM can predict the results of making the call, it may perform
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   498
     * adaptations directly on the caller's arguments,
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   499
     * and call the target method handle according to its own exact type.
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   500
     * <p>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   501
     * The resolved type descriptor at the call site of {@code invoke} must
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   502
     * be a valid argument to the receivers {@code asType} method.
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   503
     * In particular, the caller must specify the same argument arity
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   504
     * as the callee's type,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   505
     * if the callee is not a {@linkplain #asVarargsCollector variable arity collector}.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   506
     * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   507
     * When this method is observed via the Core Reflection API,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   508
     * it will appear as a single native method, taking an object array and returning an object.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   509
     * If this native method is invoked directly via
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   510
     * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   511
     * or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   512
     * it will throw an {@code UnsupportedOperationException}.
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   513
     * @param args the signature-polymorphic parameter list, statically represented using varargs
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   514
     * @return the signature-polymorphic result, statically represented using {@code Object}
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   515
     * @throws WrongMethodTypeException if the target's type cannot be adjusted to the caller's symbolic type descriptor
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   516
     * @throws ClassCastException if the target's type can be adjusted to the caller, but a reference cast fails
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   517
     * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   518
     */
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   519
    public final native @PolymorphicSignature Object invoke(Object... args) throws Throwable;
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   520
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   521
    /**
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   522
     * Private method for trusted invocation of a method handle respecting simplified signatures.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   523
     * Type mismatches will not throw {@code WrongMethodTypeException}, but could crash the JVM.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   524
     * <p>
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   525
     * The caller signature is restricted to the following basic types:
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   526
     * Object, int, long, float, double, and void return.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   527
     * <p>
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   528
     * The caller is responsible for maintaining type correctness by ensuring
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   529
     * that the each outgoing argument value is a member of the range of the corresponding
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   530
     * callee argument type.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   531
     * (The caller should therefore issue appropriate casts and integer narrowing
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   532
     * operations on outgoing argument values.)
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   533
     * The caller can assume that the incoming result value is part of the range
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   534
     * of the callee's return type.
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   535
     * @param args the signature-polymorphic parameter list, statically represented using varargs
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   536
     * @return the signature-polymorphic result, statically represented using {@code Object}
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   537
     */
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   538
    /*non-public*/ final native @PolymorphicSignature Object invokeBasic(Object... args) throws Throwable;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   539
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   540
    /**
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   541
     * Private method for trusted invocation of a MemberName of kind {@code REF_invokeVirtual}.
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   542
     * The caller signature is restricted to basic types as with {@code invokeBasic}.
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   543
     * The trailing (not leading) argument must be a MemberName.
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   544
     * @param args the signature-polymorphic parameter list, statically represented using varargs
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   545
     * @return the signature-polymorphic result, statically represented using {@code Object}
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   546
     */
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   547
    /*non-public*/ static native @PolymorphicSignature Object linkToVirtual(Object... args) throws Throwable;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   548
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   549
    /**
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   550
     * Private method for trusted invocation of a MemberName of kind {@code REF_invokeStatic}.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   551
     * The caller signature is restricted to basic types as with {@code invokeBasic}.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   552
     * The trailing (not leading) argument must be a MemberName.
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   553
     * @param args the signature-polymorphic parameter list, statically represented using varargs
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   554
     * @return the signature-polymorphic result, statically represented using {@code Object}
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   555
     */
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   556
    /*non-public*/ static native @PolymorphicSignature Object linkToStatic(Object... args) throws Throwable;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   557
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   558
    /**
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   559
     * Private method for trusted invocation of a MemberName of kind {@code REF_invokeSpecial}.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   560
     * The caller signature is restricted to basic types as with {@code invokeBasic}.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   561
     * The trailing (not leading) argument must be a MemberName.
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   562
     * @param args the signature-polymorphic parameter list, statically represented using varargs
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   563
     * @return the signature-polymorphic result, statically represented using {@code Object}
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   564
     */
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   565
    /*non-public*/ static native @PolymorphicSignature Object linkToSpecial(Object... args) throws Throwable;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   566
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   567
    /**
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   568
     * Private method for trusted invocation of a MemberName of kind {@code REF_invokeInterface}.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   569
     * The caller signature is restricted to basic types as with {@code invokeBasic}.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   570
     * The trailing (not leading) argument must be a MemberName.
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   571
     * @param args the signature-polymorphic parameter list, statically represented using varargs
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 18156
diff changeset
   572
     * @return the signature-polymorphic result, statically represented using {@code Object}
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   573
     */
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   574
    /*non-public*/ static native @PolymorphicSignature Object linkToInterface(Object... args) throws Throwable;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   575
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   576
    /**
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 20534
diff changeset
   577
     * Performs a variable arity invocation, passing the arguments in the given list
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   578
     * to the method handle, as if via an inexact {@link #invoke invoke} from a call site
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   579
     * which mentions only the type {@code Object}, and whose arity is the length
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 20534
diff changeset
   580
     * of the argument list.
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   581
     * <p>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   582
     * Specifically, execution proceeds as if by the following steps,
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   583
     * although the methods are not guaranteed to be called if the JVM
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   584
     * can predict their effects.
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   585
     * <ul>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   586
     * <li>Determine the length of the argument array as {@code N}.
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   587
     *     For a null reference, {@code N=0}. </li>
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   588
     * <li>Determine the general type {@code TN} of {@code N} arguments as
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   589
     *     as {@code TN=MethodType.genericMethodType(N)}.</li>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   590
     * <li>Force the original target method handle {@code MH0} to the
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   591
     *     required type, as {@code MH1 = MH0.asType(TN)}. </li>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   592
     * <li>Spread the array into {@code N} separate arguments {@code A0, ...}. </li>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   593
     * <li>Invoke the type-adjusted method handle on the unpacked arguments:
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   594
     *     MH1.invokeExact(A0, ...). </li>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   595
     * <li>Take the return value as an {@code Object} reference. </li>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   596
     * </ul>
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   597
     * <p>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   598
     * Because of the action of the {@code asType} step, the following argument
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   599
     * conversions are applied as necessary:
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   600
     * <ul>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   601
     * <li>reference casting
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   602
     * <li>unboxing
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   603
     * <li>widening primitive conversions
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   604
     * </ul>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   605
     * <p>
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   606
     * The result returned by the call is boxed if it is a primitive,
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   607
     * or forced to null if the return type is void.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   608
     * <p>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   609
     * This call is equivalent to the following code:
20877
83ea903d5cf1 8026183: minor documentation problems in java.lang.invoke
rriggs
parents: 20535
diff changeset
   610
     * <blockquote><pre>{@code
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   611
     * MethodHandle invoker = MethodHandles.spreadInvoker(this.type(), 0);
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   612
     * Object result = invoker.invokeExact(this, arguments);
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 20534
diff changeset
   613
     * }</pre></blockquote>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   614
     * <p>
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   615
     * Unlike the signature polymorphic methods {@code invokeExact} and {@code invoke},
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   616
     * {@code invokeWithArguments} can be accessed normally via the Core Reflection API and JNI.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   617
     * It can therefore be used as a bridge between native or reflective code and method handles.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   618
     *
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   619
     * @param arguments the arguments to pass to the target
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   620
     * @return the result returned by the target
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   621
     * @throws ClassCastException if an argument cannot be converted by reference casting
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   622
     * @throws WrongMethodTypeException if the target's type cannot be adjusted to take the given number of {@code Object} arguments
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   623
     * @throws Throwable anything thrown by the target method invocation
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   624
     * @see MethodHandles#spreadInvoker
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   625
     */
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   626
    public Object invokeWithArguments(Object... arguments) throws Throwable {
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   627
        int argc = arguments == null ? 0 : arguments.length;
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   628
        @SuppressWarnings("LocalVariableHidesMemberVariable")
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   629
        MethodType type = type();
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   630
        if (type.parameterCount() != argc || isVarargsCollector()) {
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   631
            // simulate invoke
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   632
            return asType(MethodType.genericMethodType(argc)).invokeWithArguments(arguments);
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   633
        }
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   634
        MethodHandle invoker = type.invokers().varargsInvoker();
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   635
        return invoker.invokeExact(this, arguments);
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   636
    }
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   637
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   638
    /**
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   639
     * Performs a variable arity invocation, passing the arguments in the given array
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
   640
     * to the method handle, as if via an inexact {@link #invoke invoke} from a call site
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   641
     * which mentions only the type {@code Object}, and whose arity is the length
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   642
     * of the argument array.
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   643
     * <p>
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   644
     * This method is also equivalent to the following code:
20877
83ea903d5cf1 8026183: minor documentation problems in java.lang.invoke
rriggs
parents: 20535
diff changeset
   645
     * <blockquote><pre>{@code
83ea903d5cf1 8026183: minor documentation problems in java.lang.invoke
rriggs
parents: 20535
diff changeset
   646
     *   invokeWithArguments(arguments.toArray()
83ea903d5cf1 8026183: minor documentation problems in java.lang.invoke
rriggs
parents: 20535
diff changeset
   647
     * }</pre></blockquote>
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   648
     *
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   649
     * @param arguments the arguments to pass to the target
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   650
     * @return the result returned by the target
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   651
     * @throws NullPointerException if {@code arguments} is a null reference
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   652
     * @throws ClassCastException if an argument cannot be converted by reference casting
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   653
     * @throws WrongMethodTypeException if the target's type cannot be adjusted to take the given number of {@code Object} arguments
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   654
     * @throws Throwable anything thrown by the target method invocation
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   655
     */
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   656
    public Object invokeWithArguments(java.util.List<?> arguments) throws Throwable {
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   657
        return invokeWithArguments(arguments.toArray());
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   658
    }
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   659
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   660
    /**
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   661
     * Produces an adapter method handle which adapts the type of the
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
   662
     * current method handle to a new type.
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   663
     * The resulting method handle is guaranteed to report a type
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   664
     * which is equal to the desired new type.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   665
     * <p>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   666
     * If the original type and new type are equal, returns {@code this}.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   667
     * <p>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   668
     * The new method handle, when invoked, will perform the following
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   669
     * steps:
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   670
     * <ul>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   671
     * <li>Convert the incoming argument list to match the original
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   672
     *     method handle's argument list.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   673
     * <li>Invoke the original method handle on the converted argument list.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   674
     * <li>Convert any result returned by the original method handle
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   675
     *     to the return type of new method handle.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   676
     * </ul>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   677
     * <p>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   678
     * This method provides the crucial behavioral difference between
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   679
     * {@link #invokeExact invokeExact} and plain, inexact {@link #invoke invoke}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   680
     * The two methods
25979
42e5d9f8087e 8054857: Fix typos in java.lang.** packages
prappo
parents: 24572
diff changeset
   681
     * perform the same steps when the caller's type descriptor exactly matches
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   682
     * the callee's, but when the types differ, plain {@link #invoke invoke}
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   683
     * also calls {@code asType} (or some internal equivalent) in order
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   684
     * to match up the caller's and callee's types.
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   685
     * <p>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   686
     * If the current method is a variable arity method handle
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   687
     * argument list conversion may involve the conversion and collection
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   688
     * of several arguments into an array, as
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   689
     * {@linkplain #asVarargsCollector described elsewhere}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   690
     * In every other case, all conversions are applied <em>pairwise</em>,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   691
     * which means that each argument or return value is converted to
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   692
     * exactly one argument or return value (or no return value).
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   693
     * The applied conversions are defined by consulting the
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   694
     * the corresponding component types of the old and new
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   695
     * method handle types.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   696
     * <p>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   697
     * Let <em>T0</em> and <em>T1</em> be corresponding new and old parameter types,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   698
     * or old and new return types.  Specifically, for some valid index {@code i}, let
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   699
     * <em>T0</em>{@code =newType.parameterType(i)} and <em>T1</em>{@code =this.type().parameterType(i)}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   700
     * Or else, going the other way for return values, let
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   701
     * <em>T0</em>{@code =this.type().returnType()} and <em>T1</em>{@code =newType.returnType()}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   702
     * If the types are the same, the new method handle makes no change
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   703
     * to the corresponding argument or return value (if any).
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   704
     * Otherwise, one of the following conversions is applied
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   705
     * if possible:
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   706
     * <ul>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   707
     * <li>If <em>T0</em> and <em>T1</em> are references, then a cast to <em>T1</em> is applied.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   708
     *     (The types do not need to be related in any particular way.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   709
     *     This is because a dynamic value of null can convert to any reference type.)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   710
     * <li>If <em>T0</em> and <em>T1</em> are primitives, then a Java method invocation
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   711
     *     conversion (JLS 5.3) is applied, if one exists.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   712
     *     (Specifically, <em>T0</em> must convert to <em>T1</em> by a widening primitive conversion.)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   713
     * <li>If <em>T0</em> is a primitive and <em>T1</em> a reference,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   714
     *     a Java casting conversion (JLS 5.5) is applied if one exists.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   715
     *     (Specifically, the value is boxed from <em>T0</em> to its wrapper class,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   716
     *     which is then widened as needed to <em>T1</em>.)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   717
     * <li>If <em>T0</em> is a reference and <em>T1</em> a primitive, an unboxing
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   718
     *     conversion will be applied at runtime, possibly followed
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   719
     *     by a Java method invocation conversion (JLS 5.3)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   720
     *     on the primitive value.  (These are the primitive widening conversions.)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   721
     *     <em>T0</em> must be a wrapper class or a supertype of one.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   722
     *     (In the case where <em>T0</em> is Object, these are the conversions
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   723
     *     allowed by {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}.)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   724
     *     The unboxing conversion must have a possibility of success, which means that
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   725
     *     if <em>T0</em> is not itself a wrapper class, there must exist at least one
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   726
     *     wrapper class <em>TW</em> which is a subtype of <em>T0</em> and whose unboxed
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   727
     *     primitive value can be widened to <em>T1</em>.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   728
     * <li>If the return type <em>T1</em> is marked as void, any returned value is discarded
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   729
     * <li>If the return type <em>T0</em> is void and <em>T1</em> a reference, a null value is introduced.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   730
     * <li>If the return type <em>T0</em> is void and <em>T1</em> a primitive,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   731
     *     a zero value is introduced.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   732
     * </ul>
24572
5c9e5961d21c 8037210: Get rid of char-based descriptions 'J' of basic types
vlivanov
parents: 22960
diff changeset
   733
     * (<em>Note:</em> Both <em>T0</em> and <em>T1</em> may be regarded as static types,
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   734
     * because neither corresponds specifically to the <em>dynamic type</em> of any
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   735
     * actual argument or return value.)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   736
     * <p>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   737
     * The method handle conversion cannot be made if any one of the required
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   738
     * pairwise conversions cannot be made.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   739
     * <p>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   740
     * At runtime, the conversions applied to reference arguments
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   741
     * or return values may require additional runtime checks which can fail.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   742
     * An unboxing operation may fail because the original reference is null,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   743
     * causing a {@link java.lang.NullPointerException NullPointerException}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   744
     * An unboxing operation or a reference cast may also fail on a reference
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   745
     * to an object of the wrong type,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   746
     * causing a {@link java.lang.ClassCastException ClassCastException}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   747
     * Although an unboxing operation may accept several kinds of wrappers,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   748
     * if none are available, a {@code ClassCastException} will be thrown.
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   749
     *
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   750
     * @param newType the expected type of the new method handle
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   751
     * @return a method handle which delegates to {@code this} after performing
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   752
     *           any necessary argument conversions, and arranges for any
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   753
     *           necessary return value conversions
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   754
     * @throws NullPointerException if {@code newType} is a null reference
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   755
     * @throws WrongMethodTypeException if the conversion cannot be made
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   756
     * @see MethodHandles#explicitCastArguments
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   757
     */
7554
8a0ad9757002 6939224: MethodHandle.invokeGeneric needs to perform the correct set of conversions
jrose
parents: 7051
diff changeset
   758
    public MethodHandle asType(MethodType newType) {
20527
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   759
        // Fast path alternative to a heavyweight {@code asType} call.
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   760
        // Return 'this' if the conversion will be a no-op.
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   761
        if (newType == type) {
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   762
            return this;
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   763
        }
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   764
        // Return 'this.asTypeCache' if the conversion is already memoized.
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   765
        MethodHandle atc = asTypeCache;
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   766
        if (atc != null && newType == atc.type) {
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   767
            return atc;
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   768
        }
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   769
        return asTypeUncached(newType);
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   770
    }
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   771
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   772
    /** Override this to change asType behavior. */
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   773
    /*non-public*/ MethodHandle asTypeUncached(MethodType newType) {
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   774
        if (!type.isConvertibleTo(newType))
9730
e4b334d47f4b 7032850: MethodHandle.invokeGeneric throws unspecified RuntimeException if parameterized method is called
jrose
parents: 9646
diff changeset
   775
            throw new WrongMethodTypeException("cannot convert "+this+" to "+newType);
20527
d241258cfbcb 8024761: JSR 292 improve performance of generic invocation
jrose
parents: 19817
diff changeset
   776
        return asTypeCache = convertArguments(newType);
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   777
    }
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   778
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   779
    /**
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   780
     * Makes an <em>array-spreading</em> method handle, which accepts a trailing array argument
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   781
     * and spreads its elements as positional arguments.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   782
     * The new method handle adapts, as its <i>target</i>,
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   783
     * the current method handle.  The type of the adapter will be
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   784
     * the same as the type of the target, except that the final
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   785
     * {@code arrayLength} parameters of the target's type are replaced
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   786
     * by a single array parameter of type {@code arrayType}.
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   787
     * <p>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   788
     * If the array element type differs from any of the corresponding
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   789
     * argument types on the original target,
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   790
     * the original target is adapted to take the array elements directly,
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   791
     * as if by a call to {@link #asType asType}.
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   792
     * <p>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   793
     * When called, the adapter replaces a trailing array argument
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   794
     * by the array's elements, each as its own argument to the target.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   795
     * (The order of the arguments is preserved.)
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   796
     * They are converted pairwise by casting and/or unboxing
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   797
     * to the types of the trailing parameters of the target.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   798
     * Finally the target is called.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   799
     * What the target eventually returns is returned unchanged by the adapter.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   800
     * <p>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   801
     * Before calling the target, the adapter verifies that the array
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   802
     * contains exactly enough elements to provide a correct argument count
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   803
     * to the target method handle.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   804
     * (The array may also be null when zero elements are required.)
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   805
     * <p>
20530
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   806
     * If, when the adapter is called, the supplied array argument does
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   807
     * not have the correct number of elements, the adapter will throw
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   808
     * an {@link IllegalArgumentException} instead of invoking the target.
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   809
     * <p>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   810
     * Here are some simple examples of array-spreading method handles:
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
   811
     * <blockquote><pre>{@code
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   812
MethodHandle equals = publicLookup()
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   813
  .findVirtual(String.class, "equals", methodType(boolean.class, Object.class));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   814
assert( (boolean) equals.invokeExact("me", (Object)"me"));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   815
assert(!(boolean) equals.invokeExact("me", (Object)"thee"));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   816
// spread both arguments from a 2-array:
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   817
MethodHandle eq2 = equals.asSpreader(Object[].class, 2);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   818
assert( (boolean) eq2.invokeExact(new Object[]{ "me", "me" }));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   819
assert(!(boolean) eq2.invokeExact(new Object[]{ "me", "thee" }));
20530
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   820
// try to spread from anything but a 2-array:
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   821
for (int n = 0; n <= 10; n++) {
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   822
  Object[] badArityArgs = (n == 2 ? null : new Object[n]);
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   823
  try { assert((boolean) eq2.invokeExact(badArityArgs) && false); }
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   824
  catch (IllegalArgumentException ex) { } // OK
b54a1f5cd35f 8001109: arity mismatch on a call to spreader method handle should elicit IllegalArgumentException
jrose
parents: 20529
diff changeset
   825
}
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   826
// spread both arguments from a String array:
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   827
MethodHandle eq2s = equals.asSpreader(String[].class, 2);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   828
assert( (boolean) eq2s.invokeExact(new String[]{ "me", "me" }));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   829
assert(!(boolean) eq2s.invokeExact(new String[]{ "me", "thee" }));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   830
// spread second arguments from a 1-array:
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   831
MethodHandle eq1 = equals.asSpreader(Object[].class, 1);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   832
assert( (boolean) eq1.invokeExact("me", new Object[]{ "me" }));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   833
assert(!(boolean) eq1.invokeExact("me", new Object[]{ "thee" }));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   834
// spread no arguments from a 0-array or null:
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   835
MethodHandle eq0 = equals.asSpreader(Object[].class, 0);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   836
assert( (boolean) eq0.invokeExact("me", (Object)"me", new Object[0]));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   837
assert(!(boolean) eq0.invokeExact("me", (Object)"thee", (Object[])null));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   838
// asSpreader and asCollector are approximate inverses:
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   839
for (int n = 0; n <= 2; n++) {
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   840
    for (Class<?> a : new Class<?>[]{Object[].class, String[].class, CharSequence[].class}) {
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   841
        MethodHandle equals2 = equals.asSpreader(a, n).asCollector(a, n);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   842
        assert( (boolean) equals2.invokeWithArguments("me", "me"));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   843
        assert(!(boolean) equals2.invokeWithArguments("me", "thee"));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   844
    }
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   845
}
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   846
MethodHandle caToString = publicLookup()
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   847
  .findStatic(Arrays.class, "toString", methodType(String.class, char[].class));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   848
assertEquals("[A, B, C]", (String) caToString.invokeExact("ABC".toCharArray()));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   849
MethodHandle caString3 = caToString.asCollector(char[].class, 3);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   850
assertEquals("[A, B, C]", (String) caString3.invokeExact('A', 'B', 'C'));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   851
MethodHandle caToString2 = caString3.asSpreader(char[].class, 2);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   852
assertEquals("[A, B, C]", (String) caToString2.invokeExact('A', "BC".toCharArray()));
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
   853
     * }</pre></blockquote>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   854
     * @param arrayType usually {@code Object[]}, the type of the array argument from which to extract the spread arguments
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   855
     * @param arrayLength the number of arguments to spread from an incoming array argument
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   856
     * @return a new method handle which spreads its final array argument,
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   857
     *         before calling the original method handle
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   858
     * @throws NullPointerException if {@code arrayType} is a null reference
20529
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   859
     * @throws IllegalArgumentException if {@code arrayType} is not an array type,
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   860
     *         or if target does not have at least
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   861
     *         {@code arrayLength} parameter types,
20529
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   862
     *         or if {@code arrayLength} is negative,
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   863
     *         or if the resulting method handle's type would have
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   864
     *         <a href="MethodHandle.html#maxarity">too many parameters</a>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   865
     * @throws WrongMethodTypeException if the implied {@code asType} call fails
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   866
     * @see #asCollector
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   867
     */
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   868
    public MethodHandle asSpreader(Class<?> arrayType, int arrayLength) {
9731
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   869
        asSpreaderChecks(arrayType, arrayLength);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   870
        int spreadArgPos = type.parameterCount() - arrayLength;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   871
        return MethodHandleImpl.makeSpreadArguments(this, arrayType, spreadArgPos, arrayLength);
9731
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   872
    }
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   873
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   874
    private void asSpreaderChecks(Class<?> arrayType, int arrayLength) {
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   875
        spreadArrayChecks(arrayType, arrayLength);
9646
5ebbe5ab084f 6939861: JVM should handle more conversion operations
jrose
parents: 9645
diff changeset
   876
        int nargs = type().parameterCount();
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   877
        if (nargs < arrayLength || arrayLength < 0)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   878
            throw newIllegalArgumentException("bad spread array length");
9731
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   879
        if (arrayType != Object[].class && arrayLength != 0) {
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   880
            boolean sawProblem = false;
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   881
            Class<?> arrayElement = arrayType.getComponentType();
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   882
            for (int i = nargs - arrayLength; i < nargs; i++) {
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   883
                if (!MethodType.canConvert(arrayElement, type().parameterType(i))) {
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   884
                    sawProblem = true;
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   885
                    break;
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   886
                }
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   887
            }
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   888
            if (sawProblem) {
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   889
                ArrayList<Class<?>> ptypes = new ArrayList<>(type().parameterList());
9731
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   890
                for (int i = nargs - arrayLength; i < nargs; i++) {
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   891
                    ptypes.set(i, arrayElement);
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   892
                }
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   893
                // elicit an error:
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   894
                this.asType(MethodType.methodType(type().returnType(), ptypes));
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   895
            }
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   896
        }
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   897
    }
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   898
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   899
    private void spreadArrayChecks(Class<?> arrayType, int arrayLength) {
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   900
        Class<?> arrayElement = arrayType.getComponentType();
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   901
        if (arrayElement == null)
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   902
            throw newIllegalArgumentException("not an array type", arrayType);
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   903
        if ((arrayLength & 0x7F) != arrayLength) {
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   904
            if ((arrayLength & 0xFF) != arrayLength)
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   905
                throw newIllegalArgumentException("array length is not legal", arrayLength);
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   906
            assert(arrayLength >= 128);
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   907
            if (arrayElement == long.class ||
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   908
                arrayElement == double.class)
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   909
                throw newIllegalArgumentException("array length is not legal for long[] or double[]", arrayLength);
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   910
        }
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   911
    }
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   912
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   913
    /**
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   914
     * Makes an <em>array-collecting</em> method handle, which accepts a given number of trailing
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   915
     * positional arguments and collects them into an array argument.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   916
     * The new method handle adapts, as its <i>target</i>,
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   917
     * the current method handle.  The type of the adapter will be
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   918
     * the same as the type of the target, except that a single trailing
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   919
     * parameter (usually of type {@code arrayType}) is replaced by
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   920
     * {@code arrayLength} parameters whose type is element type of {@code arrayType}.
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   921
     * <p>
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   922
     * If the array type differs from the final argument type on the original target,
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   923
     * the original target is adapted to take the array type directly,
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   924
     * as if by a call to {@link #asType asType}.
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   925
     * <p>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   926
     * When called, the adapter replaces its trailing {@code arrayLength}
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   927
     * arguments by a single new array of type {@code arrayType}, whose elements
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   928
     * comprise (in order) the replaced arguments.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   929
     * Finally the target is called.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   930
     * What the target eventually returns is returned unchanged by the adapter.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   931
     * <p>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   932
     * (The array may also be a shared constant when {@code arrayLength} is zero.)
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   933
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   934
     * (<em>Note:</em> The {@code arrayType} is often identical to the last
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   935
     * parameter type of the original target.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   936
     * It is an explicit argument for symmetry with {@code asSpreader}, and also
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   937
     * to allow the target to use a simple {@code Object} as its last parameter type.)
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   938
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   939
     * In order to create a collecting adapter which is not restricted to a particular
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   940
     * number of collected arguments, use {@link #asVarargsCollector asVarargsCollector} instead.
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   941
     * <p>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   942
     * Here are some examples of array-collecting method handles:
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
   943
     * <blockquote><pre>{@code
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   944
MethodHandle deepToString = publicLookup()
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   945
  .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   946
assertEquals("[won]",   (String) deepToString.invokeExact(new Object[]{"won"}));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   947
MethodHandle ts1 = deepToString.asCollector(Object[].class, 1);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   948
assertEquals(methodType(String.class, Object.class), ts1.type());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   949
//assertEquals("[won]", (String) ts1.invokeExact(         new Object[]{"won"})); //FAIL
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   950
assertEquals("[[won]]", (String) ts1.invokeExact((Object) new Object[]{"won"}));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   951
// arrayType can be a subtype of Object[]
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   952
MethodHandle ts2 = deepToString.asCollector(String[].class, 2);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   953
assertEquals(methodType(String.class, String.class, String.class), ts2.type());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   954
assertEquals("[two, too]", (String) ts2.invokeExact("two", "too"));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   955
MethodHandle ts0 = deepToString.asCollector(Object[].class, 0);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   956
assertEquals("[]", (String) ts0.invokeExact());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   957
// collectors can be nested, Lisp-style
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   958
MethodHandle ts22 = deepToString.asCollector(Object[].class, 3).asCollector(String[].class, 2);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   959
assertEquals("[A, B, [C, D]]", ((String) ts22.invokeExact((Object)'A', (Object)"B", "C", "D")));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   960
// arrayType can be any primitive array type
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   961
MethodHandle bytesToString = publicLookup()
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   962
  .findStatic(Arrays.class, "toString", methodType(String.class, byte[].class))
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   963
  .asCollector(byte[].class, 3);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   964
assertEquals("[1, 2, 3]", (String) bytesToString.invokeExact((byte)1, (byte)2, (byte)3));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   965
MethodHandle longsToString = publicLookup()
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   966
  .findStatic(Arrays.class, "toString", methodType(String.class, long[].class))
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   967
  .asCollector(long[].class, 1);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   968
assertEquals("[123]", (String) longsToString.invokeExact((long)123));
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
   969
     * }</pre></blockquote>
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   970
     * @param arrayType often {@code Object[]}, the type of the array argument which will collect the arguments
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   971
     * @param arrayLength the number of arguments to collect into a new array argument
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   972
     * @return a new method handle which collects some trailing argument
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   973
     *         into an array, before calling the original method handle
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   974
     * @throws NullPointerException if {@code arrayType} is a null reference
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   975
     * @throws IllegalArgumentException if {@code arrayType} is not an array type
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   976
     *         or {@code arrayType} is not assignable to this method handle's trailing parameter type,
20529
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   977
     *         or {@code arrayLength} is not a legal array size,
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   978
     *         or the resulting method handle's type would have
b49b07206f7d 8019417: JSR 292 javadoc should clarify method handle arity limits
jrose
parents: 20527
diff changeset
   979
     *         <a href="MethodHandle.html#maxarity">too many parameters</a>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
   980
     * @throws WrongMethodTypeException if the implied {@code asType} call fails
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   981
     * @see #asSpreader
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
   982
     * @see #asVarargsCollector
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
   983
     */
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
   984
    public MethodHandle asCollector(Class<?> arrayType, int arrayLength) {
9646
5ebbe5ab084f 6939861: JVM should handle more conversion operations
jrose
parents: 9645
diff changeset
   985
        asCollectorChecks(arrayType, arrayLength);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   986
        int collectArgPos = type().parameterCount()-1;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   987
        MethodHandle target = this;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   988
        if (arrayType != type().parameterType(collectArgPos))
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
   989
            target = convertArguments(type().changeParameterType(collectArgPos, arrayType));
26466
3bbb6a284bd4 8049555: Move varargsArray from sun.invoke.util package to java.lang.invoke
vlivanov
parents: 25991
diff changeset
   990
        MethodHandle collector = MethodHandleImpl.varargsArray(arrayType, arrayLength);
13610
28122b96858e 7191102: nightly failures after JSR 292 lazy method handle update (round 3)
jrose
parents: 13423
diff changeset
   991
        return MethodHandles.collectArguments(target, collectArgPos, collector);
9646
5ebbe5ab084f 6939861: JVM should handle more conversion operations
jrose
parents: 9645
diff changeset
   992
    }
5ebbe5ab084f 6939861: JVM should handle more conversion operations
jrose
parents: 9645
diff changeset
   993
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   994
    // private API: return true if last param exactly matches arrayType
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   995
    private boolean asCollectorChecks(Class<?> arrayType, int arrayLength) {
9731
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
   996
        spreadArrayChecks(arrayType, arrayLength);
9646
5ebbe5ab084f 6939861: JVM should handle more conversion operations
jrose
parents: 9645
diff changeset
   997
        int nargs = type().parameterCount();
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   998
        if (nargs != 0) {
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
   999
            Class<?> lastParam = type().parameterType(nargs-1);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1000
            if (lastParam == arrayType)  return true;
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1001
            if (lastParam.isAssignableFrom(arrayType))  return false;
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1002
        }
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1003
        throw newIllegalArgumentException("array type not assignable to trailing argument", this, arrayType);
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1004
    }
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1005
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1006
    /**
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1007
     * Makes a <em>variable arity</em> adapter which is able to accept
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1008
     * any number of trailing positional arguments and collect them
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1009
     * into an array argument.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1010
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1011
     * The type and behavior of the adapter will be the same as
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1012
     * the type and behavior of the target, except that certain
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1013
     * {@code invoke} and {@code asType} requests can lead to
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1014
     * trailing positional arguments being collected into target's
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1015
     * trailing parameter.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1016
     * Also, the last parameter type of the adapter will be
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1017
     * {@code arrayType}, even if the target has a different
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1018
     * last parameter type.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1019
     * <p>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1020
     * This transformation may return {@code this} if the method handle is
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1021
     * already of variable arity and its trailing parameter type
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1022
     * is identical to {@code arrayType}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1023
     * <p>
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1024
     * When called with {@link #invokeExact invokeExact}, the adapter invokes
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1025
     * the target with no argument changes.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1026
     * (<em>Note:</em> This behavior is different from a
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1027
     * {@linkplain #asCollector fixed arity collector},
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1028
     * since it accepts a whole array of indeterminate length,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1029
     * rather than a fixed number of arguments.)
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1030
     * <p>
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1031
     * When called with plain, inexact {@link #invoke invoke}, if the caller
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1032
     * type is the same as the adapter, the adapter invokes the target as with
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1033
     * {@code invokeExact}.
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1034
     * (This is the normal behavior for {@code invoke} when types match.)
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1035
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1036
     * Otherwise, if the caller and adapter arity are the same, and the
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1037
     * trailing parameter type of the caller is a reference type identical to
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1038
     * or assignable to the trailing parameter type of the adapter,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1039
     * the arguments and return values are converted pairwise,
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1040
     * as if by {@link #asType asType} on a fixed arity
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1041
     * method handle.
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1042
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1043
     * Otherwise, the arities differ, or the adapter's trailing parameter
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1044
     * type is not assignable from the corresponding caller type.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1045
     * In this case, the adapter replaces all trailing arguments from
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1046
     * the original trailing argument position onward, by
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1047
     * a new array of type {@code arrayType}, whose elements
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1048
     * comprise (in order) the replaced arguments.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1049
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1050
     * The caller type must provides as least enough arguments,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1051
     * and of the correct type, to satisfy the target's requirement for
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1052
     * positional arguments before the trailing array argument.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1053
     * Thus, the caller must supply, at a minimum, {@code N-1} arguments,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1054
     * where {@code N} is the arity of the target.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1055
     * Also, there must exist conversions from the incoming arguments
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1056
     * to the target's arguments.
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1057
     * As with other uses of plain {@code invoke}, if these basic
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1058
     * requirements are not fulfilled, a {@code WrongMethodTypeException}
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1059
     * may be thrown.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1060
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1061
     * In all cases, what the target eventually returns is returned unchanged by the adapter.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1062
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1063
     * In the final case, it is exactly as if the target method handle were
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1064
     * temporarily adapted with a {@linkplain #asCollector fixed arity collector}
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1065
     * to the arity required by the caller type.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1066
     * (As with {@code asCollector}, if the array length is zero,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1067
     * a shared constant may be used instead of a new array.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1068
     * If the implied call to {@code asCollector} would throw
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1069
     * an {@code IllegalArgumentException} or {@code WrongMethodTypeException},
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1070
     * the call to the variable arity adapter must throw
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1071
     * {@code WrongMethodTypeException}.)
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1072
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1073
     * The behavior of {@link #asType asType} is also specialized for
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1074
     * variable arity adapters, to maintain the invariant that
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1075
     * plain, inexact {@code invoke} is always equivalent to an {@code asType}
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1076
     * call to adjust the target type, followed by {@code invokeExact}.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1077
     * Therefore, a variable arity adapter responds
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1078
     * to an {@code asType} request by building a fixed arity collector,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1079
     * if and only if the adapter and requested type differ either
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1080
     * in arity or trailing argument type.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1081
     * The resulting fixed arity collector has its type further adjusted
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1082
     * (if necessary) to the requested type by pairwise conversion,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1083
     * as if by another application of {@code asType}.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1084
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1085
     * When a method handle is obtained by executing an {@code ldc} instruction
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1086
     * of a {@code CONSTANT_MethodHandle} constant, and the target method is marked
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1087
     * as a variable arity method (with the modifier bit {@code 0x0080}),
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1088
     * the method handle will accept multiple arities, as if the method handle
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1089
     * constant were created by means of a call to {@code asVarargsCollector}.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1090
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1091
     * In order to create a collecting adapter which collects a predetermined
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1092
     * number of arguments, and whose type reflects this predetermined number,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1093
     * use {@link #asCollector asCollector} instead.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1094
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1095
     * No method handle transformations produce new method handles with
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1096
     * variable arity, unless they are documented as doing so.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1097
     * Therefore, besides {@code asVarargsCollector},
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1098
     * all methods in {@code MethodHandle} and {@code MethodHandles}
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1099
     * will return a method handle with fixed arity,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1100
     * except in the cases where they are specified to return their original
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1101
     * operand (e.g., {@code asType} of the method handle's own type).
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1102
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1103
     * Calling {@code asVarargsCollector} on a method handle which is already
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1104
     * of variable arity will produce a method handle with the same type and behavior.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1105
     * It may (or may not) return the original variable arity method handle.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1106
     * <p>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1107
     * Here is an example, of a list-making variable arity method handle:
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
  1108
     * <blockquote><pre>{@code
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1109
MethodHandle deepToString = publicLookup()
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1110
  .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1111
MethodHandle ts1 = deepToString.asVarargsCollector(Object[].class);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1112
assertEquals("[won]",   (String) ts1.invokeExact(    new Object[]{"won"}));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1113
assertEquals("[won]",   (String) ts1.invoke(         new Object[]{"won"}));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1114
assertEquals("[won]",   (String) ts1.invoke(                      "won" ));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1115
assertEquals("[[won]]", (String) ts1.invoke((Object) new Object[]{"won"}));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1116
// findStatic of Arrays.asList(...) produces a variable arity method handle:
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1117
MethodHandle asList = publicLookup()
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1118
  .findStatic(Arrays.class, "asList", methodType(List.class, Object[].class));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1119
assertEquals(methodType(List.class, Object[].class), asList.type());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1120
assert(asList.isVarargsCollector());
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1121
assertEquals("[]", asList.invoke().toString());
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1122
assertEquals("[1]", asList.invoke(1).toString());
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1123
assertEquals("[two, too]", asList.invoke("two", "too").toString());
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1124
String[] argv = { "three", "thee", "tee" };
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1125
assertEquals("[three, thee, tee]", asList.invoke(argv).toString());
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1126
assertEquals("[three, thee, tee]", asList.invoke((Object[])argv).toString());
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1127
List ls = (List) asList.invoke((Object)argv);
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1128
assertEquals(1, ls.size());
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1129
assertEquals("[three, thee, tee]", Arrays.toString((Object[])ls.get(0)));
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
  1130
     * }</pre></blockquote>
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1131
     * <p style="font-size:smaller;">
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
  1132
     * <em>Discussion:</em>
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1133
     * These rules are designed as a dynamically-typed variation
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1134
     * of the Java rules for variable arity methods.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1135
     * In both cases, callers to a variable arity method or method handle
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1136
     * can either pass zero or more positional arguments, or else pass
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1137
     * pre-collected arrays of any length.  Users should be aware of the
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1138
     * special role of the final argument, and of the effect of a
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1139
     * type match on that final argument, which determines whether
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1140
     * or not a single trailing argument is interpreted as a whole
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1141
     * array or a single element of an array to be collected.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1142
     * Note that the dynamic type of the trailing argument has no
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1143
     * effect on this decision, only a comparison between the symbolic
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1144
     * type descriptor of the call site and the type descriptor of the method handle.)
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
  1145
     *
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1146
     * @param arrayType often {@code Object[]}, the type of the array argument which will collect the arguments
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1147
     * @return a new method handle which can collect any number of trailing arguments
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1148
     *         into an array, before calling the original method handle
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1149
     * @throws NullPointerException if {@code arrayType} is a null reference
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1150
     * @throws IllegalArgumentException if {@code arrayType} is not an array type
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1151
     *         or {@code arrayType} is not assignable to this method handle's trailing parameter type
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1152
     * @see #asCollector
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
  1153
     * @see #isVarargsCollector
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1154
     * @see #asFixedArity
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1155
     */
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1156
    public MethodHandle asVarargsCollector(Class<?> arrayType) {
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1157
        Class<?> arrayElement = arrayType.getComponentType();
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1158
        boolean lastMatch = asCollectorChecks(arrayType, 0);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1159
        if (isVarargsCollector() && lastMatch)
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1160
            return this;
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1161
        return MethodHandleImpl.makeVarargsCollector(this, arrayType);
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1162
    }
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1163
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1164
    /**
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1165
     * Determines if this method handle
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1166
     * supports {@linkplain #asVarargsCollector variable arity} calls.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1167
     * Such method handles arise from the following sources:
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1168
     * <ul>
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1169
     * <li>a call to {@linkplain #asVarargsCollector asVarargsCollector}
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1170
     * <li>a call to a {@linkplain java.lang.invoke.MethodHandles.Lookup lookup method}
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1171
     *     which resolves to a variable arity Java method or constructor
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1172
     * <li>an {@code ldc} instruction of a {@code CONSTANT_MethodHandle}
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1173
     *     which resolves to a variable arity Java method or constructor
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1174
     * </ul>
9645
dabb5e4edc4c 7034977: JSR 292 MethodHandle.invokeGeneric should be renamed MethodHandle.invoke
jrose
parents: 8822
diff changeset
  1175
     * @return true if this method handle accepts more than one arity of plain, inexact {@code invoke} calls
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
  1176
     * @see #asVarargsCollector
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1177
     * @see #asFixedArity
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1178
     */
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1179
    public boolean isVarargsCollector() {
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1180
        return false;
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1181
    }
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1182
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1183
    /**
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1184
     * Makes a <em>fixed arity</em> method handle which is otherwise
20877
83ea903d5cf1 8026183: minor documentation problems in java.lang.invoke
rriggs
parents: 20535
diff changeset
  1185
     * equivalent to the current method handle.
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1186
     * <p>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1187
     * If the current method handle is not of
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1188
     * {@linkplain #asVarargsCollector variable arity},
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1189
     * the current method handle is returned.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1190
     * This is true even if the current method handle
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1191
     * could not be a valid input to {@code asVarargsCollector}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1192
     * <p>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1193
     * Otherwise, the resulting fixed-arity method handle has the same
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1194
     * type and behavior of the current method handle,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1195
     * except that {@link #isVarargsCollector isVarargsCollector}
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1196
     * will be false.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1197
     * The fixed-arity method handle may (or may not) be the
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1198
     * a previous argument to {@code asVarargsCollector}.
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1199
     * <p>
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1200
     * Here is an example, of a list-making variable arity method handle:
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
  1201
     * <blockquote><pre>{@code
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1202
MethodHandle asListVar = publicLookup()
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1203
  .findStatic(Arrays.class, "asList", methodType(List.class, Object[].class))
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1204
  .asVarargsCollector(Object[].class);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1205
MethodHandle asListFix = asListVar.asFixedArity();
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1206
assertEquals("[1]", asListVar.invoke(1).toString());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1207
Exception caught = null;
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1208
try { asListFix.invoke((Object)1); }
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1209
catch (Exception ex) { caught = ex; }
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1210
assert(caught instanceof ClassCastException);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1211
assertEquals("[two, too]", asListVar.invoke("two", "too").toString());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1212
try { asListFix.invoke("two", "too"); }
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1213
catch (Exception ex) { caught = ex; }
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1214
assert(caught instanceof WrongMethodTypeException);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1215
Object[] argv = { "three", "thee", "tee" };
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1216
assertEquals("[three, thee, tee]", asListVar.invoke(argv).toString());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1217
assertEquals("[three, thee, tee]", asListFix.invoke(argv).toString());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1218
assertEquals(1, ((List) asListVar.invoke((Object)argv)).size());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1219
assertEquals("[three, thee, tee]", asListFix.invoke((Object)argv).toString());
18156
edb590d448c5 8016217: More javadoc warnings
alanb
parents: 16030
diff changeset
  1220
     * }</pre></blockquote>
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1221
     *
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1222
     * @return a new method handle which accepts only a fixed number of arguments
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1223
     * @see #asVarargsCollector
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1224
     * @see #isVarargsCollector
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1225
     */
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1226
    public MethodHandle asFixedArity() {
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1227
        assert(!isVarargsCollector());
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1228
        return this;
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1229
    }
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1230
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 9731
diff changeset
  1231
    /**
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1232
     * Binds a value {@code x} to the first argument of a method handle, without invoking it.
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1233
     * The new method handle adapts, as its <i>target</i>,
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1234
     * the current method handle by binding it to the given argument.
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1235
     * The type of the bound handle will be
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1236
     * the same as the type of the target, except that a single leading
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1237
     * reference parameter will be omitted.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1238
     * <p>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1239
     * When called, the bound handle inserts the given value {@code x}
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1240
     * as a new leading argument to the target.  The other arguments are
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1241
     * also passed unchanged.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1242
     * What the target eventually returns is returned unchanged by the bound handle.
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1243
     * <p>
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1244
     * The reference {@code x} must be convertible to the first parameter
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1245
     * type of the target.
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1246
     * <p>
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1247
     * (<em>Note:</em>  Because method handles are immutable, the target method handle
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1248
     * retains its original type and behavior.)
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1249
     * @param x  the value to bind to the first argument of the target
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1250
     * @return a new method handle which prepends the given value to the incoming
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1251
     *         argument list, before calling the original method handle
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1252
     * @throws IllegalArgumentException if the target does not have a
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1253
     *         leading parameter type that is a reference type
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1254
     * @throws ClassCastException if {@code x} cannot be converted
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1255
     *         to the leading parameter type of the target
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
  1256
     * @see MethodHandles#insertArguments
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1257
     */
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 8345
diff changeset
  1258
    public MethodHandle bindTo(Object x) {
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1259
        Class<?> ptype;
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1260
        @SuppressWarnings("LocalVariableHidesMemberVariable")
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1261
        MethodType type = type();
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1262
        if (type.parameterCount() == 0 ||
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1263
            (ptype = type.parameterType(0)).isPrimitive())
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1264
            throw newIllegalArgumentException("no leading reference parameter", x);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1265
        x = ptype.cast(x);  // throw CCE if needed
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1266
        return bindReceiver(x);
4537
7c3c7f8d5195 6914665: update jdk code for JSR 292 (post 6858164)
jrose
parents: 2707
diff changeset
  1267
    }
7051
1c545d70a157 6964498: JSR 292 invokedynamic sites need local bootstrap methods
jrose
parents: 5725
diff changeset
  1268
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
  1269
    /**
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1270
     * Returns a string representation of the method handle,
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1271
     * starting with the string {@code "MethodHandle"} and
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1272
     * ending with the string representation of the method handle's type.
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1273
     * In other words, this method returns a string equal to the value of:
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 20534
diff changeset
  1274
     * <blockquote><pre>{@code
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1275
     * "MethodHandle" + type().toString()
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 20534
diff changeset
  1276
     * }</pre></blockquote>
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
  1277
     * <p>
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1278
     * (<em>Note:</em>  Future releases of this API may add further information
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1279
     * to the string representation.
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
  1280
     * Therefore, the present syntax should not be parsed by applications.)
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1281
     *
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1282
     * @return a string representation of the method handle
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
  1283
     */
8345
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1284
    @Override
9e2483e6cfab 7013417: JSR 292 needs to support variadic method handle calls
jrose
parents: 7562
diff changeset
  1285
    public String toString() {
9731
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
  1286
        if (DEBUG_METHOD_HANDLE_NAMES)  return debugString();
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1287
        return standardString();
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1288
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1289
    String standardString() {
9731
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
  1290
        return "MethodHandle"+type;
d0f7a3e441c4 7044892: JSR 292: API entry points sometimes throw the wrong exceptions or doesn't throw the expected one
jrose
parents: 9730
diff changeset
  1291
    }
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1292
    String debugString() {
13610
28122b96858e 7191102: nightly failures after JSR 292 lazy method handle update (round 3)
jrose
parents: 13423
diff changeset
  1293
        return standardString()+"/LF="+internalForm()+internalProperties();
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1294
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1295
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1296
    //// Implementation methods.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1297
    //// Sub-classes can override these default implementations.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1298
    //// All these methods assume arguments are already validated.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1299
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1300
    // Other transforms to do:  convert, explicitCast, permute, drop, filter, fold, GWT, catch
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1301
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1302
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1303
    MethodHandle setVarargs(MemberName member) throws IllegalAccessException {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1304
        if (!member.isVarargs())  return this;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1305
        int argc = type().parameterCount();
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1306
        if (argc != 0) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1307
            Class<?> arrayType = type().parameterType(argc-1);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1308
            if (arrayType.isArray()) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1309
                return MethodHandleImpl.makeVarargsCollector(this, arrayType);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1310
            }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1311
        }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1312
        throw member.makeAccessException("cannot make variable arity", null);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1313
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1314
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1315
    MethodHandle viewAsType(MethodType newType) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1316
        // No actual conversions, just a new view of the same method.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1317
        return MethodHandleImpl.makePairwiseConvert(this, newType, 0);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1318
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1319
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1320
    // Decoding
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1321
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1322
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1323
    LambdaForm internalForm() {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1324
        return form;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1325
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1326
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1327
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1328
    MemberName internalMemberName() {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1329
        return null;  // DMH returns DMH.member
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1330
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1331
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1332
    /*non-public*/
20534
da86f7904e6d 8025112: JSR 292 spec updates for security manager and caller sensitivity
jrose
parents: 20530
diff changeset
  1333
    Class<?> internalCallerClass() {
da86f7904e6d 8025112: JSR 292 spec updates for security manager and caller sensitivity
jrose
parents: 20530
diff changeset
  1334
        return null;  // caller-bound MH for @CallerSensitive method returns caller
da86f7904e6d 8025112: JSR 292 spec updates for security manager and caller sensitivity
jrose
parents: 20530
diff changeset
  1335
    }
da86f7904e6d 8025112: JSR 292 spec updates for security manager and caller sensitivity
jrose
parents: 20530
diff changeset
  1336
da86f7904e6d 8025112: JSR 292 spec updates for security manager and caller sensitivity
jrose
parents: 20530
diff changeset
  1337
    /*non-public*/
19804
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1338
    MethodHandle withInternalMemberName(MemberName member) {
19817
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1339
        if (member != null) {
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1340
            return MethodHandleImpl.makeWrappedMember(this, member);
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1341
        } else if (internalMemberName() == null) {
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1342
            // The required internaMemberName is null, and this MH (like most) doesn't have one.
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1343
            return this;
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1344
        } else {
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1345
            // The following case is rare. Mask the internalMemberName by wrapping the MH in a BMH.
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1346
            MethodHandle result = rebind();
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1347
            assert (result.internalMemberName() == null);
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1348
            return result;
72338a6a1a4b 8024260: 10 closed/java/lang/invoke/* tests failing after overhaul to MethodHandleInfo
rfield
parents: 19804
diff changeset
  1349
        }
19804
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1350
    }
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1351
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1352
    /*non-public*/
16030
265a0d86c9ff 7087570: java.lang.invoke.MemberName information wrong for method handles created with findConstructor
kmo
parents: 14342
diff changeset
  1353
    boolean isInvokeSpecial() {
265a0d86c9ff 7087570: java.lang.invoke.MemberName information wrong for method handles created with findConstructor
kmo
parents: 14342
diff changeset
  1354
        return false;  // DMH.Special returns true
265a0d86c9ff 7087570: java.lang.invoke.MemberName information wrong for method handles created with findConstructor
kmo
parents: 14342
diff changeset
  1355
    }
265a0d86c9ff 7087570: java.lang.invoke.MemberName information wrong for method handles created with findConstructor
kmo
parents: 14342
diff changeset
  1356
265a0d86c9ff 7087570: java.lang.invoke.MemberName information wrong for method handles created with findConstructor
kmo
parents: 14342
diff changeset
  1357
    /*non-public*/
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1358
    Object internalValues() {
13610
28122b96858e 7191102: nightly failures after JSR 292 lazy method handle update (round 3)
jrose
parents: 13423
diff changeset
  1359
        return null;
28122b96858e 7191102: nightly failures after JSR 292 lazy method handle update (round 3)
jrose
parents: 13423
diff changeset
  1360
    }
28122b96858e 7191102: nightly failures after JSR 292 lazy method handle update (round 3)
jrose
parents: 13423
diff changeset
  1361
28122b96858e 7191102: nightly failures after JSR 292 lazy method handle update (round 3)
jrose
parents: 13423
diff changeset
  1362
    /*non-public*/
28122b96858e 7191102: nightly failures after JSR 292 lazy method handle update (round 3)
jrose
parents: 13423
diff changeset
  1363
    Object internalProperties() {
28122b96858e 7191102: nightly failures after JSR 292 lazy method handle update (round 3)
jrose
parents: 13423
diff changeset
  1364
        // Override to something like "/FOO=bar"
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1365
        return "";
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1366
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1367
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1368
    //// Method handle implementation methods.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1369
    //// Sub-classes can override these default implementations.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1370
    //// All these methods assume arguments are already validated.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1371
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1372
    /*non-public*/ MethodHandle convertArguments(MethodType newType) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1373
        // Override this if it can be improved.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1374
        return MethodHandleImpl.makePairwiseConvert(this, newType, 1);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1375
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1376
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1377
    /*non-public*/
24572
5c9e5961d21c 8037210: Get rid of char-based descriptions 'J' of basic types
vlivanov
parents: 22960
diff changeset
  1378
    MethodHandle bindArgument(int pos, BasicType basicType, Object value) {
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1379
        // Override this if it can be improved.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1380
        return rebind().bindArgument(pos, basicType, value);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1381
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1382
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1383
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1384
    MethodHandle bindReceiver(Object receiver) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1385
        // Override this if it can be improved.
24572
5c9e5961d21c 8037210: Get rid of char-based descriptions 'J' of basic types
vlivanov
parents: 22960
diff changeset
  1386
        return bindArgument(0, L_TYPE, receiver);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1387
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1388
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1389
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1390
    MethodHandle dropArguments(MethodType srcType, int pos, int drops) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1391
        // Override this if it can be improved.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1392
        return rebind().dropArguments(srcType, pos, drops);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1393
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1394
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1395
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1396
    MethodHandle permuteArguments(MethodType newType, int[] reorder) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1397
        // Override this if it can be improved.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1398
        return rebind().permuteArguments(newType, reorder);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1399
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1400
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1401
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1402
    MethodHandle rebind() {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1403
        // Bind 'this' into a new invoker, of the known class BMH.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1404
        MethodType type2 = type();
19804
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1405
        LambdaForm form2 = reinvokerForm(this);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1406
        // form2 = lambda (bmh, arg*) { thismh = bmh[0]; invokeBasic(thismh, arg*) }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1407
        return BoundMethodHandle.bindSingle(type2, form2, this);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1408
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1409
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1410
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1411
    MethodHandle reinvokerTarget() {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1412
        throw new InternalError("not a reinvoker MH: "+this.getClass().getName()+": "+this);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1413
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1414
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1415
    /** Create a LF which simply reinvokes a target of the given basic type.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1416
     *  The target MH must override {@link #reinvokerTarget} to provide the target.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1417
     */
19804
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1418
    static LambdaForm reinvokerForm(MethodHandle target) {
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1419
        MethodType mtype = target.type().basicType();
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1420
        LambdaForm reinvoker = mtype.form().cachedLambdaForm(MethodTypeForm.LF_REINVOKE);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1421
        if (reinvoker != null)  return reinvoker;
19804
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1422
        if (mtype.parameterSlotCount() >= MethodType.MAX_MH_ARITY)
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1423
            return makeReinvokerForm(target.type(), target);  // cannot cache this
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1424
        reinvoker = makeReinvokerForm(mtype, null);
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1425
        return mtype.form().setCachedLambdaForm(MethodTypeForm.LF_REINVOKE, reinvoker);
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1426
    }
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1427
    private static LambdaForm makeReinvokerForm(MethodType mtype, MethodHandle customTargetOrNull) {
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1428
        boolean customized = (customTargetOrNull != null);
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1429
        MethodHandle MH_invokeBasic = customized ? null : MethodHandles.basicInvoker(mtype);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1430
        final int THIS_BMH    = 0;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1431
        final int ARG_BASE    = 1;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1432
        final int ARG_LIMIT   = ARG_BASE + mtype.parameterCount();
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1433
        int nameCursor = ARG_LIMIT;
19804
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1434
        final int NEXT_MH     = customized ? -1 : nameCursor++;
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1435
        final int REINVOKE    = nameCursor++;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1436
        LambdaForm.Name[] names = LambdaForm.arguments(nameCursor - ARG_LIMIT, mtype.invokerType());
19804
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1437
        Object[] targetArgs;
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1438
        MethodHandle targetMH;
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1439
        if (customized) {
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1440
            targetArgs = Arrays.copyOfRange(names, ARG_BASE, ARG_LIMIT, Object[].class);
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1441
            targetMH = customTargetOrNull;
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1442
        } else {
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1443
            names[NEXT_MH] = new LambdaForm.Name(NF_reinvokerTarget, names[THIS_BMH]);
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1444
            targetArgs = Arrays.copyOfRange(names, THIS_BMH, ARG_LIMIT, Object[].class);
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1445
            targetArgs[0] = names[NEXT_MH];  // overwrite this MH with next MH
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1446
            targetMH = MethodHandles.basicInvoker(mtype);
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1447
        }
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1448
        names[REINVOKE] = new LambdaForm.Name(targetMH, targetArgs);
83170920c07b 8008688: Make MethodHandleInfo public
rfield
parents: 18569
diff changeset
  1449
        return new LambdaForm("BMH.reinvoke", ARG_LIMIT, names);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1450
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1451
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1452
    private static final LambdaForm.NamedFunction NF_reinvokerTarget;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1453
    static {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1454
        try {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1455
            NF_reinvokerTarget = new LambdaForm.NamedFunction(MethodHandle.class
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1456
                .getDeclaredMethod("reinvokerTarget"));
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1457
        } catch (ReflectiveOperationException ex) {
14089
0a41b980d62a 8000989: smaller code changes to make future JSR 292 backports easier
twisti
parents: 13610
diff changeset
  1458
            throw newInternalError(ex);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1459
        }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1460
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1461
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1462
    /**
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1463
     * Replace the old lambda form of this method handle with a new one.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1464
     * The new one must be functionally equivalent to the old one.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1465
     * Threads may continue running the old form indefinitely,
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1466
     * but it is likely that the new one will be preferred for new executions.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1467
     * Use with discretion.
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1468
     */
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1469
    /*non-public*/
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1470
    void updateForm(LambdaForm newForm) {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1471
        if (form == newForm)  return;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1472
        // ISSUE: Should we have a memory fence here?
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1473
        UNSAFE.putObject(this, FORM_OFFSET, newForm);
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1474
        this.form.prepare();  // as in MethodHandle.<init>
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1475
    }
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1476
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1477
    private static final long FORM_OFFSET;
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1478
    static {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1479
        try {
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1480
            FORM_OFFSET = UNSAFE.objectFieldOffset(MethodHandle.class.getDeclaredField("form"));
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1481
        } catch (ReflectiveOperationException ex) {
14089
0a41b980d62a 8000989: smaller code changes to make future JSR 292 backports easier
twisti
parents: 13610
diff changeset
  1482
            throw newInternalError(ex);
13423
17843fff200d 7023639: JSR 292 method handle invocation needs a fast path for compiled code
twisti
parents: 11513
diff changeset
  1483
        }
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7554
diff changeset
  1484
    }
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
  1485
}