1 /* 2 * Copyright (c) 2012, 2013, 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 package java.lang.invoke; 27 28 import java.io.Serializable; 29 import java.util.Arrays; 30 31 /** 32 * <p>Methods to facilitate the creation of simple "function objects" that 33 * implement one or more interfaces by delegation to a provided {@link MethodHandle}, 34 * possibly after type adaptation and partial evaluation of arguments. These 35 * methods are typically used as <em>bootstrap methods</em> for {@code invokedynamic} 36 * call sites, to support the <em>lambda expression</em> and <em>method 37 * reference expression</em> features of the Java Programming Language. 38 * 39 * <p>Indirect access to the behavior specified by the provided {@code MethodHandle} 40 * proceeds in order through three phases: 41 * <ul> 42 * <li><em>Linkage</em> occurs when the methods in this class are invoked. 43 * They take as arguments an interface to be implemented (typically a 44 * <em>functional interface</em>, one with a single abstract method), a 45 * name and signature of a method from that interface to be implemented, a 46 * method handle describing the desired implementation behavior 47 * for that method, and possibly other additional metadata, and produce a 48 * {@link CallSite} whose target can be used to create suitable function 49 * objects. Linkage may involve dynamically loading a new class that 50 * implements the target interface. The {@code CallSite} can be considered a 51 * "factory" for function objects and so these linkage methods are referred 52 * to as "metafactories".</li> 53 * 54 * <li><em>Capture</em> occurs when the {@code CallSite}'s target is 55 * invoked, typically through an {@code invokedynamic} call site, 56 * producing a function object. This may occur many times for 57 * a single factory {@code CallSite}. Capture may involve allocation of a 58 * new function object, or may return an existing function object. The 59 * behavior {@code MethodHandle} may have additional parameters beyond those 60 * of the specified interface method; these are referred to as <em>captured 61 * parameters</em>, which must be provided as arguments to the 62 * {@code CallSite} target, and which may be early-bound to the behavior 63 * {@code MethodHandle}. The number of captured parameters and their types 64 * are determined during linkage.</li> 65 * 66 * <li><em>Invocation</em> occurs when an implemented interface method 67 * is invoked on a function object. This may occur many times for a single 68 * function object. The method referenced by the behavior {@code MethodHandle} 69 * is invoked with the captured arguments and any additional arguments 70 * provided on invocation, as if by {@link MethodHandle#invoke(Object...)}.</li> 71 * </ul> 72 * 73 * <p>It is sometimes useful to restrict the set of inputs or results permitted 74 * at invocation. For example, when the generic interface {@code Predicate<T>} 75 * is parameterized as {@code Predicate<String>}, the input must be a 76 * {@code String}, even though the method to implement allows any {@code Object}. 77 * At linkage time, an additional {@link MethodType} parameter describes the 78 * "instantiated" method type; on invocation, the arguments and eventual result 79 * are checked against this {@code MethodType}. 80 * 81 * <p>This class provides two forms of linkage methods: a standard version 82 * ({@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)}) 83 * using an optimized protocol, and an alternate version 84 * {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}). 85 * The alternate version is a generalization of the standard version, providing 86 * additional control over the behavior of the generated function objects via 87 * flags and additional arguments. The alternate version adds the ability to 88 * manage the following attributes of function objects: 89 * 90 * <ul> 91 * <li><em>Bridging.</em> It is sometimes useful to implement multiple 92 * variations of the method signature, involving argument or return type 93 * adaptation. This occurs when multiple distinct VM signatures for a method 94 * are logically considered to be the same method by the language. The 95 * flag {@code FLAG_BRIDGES} indicates that a list of additional 96 * {@code MethodType}s will be provided, each of which will be implemented 97 * by the resulting function object. These methods will share the same 98 * name and instantiated type.</li> 99 * 100 * <li><em>Multiple interfaces.</em> If needed, more than one interface 101 * can be implemented by the function object. (These additional interfaces 102 * are typically marker interfaces with no methods.) The flag {@code FLAG_MARKERS} 103 * indicates that a list of additional interfaces will be provided, each of 104 * which should be implemented by the resulting function object.</li> 105 * 106 * <li><em>Serializability.</em> The generated function objects do not 107 * generally support serialization. If desired, {@code FLAG_SERIALIZABLE} 108 * can be used to indicate that the function objects should be serializable. 109 * Serializable function objects will use, as their serialized form, 110 * instances of the class {@code SerializedLambda}, which requires additional 111 * assistance from the capturing class (the class described by the 112 * {@link MethodHandles.Lookup} parameter {@code caller}); see 113 * {@link SerializedLambda} for details.</li> 114 * </ul> 115 * 116 * <p>Assume the linkage arguments are as follows: 117 * <ul> 118 * <li>{@code invokedType} (describing the {@code CallSite} signature) has 119 * K parameters of types (D1..Dk) and return type Rd;</li> 120 * <li>{@code samMethodType} (describing the implemented method type) has N 121 * parameters, of types (U1..Un) and return type Ru;</li> 122 * <li>{@code implMethod} (the {@code MethodHandle} providing the 123 * implementation has M parameters, of types (A1..Am) and return type Ra 124 * (if the method describes an instance method, the method type of this 125 * method handle already includes an extra first argument corresponding to 126 * the receiver);</li> 127 * <li>{@code instantiatedMethodType} (allowing restrictions on invocation) 128 * has N parameters, of types (T1..Tn) and return type Rt.</li> 129 * </ul> 130 * 131 * <p>Then the following linkage invariants must hold: 132 * <ul> 133 * <li>Rd is an interface</li> 134 * <li>{@code implMethod} is a <em>direct method handle</em></li> 135 * <li>{@code samMethodType} and {@code instantiatedMethodType} have the same 136 * arity N, and for i=1..N, Ti and Ui are the same type, or Ti and Ui are 137 * both reference types and Ti is a subtype of Ui</li> 138 * <li>Either Rt and Ru are the same type, or both are reference types and 139 * Rt is a subtype of Ru</li> 140 * <li>K + N = M</li> 141 * <li>For i=1..K, Di = Ai</li> 142 * <li>For i=1..N, Ti is adaptable to Aj, where j=i+k</li> 143 * <li>The return type Rt is void, or the return type Ra is not void and is 144 * adaptable to Rt</li> 145 * </ul> 146 * 147 * <p>Further, at capture time, if {@code implMethod} corresponds to an instance 148 * method, and there are any capture arguments ({@code K > 0}), then the first 149 * capture argument (corresponding to the receiver) must be non-null. 150 * 151 * <p>A type Q is considered adaptable to S as follows: 152 * <table class="borderless"> 153 * <caption style="display:none">adaptable types</caption> 154 * <thead> 155 * <tr><th>Q</th><th>S</th><th>Link-time checks</th><th>Invocation-time checks</th></tr> 156 * </thead> 157 * <tbody> 158 * <tr> 159 * <td>Primitive</td><td>Primitive</td> 160 * <td>Q can be converted to S via a primitive widening conversion</td> 161 * <td>None</td> 162 * </tr> 163 * <tr> 164 * <td>Primitive</td><td>Reference</td> 165 * <td>S is a supertype of the Wrapper(Q)</td> 166 * <td>Cast from Wrapper(Q) to S</td> 167 * </tr> 168 * <tr> 169 * <td>Reference</td><td>Primitive</td> 170 * <td>for parameter types: Q is a primitive wrapper and Primitive(Q) 171 * can be widened to S 172 * <br>for return types: If Q is a primitive wrapper, check that 173 * Primitive(Q) can be widened to S</td> 174 * <td>If Q is not a primitive wrapper, cast Q to the base Wrapper(S); 175 * for example Number for numeric types</td> 176 * </tr> 177 * <tr> 178 * <td>Reference</td><td>Reference</td> 179 * <td>for parameter types: S is a supertype of Q 180 * <br>for return types: none</td> 181 * <td>Cast from Q to S</td> 182 * </tr> 183 * </tbody> 184 * </table> 185 * 186 * @apiNote These linkage methods are designed to support the evaluation 187 * of <em>lambda expressions</em> and <em>method references</em> in the Java 188 * Language. For every lambda expressions or method reference in the source code, 189 * there is a target type which is a functional interface. Evaluating a lambda 190 * expression produces an object of its target type. The recommended mechanism 191 * for evaluating lambda expressions is to desugar the lambda body to a method, 192 * invoke an invokedynamic call site whose static argument list describes the 193 * sole method of the functional interface and the desugared implementation 194 * method, and returns an object (the lambda object) that implements the target 195 * type. (For method references, the implementation method is simply the 196 * referenced method; no desugaring is needed.) 197 * 198 * <p>The argument list of the implementation method and the argument list of 199 * the interface method(s) may differ in several ways. The implementation 200 * methods may have additional arguments to accommodate arguments captured by 201 * the lambda expression; there may also be differences resulting from permitted 202 * adaptations of arguments, such as casting, boxing, unboxing, and primitive 203 * widening. (Varargs adaptations are not handled by the metafactories; these are 204 * expected to be handled by the caller.) 205 * 206 * <p>Invokedynamic call sites have two argument lists: a static argument list 207 * and a dynamic argument list. The static argument list is stored in the 208 * constant pool; the dynamic argument is pushed on the operand stack at capture 209 * time. The bootstrap method has access to the entire static argument list 210 * (which in this case, includes information describing the implementation method, 211 * the target interface, and the target interface method(s)), as well as a 212 * method signature describing the number and static types (but not the values) 213 * of the dynamic arguments and the static return type of the invokedynamic site. 214 * 215 * @implNote The implementation method is described with a method handle. In 216 * theory, any method handle could be used. Currently supported are direct method 217 * handles representing invocation of virtual, interface, constructor and static 218 * methods. 219 * @since 1.8 220 */ 221 public final class LambdaMetafactory { 222 223 private LambdaMetafactory() {} 224 225 /** Flag for alternate metafactories indicating the lambda object 226 * must be serializable */ 227 public static final int FLAG_SERIALIZABLE = 1 << 0; 228 229 /** 230 * Flag for alternate metafactories indicating the lambda object implements 231 * other marker interfaces 232 * besides Serializable 233 */ 234 public static final int FLAG_MARKERS = 1 << 1; 235 236 /** 237 * Flag for alternate metafactories indicating the lambda object requires 238 * additional bridge methods 239 */ 240 public static final int FLAG_BRIDGES = 1 << 2; 241 242 private static final Class<?>[] EMPTY_CLASS_ARRAY = new Class<?>[0]; 243 private static final MethodType[] EMPTY_MT_ARRAY = new MethodType[0]; 244 245 /** 246 * Facilitates the creation of simple "function objects" that implement one 247 * or more interfaces by delegation to a provided {@link MethodHandle}, 248 * after appropriate type adaptation and partial evaluation of arguments. 249 * Typically used as a <em>bootstrap method</em> for {@code invokedynamic} 250 * call sites, to support the <em>lambda expression</em> and <em>method 251 * reference expression</em> features of the Java Programming Language. 252 * 253 * <p>This is the standard, streamlined metafactory; additional flexibility 254 * is provided by {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}. 255 * A general description of the behavior of this method is provided 256 * {@link LambdaMetafactory above}. 257 * 258 * <p>When the target of the {@code CallSite} returned from this method is 259 * invoked, the resulting function objects are instances of a class which 260 * implements the interface named by the return type of {@code invokedType}, 261 * declares a method with the name given by {@code invokedName} and the 262 * signature given by {@code samMethodType}. It may also override additional 263 * methods from {@code Object}. 264 * 265 * @param caller Represents a lookup context with the accessibility 266 * privileges of the caller. When used with {@code invokedynamic}, 267 * this is stacked automatically by the VM. 268 * @param invokedName The name of the method to implement. When used with 269 * {@code invokedynamic}, this is provided by the 270 * {@code NameAndType} of the {@code InvokeDynamic} 271 * structure and is stacked automatically by the VM. 272 * @param invokedType The expected signature of the {@code CallSite}. The 273 * parameter types represent the types of capture variables; 274 * the return type is the interface to implement. When 275 * used with {@code invokedynamic}, this is provided by 276 * the {@code NameAndType} of the {@code InvokeDynamic} 277 * structure and is stacked automatically by the VM. 278 * In the event that the implementation method is an 279 * instance method and this signature has any parameters, 280 * the first parameter in the invocation signature must 281 * correspond to the receiver. 282 * @param samMethodType Signature and return type of method to be implemented 283 * by the function object. 284 * @param implMethod A direct method handle describing the implementation 285 * method which should be called (with suitable adaptation 286 * of argument types, return types, and with captured 287 * arguments prepended to the invocation arguments) at 288 * invocation time. 289 * @param instantiatedMethodType The signature and return type that should 290 * be enforced dynamically at invocation time. 291 * This may be the same as {@code samMethodType}, 292 * or may be a specialization of it. 293 * @return a CallSite whose target can be used to perform capture, generating 294 * instances of the interface named by {@code invokedType} 295 * @throws LambdaConversionException If any of the linkage invariants 296 * described {@link LambdaMetafactory above} 297 * are violated 298 */ 299 public static CallSite metafactory(MethodHandles.Lookup caller, 300 String invokedName, 301 MethodType invokedType, 302 MethodType samMethodType, 303 MethodHandle implMethod, 304 MethodType instantiatedMethodType) 305 throws LambdaConversionException { 306 AbstractValidatingLambdaMetafactory mf; 307 mf = new InnerClassLambdaMetafactory(caller, invokedType, 308 invokedName, samMethodType, 309 implMethod, instantiatedMethodType, 310 false, EMPTY_CLASS_ARRAY, EMPTY_MT_ARRAY); 311 mf.validateMetafactoryArgs(); 312 return mf.buildCallSite(); 313 } 314 315 /** 316 * Facilitates the creation of simple "function objects" that implement one 317 * or more interfaces by delegation to a provided {@link MethodHandle}, 318 * after appropriate type adaptation and partial evaluation of arguments. 319 * Typically used as a <em>bootstrap method</em> for {@code invokedynamic} 320 * call sites, to support the <em>lambda expression</em> and <em>method 321 * reference expression</em> features of the Java Programming Language. 322 * 323 * <p>This is the general, more flexible metafactory; a streamlined version 324 * is provided by {@link #metafactory(java.lang.invoke.MethodHandles.Lookup, 325 * String, MethodType, MethodType, MethodHandle, MethodType)}. 326 * A general description of the behavior of this method is provided 327 * {@link LambdaMetafactory above}. 328 * 329 * <p>The argument list for this method includes three fixed parameters, 330 * corresponding to the parameters automatically stacked by the VM for the 331 * bootstrap method in an {@code invokedynamic} invocation, and an {@code Object[]} 332 * parameter that contains additional parameters. The declared argument 333 * list for this method is: 334 * 335 * <pre>{@code 336 * CallSite altMetafactory(MethodHandles.Lookup caller, 337 * String invokedName, 338 * MethodType invokedType, 339 * Object... args) 340 * }</pre> 341 * 342 * <p>but it behaves as if the argument list is as follows: 343 * 344 * <pre>{@code 345 * CallSite altMetafactory(MethodHandles.Lookup caller, 346 * String invokedName, 347 * MethodType invokedType, 348 * MethodType samMethodType, 349 * MethodHandle implMethod, 350 * MethodType instantiatedMethodType, 351 * int flags, 352 * int markerInterfaceCount, // IF flags has MARKERS set 353 * Class... markerInterfaces, // IF flags has MARKERS set 354 * int bridgeCount, // IF flags has BRIDGES set 355 * MethodType... bridges // IF flags has BRIDGES set 356 * ) 357 * }</pre> 358 * 359 * <p>Arguments that appear in the argument list for 360 * {@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)} 361 * have the same specification as in that method. The additional arguments 362 * are interpreted as follows: 363 * <ul> 364 * <li>{@code flags} indicates additional options; this is a bitwise 365 * OR of desired flags. Defined flags are {@link #FLAG_BRIDGES}, 366 * {@link #FLAG_MARKERS}, and {@link #FLAG_SERIALIZABLE}.</li> 367 * <li>{@code markerInterfaceCount} is the number of additional interfaces 368 * the function object should implement, and is present if and only if the 369 * {@code FLAG_MARKERS} flag is set.</li> 370 * <li>{@code markerInterfaces} is a variable-length list of additional 371 * interfaces to implement, whose length equals {@code markerInterfaceCount}, 372 * and is present if and only if the {@code FLAG_MARKERS} flag is set.</li> 373 * <li>{@code bridgeCount} is the number of additional method signatures 374 * the function object should implement, and is present if and only if 375 * the {@code FLAG_BRIDGES} flag is set.</li> 376 * <li>{@code bridges} is a variable-length list of additional 377 * methods signatures to implement, whose length equals {@code bridgeCount}, 378 * and is present if and only if the {@code FLAG_BRIDGES} flag is set.</li> 379 * </ul> 380 * 381 * <p>Each class named by {@code markerInterfaces} is subject to the same 382 * restrictions as {@code Rd}, the return type of {@code invokedType}, 383 * as described {@link LambdaMetafactory above}. Each {@code MethodType} 384 * named by {@code bridges} is subject to the same restrictions as 385 * {@code samMethodType}, as described {@link LambdaMetafactory above}. 386 * 387 * <p>When FLAG_SERIALIZABLE is set in {@code flags}, the function objects 388 * will implement {@code Serializable}, and will have a {@code writeReplace} 389 * method that returns an appropriate {@link SerializedLambda}. The 390 * {@code caller} class must have an appropriate {@code $deserializeLambda$} 391 * method, as described in {@link SerializedLambda}. 392 * 393 * <p>When the target of the {@code CallSite} returned from this method is 394 * invoked, the resulting function objects are instances of a class with 395 * the following properties: 396 * <ul> 397 * <li>The class implements the interface named by the return type 398 * of {@code invokedType} and any interfaces named by {@code markerInterfaces}</li> 399 * <li>The class declares methods with the name given by {@code invokedName}, 400 * and the signature given by {@code samMethodType} and additional signatures 401 * given by {@code bridges}</li> 402 * <li>The class may override methods from {@code Object}, and may 403 * implement methods related to serialization.</li> 404 * </ul> 405 * 406 * @param caller Represents a lookup context with the accessibility 407 * privileges of the caller. When used with {@code invokedynamic}, 408 * this is stacked automatically by the VM. 409 * @param invokedName The name of the method to implement. When used with 410 * {@code invokedynamic}, this is provided by the 411 * {@code NameAndType} of the {@code InvokeDynamic} 412 * structure and is stacked automatically by the VM. 413 * @param invokedType The expected signature of the {@code CallSite}. The 414 * parameter types represent the types of capture variables; 415 * the return type is the interface to implement. When 416 * used with {@code invokedynamic}, this is provided by 417 * the {@code NameAndType} of the {@code InvokeDynamic} 418 * structure and is stacked automatically by the VM. 419 * In the event that the implementation method is an 420 * instance method and this signature has any parameters, 421 * the first parameter in the invocation signature must 422 * correspond to the receiver. 423 * @param args An {@code Object[]} array containing the required 424 * arguments {@code samMethodType}, {@code implMethod}, 425 * {@code instantiatedMethodType}, {@code flags}, and any 426 * optional arguments, as described 427 * {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)} above} 428 * @return a CallSite whose target can be used to perform capture, generating 429 * instances of the interface named by {@code invokedType} 430 * @throws LambdaConversionException If any of the linkage invariants 431 * described {@link LambdaMetafactory above} 432 * are violated 433 */ 434 public static CallSite altMetafactory(MethodHandles.Lookup caller, 435 String invokedName, 436 MethodType invokedType, 437 Object... args) 438 throws LambdaConversionException { 439 MethodType samMethodType = (MethodType)args[0]; 440 MethodHandle implMethod = (MethodHandle)args[1]; 441 MethodType instantiatedMethodType = (MethodType)args[2]; 442 int flags = (Integer) args[3]; 443 Class<?>[] markerInterfaces; 444 MethodType[] bridges; 445 int argIndex = 4; 446 if ((flags & FLAG_MARKERS) != 0) { 447 int markerCount = (Integer) args[argIndex++]; 448 markerInterfaces = new Class<?>[markerCount]; 449 System.arraycopy(args, argIndex, markerInterfaces, 0, markerCount); 450 argIndex += markerCount; 451 } 452 else 453 markerInterfaces = EMPTY_CLASS_ARRAY; 454 if ((flags & FLAG_BRIDGES) != 0) { 455 int bridgeCount = (Integer) args[argIndex++]; 456 bridges = new MethodType[bridgeCount]; 457 System.arraycopy(args, argIndex, bridges, 0, bridgeCount); 458 argIndex += bridgeCount; 459 } 460 else 461 bridges = EMPTY_MT_ARRAY; 462 463 boolean isSerializable = ((flags & FLAG_SERIALIZABLE) != 0); 464 if (isSerializable) { 465 boolean foundSerializableSupertype = Serializable.class.isAssignableFrom(invokedType.returnType()); 466 for (Class<?> c : markerInterfaces) 467 foundSerializableSupertype |= Serializable.class.isAssignableFrom(c); 468 if (!foundSerializableSupertype) { 469 markerInterfaces = Arrays.copyOf(markerInterfaces, markerInterfaces.length + 1); 470 markerInterfaces[markerInterfaces.length-1] = Serializable.class; 471 } 472 } 473 474 AbstractValidatingLambdaMetafactory mf 475 = new InnerClassLambdaMetafactory(caller, invokedType, 476 invokedName, samMethodType, 477 implMethod, 478 instantiatedMethodType, 479 isSerializable, 480 markerInterfaces, bridges); 481 mf.validateMetafactoryArgs(); 482 return mf.buildCallSite(); 483 } 484 }