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 summary="adaptable types">
153 * <tr><th>Q</th><th>S</th><th>Link-time checks</th><th>Invocation-time checks</th></tr>
154 * <tr>
155 * <td>Primitive</td><td>Primitive</td>
156 * <td>Q can be converted to S via a primitive widening conversion</td>
157 * <td>None</td>
158 * </tr>
159 * <tr>
160 * <td>Primitive</td><td>Reference</td>
161 * <td>S is a supertype of the Wrapper(Q)</td>
162 * <td>Cast from Wrapper(Q) to S</td>
163 * </tr>
164 * <tr>
165 * <td>Reference</td><td>Primitive</td>
166 * <td>for parameter types: Q is a primitive wrapper and Primitive(Q)
167 * can be widened to S
168 * <br>for return types: If Q is a primitive wrapper, check that
169 * Primitive(Q) can be widened to S</td>
170 * <td>If Q is not a primitive wrapper, cast Q to the base Wrapper(S);
171 * for example Number for numeric types</td>
172 * </tr>
173 * <tr>
174 * <td>Reference</td><td>Reference</td>
175 * <td>for parameter types: S is a supertype of Q
176 * <br>for return types: none</td>
177 * <td>Cast from Q to S</td>
178 * </tr>
179 * </table>
180 *
181 * @apiNote These linkage methods are designed to support the evaluation
182 * of <em>lambda expressions</em> and <em>method references</em> in the Java
183 * Language. For every lambda expressions or method reference in the source code,
184 * there is a target type which is a functional interface. Evaluating a lambda
185 * expression produces an object of its target type. The recommended mechanism
186 * for evaluating lambda expressions is to desugar the lambda body to a method,
187 * invoke an invokedynamic call site whose static argument list describes the
188 * sole method of the functional interface and the desugared implementation
189 * method, and returns an object (the lambda object) that implements the target
190 * type. (For method references, the implementation method is simply the
191 * referenced method; no desugaring is needed.)
192 *
193 * <p>The argument list of the implementation method and the argument list of
194 * the interface method(s) may differ in several ways. The implementation
195 * methods may have additional arguments to accommodate arguments captured by
196 * the lambda expression; there may also be differences resulting from permitted
197 * adaptations of arguments, such as casting, boxing, unboxing, and primitive
198 * widening. (Varargs adaptations are not handled by the metafactories; these are
199 * expected to be handled by the caller.)
200 *
201 * <p>Invokedynamic call sites have two argument lists: a static argument list
202 * and a dynamic argument list. The static argument list is stored in the
203 * constant pool; the dynamic argument is pushed on the operand stack at capture
204 * time. The bootstrap method has access to the entire static argument list
205 * (which in this case, includes information describing the implementation method,
206 * the target interface, and the target interface method(s)), as well as a
207 * method signature describing the number and static types (but not the values)
208 * of the dynamic arguments and the static return type of the invokedynamic site.
209 *
210 * @implNote The implementation method is described with a method handle. In
211 * theory, any method handle could be used. Currently supported are direct method
212 * handles representing invocation of virtual, interface, constructor and static
213 * methods.
214 */
215 public class LambdaMetafactory {
216
217 /** Flag for alternate metafactories indicating the lambda object
218 * must be serializable */
219 public static final int FLAG_SERIALIZABLE = 1 << 0;
220
221 /**
222 * Flag for alternate metafactories indicating the lambda object implements
223 * other marker interfaces
224 * besides Serializable
225 */
226 public static final int FLAG_MARKERS = 1 << 1;
227
228 /**
229 * Flag for alternate metafactories indicating the lambda object requires
230 * additional bridge methods
231 */
232 public static final int FLAG_BRIDGES = 1 << 2;
233
234 private static final Class<?>[] EMPTY_CLASS_ARRAY = new Class<?>[0];
235 private static final MethodType[] EMPTY_MT_ARRAY = new MethodType[0];
236
237 /**
238 * Facilitates the creation of simple "function objects" that implement one
239 * or more interfaces by delegation to a provided {@link MethodHandle},
240 * after appropriate type adaptation and partial evaluation of arguments.
241 * Typically used as a <em>bootstrap method</em> for {@code invokedynamic}
242 * call sites, to support the <em>lambda expression</em> and <em>method
243 * reference expression</em> features of the Java Programming Language.
244 *
245 * <p>This is the standard, streamlined metafactory; additional flexibility
246 * is provided by {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}.
247 * A general description of the behavior of this method is provided
248 * {@link LambdaMetafactory above}.
249 *
250 * <p>When the target of the {@code CallSite} returned from this method is
251 * invoked, the resulting function objects are instances of a class which
252 * implements the interface named by the return type of {@code invokedType},
253 * declares a method with the name given by {@code invokedName} and the
254 * signature given by {@code samMethodType}. It may also override additional
255 * methods from {@code Object}.
256 *
257 * @param caller Represents a lookup context with the accessibility
258 * privileges of the caller. When used with {@code invokedynamic},
259 * this is stacked automatically by the VM.
260 * @param invokedName The name of the method to implement. When used with
261 * {@code invokedynamic}, this is provided by the
262 * {@code NameAndType} of the {@code InvokeDynamic}
263 * structure and is stacked automatically by the VM.
264 * @param invokedType The expected signature of the {@code CallSite}. The
265 * parameter types represent the types of capture variables;
266 * the return type is the interface to implement. When
267 * used with {@code invokedynamic}, this is provided by
268 * the {@code NameAndType} of the {@code InvokeDynamic}
269 * structure and is stacked automatically by the VM.
270 * In the event that the implementation method is an
271 * instance method and this signature has any parameters,
272 * the first parameter in the invocation signature must
273 * correspond to the receiver.
274 * @param samMethodType Signature and return type of method to be implemented
275 * by the function object.
276 * @param implMethod A direct method handle describing the implementation
277 * method which should be called (with suitable adaptation
278 * of argument types, return types, and with captured
279 * arguments prepended to the invocation arguments) at
280 * invocation time.
281 * @param instantiatedMethodType The signature and return type that should
282 * be enforced dynamically at invocation time.
283 * This may be the same as {@code samMethodType},
284 * or may be a specialization of it.
285 * @return a CallSite whose target can be used to perform capture, generating
286 * instances of the interface named by {@code invokedType}
287 * @throws LambdaConversionException If any of the linkage invariants
288 * described {@link LambdaMetafactory above}
289 * are violated
290 */
291 public static CallSite metafactory(MethodHandles.Lookup caller,
292 String invokedName,
293 MethodType invokedType,
294 MethodType samMethodType,
295 MethodHandle implMethod,
296 MethodType instantiatedMethodType)
297 throws LambdaConversionException {
298 AbstractValidatingLambdaMetafactory mf;
299 mf = new InnerClassLambdaMetafactory(caller, invokedType,
300 invokedName, samMethodType,
301 implMethod, instantiatedMethodType,
302 false, EMPTY_CLASS_ARRAY, EMPTY_MT_ARRAY);
303 mf.validateMetafactoryArgs();
304 return mf.buildCallSite();
305 }
306
307 /**
308 * Facilitates the creation of simple "function objects" that implement one
309 * or more interfaces by delegation to a provided {@link MethodHandle},
310 * after appropriate type adaptation and partial evaluation of arguments.
311 * Typically used as a <em>bootstrap method</em> for {@code invokedynamic}
312 * call sites, to support the <em>lambda expression</em> and <em>method
313 * reference expression</em> features of the Java Programming Language.
314 *
315 * <p>This is the general, more flexible metafactory; a streamlined version
316 * is provided by {@link #metafactory(java.lang.invoke.MethodHandles.Lookup,
317 * String, MethodType, MethodType, MethodHandle, MethodType)}.
318 * A general description of the behavior of this method is provided
319 * {@link LambdaMetafactory above}.
320 *
321 * <p>The argument list for this method includes three fixed parameters,
322 * corresponding to the parameters automatically stacked by the VM for the
323 * bootstrap method in an {@code invokedynamic} invocation, and an {@code Object[]}
324 * parameter that contains additional parameters. The declared argument
325 * list for this method is:
326 *
327 * <pre>{@code
328 * CallSite altMetafactory(MethodHandles.Lookup caller,
329 * String invokedName,
330 * MethodType invokedType,
331 * Object... args)
332 * }</pre>
333 *
334 * <p>but it behaves as if the argument list is as follows:
335 *
336 * <pre>{@code
337 * CallSite altMetafactory(MethodHandles.Lookup caller,
338 * String invokedName,
339 * MethodType invokedType,
340 * MethodType samMethodType,
341 * MethodHandle implMethod,
342 * MethodType instantiatedMethodType,
343 * int flags,
344 * int markerInterfaceCount, // IF flags has MARKERS set
345 * Class... markerInterfaces, // IF flags has MARKERS set
346 * int bridgeCount, // IF flags has BRIDGES set
347 * MethodType... bridges // IF flags has BRIDGES set
348 * )
349 * }</pre>
350 *
351 * <p>Arguments that appear in the argument list for
352 * {@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)}
353 * have the same specification as in that method. The additional arguments
354 * are interpreted as follows:
355 * <ul>
356 * <li>{@code flags} indicates additional options; this is a bitwise
357 * OR of desired flags. Defined flags are {@link #FLAG_BRIDGES},
358 * {@link #FLAG_MARKERS}, and {@link #FLAG_SERIALIZABLE}.</li>
359 * <li>{@code markerInterfaceCount} is the number of additional interfaces
360 * the function object should implement, and is present if and only if the
361 * {@code FLAG_MARKERS} flag is set.</li>
362 * <li>{@code markerInterfaces} is a variable-length list of additional
363 * interfaces to implement, whose length equals {@code markerInterfaceCount},
364 * and is present if and only if the {@code FLAG_MARKERS} flag is set.</li>
365 * <li>{@code bridgeCount} is the number of additional method signatures
366 * the function object should implement, and is present if and only if
367 * the {@code FLAG_BRIDGES} flag is set.</li>
368 * <li>{@code bridges} is a variable-length list of additional
369 * methods signatures to implement, whose length equals {@code bridgeCount},
370 * and is present if and only if the {@code FLAG_BRIDGES} flag is set.</li>
371 * </ul>
372 *
373 * <p>Each class named by {@code markerInterfaces} is subject to the same
374 * restrictions as {@code Rd}, the return type of {@code invokedType},
375 * as described {@link LambdaMetafactory above}. Each {@code MethodType}
376 * named by {@code bridges} is subject to the same restrictions as
377 * {@code samMethodType}, as described {@link LambdaMetafactory above}.
378 *
379 * <p>When FLAG_SERIALIZABLE is set in {@code flags}, the function objects
380 * will implement {@code Serializable}, and will have a {@code writeReplace}
381 * method that returns an appropriate {@link SerializedLambda}. The
382 * {@code caller} class must have an appropriate {@code $deserializeLambda$}
383 * method, as described in {@link SerializedLambda}.
384 *
385 * <p>When the target of the {@code CallSite} returned from this method is
386 * invoked, the resulting function objects are instances of a class with
387 * the following properties:
388 * <ul>
389 * <li>The class implements the interface named by the return type
390 * of {@code invokedType} and any interfaces named by {@code markerInterfaces}</li>
391 * <li>The class declares methods with the name given by {@code invokedName},
392 * and the signature given by {@code samMethodType} and additional signatures
393 * given by {@code bridges}</li>
394 * <li>The class may override methods from {@code Object}, and may
395 * implement methods related to serialization.</li>
396 * </ul>
397 *
398 * @param caller Represents a lookup context with the accessibility
399 * privileges of the caller. When used with {@code invokedynamic},
400 * this is stacked automatically by the VM.
401 * @param invokedName The name of the method to implement. When used with
402 * {@code invokedynamic}, this is provided by the
403 * {@code NameAndType} of the {@code InvokeDynamic}
404 * structure and is stacked automatically by the VM.
405 * @param invokedType The expected signature of the {@code CallSite}. The
406 * parameter types represent the types of capture variables;
407 * the return type is the interface to implement. When
408 * used with {@code invokedynamic}, this is provided by
409 * the {@code NameAndType} of the {@code InvokeDynamic}
410 * structure and is stacked automatically by the VM.
411 * In the event that the implementation method is an
412 * instance method and this signature has any parameters,
413 * the first parameter in the invocation signature must
414 * correspond to the receiver.
415 * @param args An {@code Object[]} array containing the required
416 * arguments {@code samMethodType}, {@code implMethod},
417 * {@code instantiatedMethodType}, {@code flags}, and any
418 * optional arguments, as described
419 * {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)} above}
420 * @return a CallSite whose target can be used to perform capture, generating
421 * instances of the interface named by {@code invokedType}
422 * @throws LambdaConversionException If any of the linkage invariants
423 * described {@link LambdaMetafactory above}
424 * are violated
425 */
426 public static CallSite altMetafactory(MethodHandles.Lookup caller,
427 String invokedName,
428 MethodType invokedType,
429 Object... args)
430 throws LambdaConversionException {
431 MethodType samMethodType = (MethodType)args[0];
432 MethodHandle implMethod = (MethodHandle)args[1];
433 MethodType instantiatedMethodType = (MethodType)args[2];
434 int flags = (Integer) args[3];
435 Class<?>[] markerInterfaces;
436 MethodType[] bridges;
437 int argIndex = 4;
438 if ((flags & FLAG_MARKERS) != 0) {
439 int markerCount = (Integer) args[argIndex++];
440 markerInterfaces = new Class<?>[markerCount];
441 System.arraycopy(args, argIndex, markerInterfaces, 0, markerCount);
442 argIndex += markerCount;
443 }
444 else
445 markerInterfaces = EMPTY_CLASS_ARRAY;
446 if ((flags & FLAG_BRIDGES) != 0) {
447 int bridgeCount = (Integer) args[argIndex++];
448 bridges = new MethodType[bridgeCount];
449 System.arraycopy(args, argIndex, bridges, 0, bridgeCount);
450 argIndex += bridgeCount;
451 }
452 else
453 bridges = EMPTY_MT_ARRAY;
454
455 boolean isSerializable = ((flags & FLAG_SERIALIZABLE) != 0);
456 if (isSerializable) {
457 boolean foundSerializableSupertype = Serializable.class.isAssignableFrom(invokedType.returnType());
458 for (Class<?> c : markerInterfaces)
459 foundSerializableSupertype |= Serializable.class.isAssignableFrom(c);
460 if (!foundSerializableSupertype) {
461 markerInterfaces = Arrays.copyOf(markerInterfaces, markerInterfaces.length + 1);
462 markerInterfaces[markerInterfaces.length-1] = Serializable.class;
463 }
464 }
465
466 AbstractValidatingLambdaMetafactory mf
467 = new InnerClassLambdaMetafactory(caller, invokedType,
468 invokedName, samMethodType,
469 implMethod,
470 instantiatedMethodType,
471 isSerializable,
472 markerInterfaces, bridges);
473 mf.validateMetafactoryArgs();
474 return mf.buildCallSite();
475 }
476 }