1 /* 2 * Copyright (c) 2008, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 * The {@code java.lang.invoke} package contains dynamic language support provided directly by 28 * the Java core class libraries and virtual machine. 29 * 30 * <p> 31 * As described in the Java Virtual Machine Specification, 32 * certain types in this package have special relations to dynamic 33 * language support in the virtual machine: 34 * <ul> 35 * <li>The classes {@link java.lang.invoke.MethodHandle MethodHandle} 36 * {@link java.lang.invoke.VarHandle VarHandle} contain 37 * <a href="MethodHandle.html#sigpoly">signature polymorphic methods</a> 38 * which can be linked regardless of their type descriptor. 39 * Normally, method linkage requires exact matching of type descriptors. 40 * </li> 41 * 42 * <li>The JVM bytecode format supports immediate constants of 43 * the classes {@link java.lang.invoke.MethodHandle MethodHandle} and {@link java.lang.invoke.MethodType MethodType}. 44 * </li> 45 * </ul> 46 * 47 * <h1><a name="jvm_mods"></a>Summary of relevant Java Virtual Machine changes</h1> 48 * The following low-level information summarizes relevant parts of the 49 * Java Virtual Machine specification. For full details, please see the 50 * current version of that specification. 51 * 52 * Each occurrence of an {@code invokedynamic} instruction is called a <em>dynamic call site</em>. 53 * <h2><a name="indyinsn"></a>{@code invokedynamic} instructions</h2> 54 * A dynamic call site is originally in an unlinked state. In this state, there is 55 * no target method for the call site to invoke. 56 * <p> 57 * Before the JVM can execute a dynamic call site (an {@code invokedynamic} instruction), 58 * the call site must first be <em>linked</em>. 59 * Linking is accomplished by calling a <em>bootstrap method</em> 60 * which is given the static information content of the call site, 61 * and which must produce a {@link java.lang.invoke.MethodHandle method handle} 62 * that gives the behavior of the call site. 63 * <p> 64 * Each {@code invokedynamic} instruction statically specifies its own 65 * bootstrap method as a constant pool reference. 66 * The constant pool reference also specifies the call site's name and type descriptor, 67 * just like {@code invokevirtual} and the other invoke instructions. 68 * <p> 69 * Linking starts with resolving the constant pool entry for the 70 * bootstrap method, and resolving a {@link java.lang.invoke.MethodType MethodType} object for 71 * the type descriptor of the dynamic call site. 72 * This resolution process may trigger class loading. 73 * It may therefore throw an error if a class fails to load. 74 * This error becomes the abnormal termination of the dynamic 75 * call site execution. 76 * Linkage does not trigger class initialization. 77 * <p> 78 * The bootstrap method is invoked on at least three values: 79 * <ul> 80 * <li>a {@code MethodHandles.Lookup}, a lookup object on the <em>caller class</em> in which dynamic call site occurs </li> 81 * <li>a {@code String}, the method name mentioned in the call site </li> 82 * <li>a {@code MethodType}, the resolved type descriptor of the call </li> 83 * <li>optionally, between 1 and 251 additional static arguments taken from the constant pool </li> 84 * </ul> 85 * Invocation is as if by 86 * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke}. 87 * The returned result must be a {@link java.lang.invoke.CallSite CallSite} 88 * (or a subclass), otherwise a 89 * {@link java.lang.BootstrapMethodError BootstrapMethodError} is thrown. 90 * The type of the call site's target must be exactly equal to the type 91 * derived from the dynamic call site's type descriptor and passed to 92 * the bootstrap method, otherwise a {@code BootstrapMethodError} is thrown. 93 * On success the call site then becomes permanently linked to the dynamic call 94 * site. 95 * <p> 96 * If an exception, {@code E} say, occurs when linking the call site then the 97 * linkage fails and terminates abnormally. {@code E} is rethrown if the type of 98 * {@code E} is {@code Error} or a subclass, otherwise a 99 * {@code BootstrapMethodError} that wraps {@code E} is thrown. 100 * If this happens, the same {@code Error} or subclass will the thrown for all 101 * subsequent attempts to execute the dynamic call site. 102 * <h2>timing of linkage</h2> 103 * A dynamic call site is linked just before its first execution. 104 * The bootstrap method call implementing the linkage occurs within 105 * a thread that is attempting a first execution. 106 * <p> 107 * If there are several such threads, the bootstrap method may be 108 * invoked in several threads concurrently. 109 * Therefore, bootstrap methods which access global application 110 * data must take the usual precautions against race conditions. 111 * In any case, every {@code invokedynamic} instruction is either 112 * unlinked or linked to a unique {@code CallSite} object. 113 * <p> 114 * In an application which requires dynamic call sites with individually 115 * mutable behaviors, their bootstrap methods should produce distinct 116 * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request. 117 * Alternatively, an application can link a single {@code CallSite} object 118 * to several {@code invokedynamic} instructions, in which case 119 * a change to the target method will become visible at each of 120 * the instructions. 121 * <p> 122 * If several threads simultaneously execute a bootstrap method for a single dynamic 123 * call site, the JVM must choose one {@code CallSite} object and install it visibly to 124 * all threads. Any other bootstrap method calls are allowed to complete, but their 125 * results are ignored, and their dynamic call site invocations proceed with the originally 126 * chosen target object. 127 128 * <p style="font-size:smaller;"> 129 * <em>Discussion:</em> 130 * These rules do not enable the JVM to duplicate dynamic call sites, 131 * or to issue “causeless” bootstrap method calls. 132 * Every dynamic call site transitions at most once from unlinked to linked, 133 * just before its first invocation. 134 * There is no way to undo the effect of a completed bootstrap method call. 135 * 136 * <h2>types of bootstrap methods</h2> 137 * As long as each bootstrap method can be correctly invoked 138 * by {@code MethodHandle.invoke}, its detailed type is arbitrary. 139 * For example, the first argument could be {@code Object} 140 * instead of {@code MethodHandles.Lookup}, and the return type 141 * could also be {@code Object} instead of {@code CallSite}. 142 * (Note that the types and number of the stacked arguments limit 143 * the legal kinds of bootstrap methods to appropriately typed 144 * static methods and constructors of {@code CallSite} subclasses.) 145 * <p> 146 * If a given {@code invokedynamic} instruction specifies no static arguments, 147 * the instruction's bootstrap method will be invoked on three arguments, 148 * conveying the instruction's caller class, name, and method type. 149 * If the {@code invokedynamic} instruction specifies one or more static arguments, 150 * those values will be passed as additional arguments to the method handle. 151 * (Note that because there is a limit of 255 arguments to any method, 152 * at most 251 extra arguments can be supplied, since the bootstrap method 153 * handle itself and its first three arguments must also be stacked.) 154 * The bootstrap method will be invoked as if by either {@code MethodHandle.invoke} 155 * or {@code invokeWithArguments}. (There is no way to tell the difference.) 156 * <p> 157 * The normal argument conversion rules for {@code MethodHandle.invoke} apply to all stacked arguments. 158 * For example, if a pushed value is a primitive type, it may be converted to a reference by boxing conversion. 159 * If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set), 160 * then some or all of the arguments specified here may be collected into a trailing array parameter. 161 * (This is not a special rule, but rather a useful consequence of the interaction 162 * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, 163 * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.) 164 * <p> 165 * Given these rules, here are examples of legal bootstrap method declarations, 166 * given various numbers {@code N} of extra arguments. 167 * The first rows (marked {@code *}) will work for any number of extra arguments. 168 * <table border=1 cellpadding=5 summary="Static argument types"> 169 * <tr><th>N</th><th>sample bootstrap method</th></tr> 170 * <tr><td>*</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr> 171 * <tr><td>*</td><td><code>CallSite bootstrap(Object... args)</code></td></tr> 172 * <tr><td>*</td><td><code>CallSite bootstrap(Object caller, Object... nameAndTypeWithArgs)</code></td></tr> 173 * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type)</code></td></tr> 174 * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, Object... nameAndType)</code></td></tr> 175 * <tr><td>1</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)</code></td></tr> 176 * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr> 177 * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, String... args)</code></td></tr> 178 * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, String x, int y)</code></td></tr> 179 * </table> 180 * The last example assumes that the extra arguments are of type 181 * {@code CONSTANT_String} and {@code CONSTANT_Integer}, respectively. 182 * The second-to-last example assumes that all extra arguments are of type 183 * {@code CONSTANT_String}. 184 * The other examples work with all types of extra arguments. 185 * <p> 186 * As noted above, the actual method type of the bootstrap method can vary. 187 * For example, the fourth argument could be {@code MethodHandle}, 188 * if that is the type of the corresponding constant in 189 * the {@code CONSTANT_InvokeDynamic} entry. 190 * In that case, the {@code MethodHandle.invoke} call will pass the extra method handle 191 * constant as an {@code Object}, but the type matching machinery of {@code MethodHandle.invoke} 192 * will cast the reference back to {@code MethodHandle} before invoking the bootstrap method. 193 * (If a string constant were passed instead, by badly generated code, that cast would then fail, 194 * resulting in a {@code BootstrapMethodError}.) 195 * <p> 196 * Note that, as a consequence of the above rules, the bootstrap method may accept a primitive 197 * argument, if it can be represented by a constant pool entry. 198 * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} 199 * cannot be created for bootstrap methods, since such constants cannot be directly 200 * represented in the constant pool, and the invocation of the bootstrap method will 201 * not perform the necessary narrowing primitive conversions. 202 * <p> 203 * Extra bootstrap method arguments are intended to allow language implementors 204 * to safely and compactly encode metadata. 205 * In principle, the name and extra arguments are redundant, 206 * since each call site could be given its own unique bootstrap method. 207 * Such a practice is likely to produce large class files and constant pools. 208 * 209 * @author John Rose, JSR 292 EG 210 * @since 1.7 211 */ 212 213 package java.lang.invoke;