| /* |
| * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.lang.invoke; |
| |
| import java.io.Serializable; |
| import java.util.Arrays; |
| |
| /** |
| * <p>Methods to facilitate the creation of simple "function objects" that |
| * implement one or more interfaces by delegation to a provided {@link MethodHandle}, |
| * possibly after type adaptation and partial evaluation of arguments. These |
| * methods are typically used as <em>bootstrap methods</em> for {@code invokedynamic} |
| * call sites, to support the <em>lambda expression</em> and <em>method |
| * reference expression</em> features of the Java Programming Language. |
| * |
| * <p>Indirect access to the behavior specified by the provided {@code MethodHandle} |
| * proceeds in order through three phases: |
| * <ul> |
| * <li><em>Linkage</em> occurs when the methods in this class are invoked. |
| * They take as arguments an interface to be implemented (typically a |
| * <em>functional interface</em>, one with a single abstract method), a |
| * name and signature of a method from that interface to be implemented, a |
| * method handle describing the desired implementation behavior |
| * for that method, and possibly other additional metadata, and produce a |
| * {@link CallSite} whose target can be used to create suitable function |
| * objects. Linkage may involve dynamically loading a new class that |
| * implements the target interface. The {@code CallSite} can be considered a |
| * "factory" for function objects and so these linkage methods are referred |
| * to as "metafactories".</li> |
| * |
| * <li><em>Capture</em> occurs when the {@code CallSite}'s target is |
| * invoked, typically through an {@code invokedynamic} call site, |
| * producing a function object. This may occur many times for |
| * a single factory {@code CallSite}. Capture may involve allocation of a |
| * new function object, or may return an existing function object. The |
| * behavior {@code MethodHandle} may have additional parameters beyond those |
| * of the specified interface method; these are referred to as <em>captured |
| * parameters</em>, which must be provided as arguments to the |
| * {@code CallSite} target, and which may be early-bound to the behavior |
| * {@code MethodHandle}. The number of captured parameters and their types |
| * are determined during linkage. |
| * The identity of a function object produced by invoking the |
| * {@code CallSite}'s target is unpredictable, and therefore |
| * identity-sensitive operations (such as reference equality, object |
| * locking, and {@code System.identityHashCode()} may produce different |
| * results in different implementations, or even upon different invocations |
| * in the same implementation.</li> |
| * |
| * <li><em>Invocation</em> occurs when an implemented interface method |
| * is invoked on a function object. This may occur many times for a single |
| * function object. The method referenced by the behavior {@code MethodHandle} |
| * is invoked with the captured arguments and any additional arguments |
| * provided on invocation, as if by {@link MethodHandle#invoke(Object...)}.</li> |
| * </ul> |
| * |
| * <p>It is sometimes useful to restrict the set of inputs or results permitted |
| * at invocation. For example, when the generic interface {@code Predicate<T>} |
| * is parameterized as {@code Predicate<String>}, the input must be a |
| * {@code String}, even though the method to implement allows any {@code Object}. |
| * At linkage time, an additional {@link MethodType} parameter describes the |
| * "instantiated" method type; on invocation, the arguments and eventual result |
| * are checked against this {@code MethodType}. |
| * |
| * <p>This class provides two forms of linkage methods: a standard version |
| * ({@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)}) |
| * using an optimized protocol, and an alternate version |
| * {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}). |
| * The alternate version is a generalization of the standard version, providing |
| * additional control over the behavior of the generated function objects via |
| * flags and additional arguments. The alternate version adds the ability to |
| * manage the following attributes of function objects: |
| * |
| * <ul> |
| * <li><em>Bridging.</em> It is sometimes useful to implement multiple |
| * variations of the method signature, involving argument or return type |
| * adaptation. This occurs when multiple distinct VM signatures for a method |
| * are logically considered to be the same method by the language. The |
| * flag {@code FLAG_BRIDGES} indicates that a list of additional |
| * {@code MethodType}s will be provided, each of which will be implemented |
| * by the resulting function object. These methods will share the same |
| * name and instantiated type.</li> |
| * |
| * <li><em>Multiple interfaces.</em> If needed, more than one interface |
| * can be implemented by the function object. (These additional interfaces |
| * are typically marker interfaces with no methods.) The flag {@code FLAG_MARKERS} |
| * indicates that a list of additional interfaces will be provided, each of |
| * which should be implemented by the resulting function object.</li> |
| * |
| * <li><em>Serializability.</em> The generated function objects do not |
| * generally support serialization. If desired, {@code FLAG_SERIALIZABLE} |
| * can be used to indicate that the function objects should be serializable. |
| * Serializable function objects will use, as their serialized form, |
| * instances of the class {@code SerializedLambda}, which requires additional |
| * assistance from the capturing class (the class described by the |
| * {@link MethodHandles.Lookup} parameter {@code caller}); see |
| * {@link SerializedLambda} for details.</li> |
| * </ul> |
| * |
| * <p>Assume the linkage arguments are as follows: |
| * <ul> |
| * <li>{@code invokedType} (describing the {@code CallSite} signature) has |
| * K parameters of types (D1..Dk) and return type Rd;</li> |
| * <li>{@code samMethodType} (describing the implemented method type) has N |
| * parameters, of types (U1..Un) and return type Ru;</li> |
| * <li>{@code implMethod} (the {@code MethodHandle} providing the |
| * implementation has M parameters, of types (A1..Am) and return type Ra |
| * (if the method describes an instance method, the method type of this |
| * method handle already includes an extra first argument corresponding to |
| * the receiver);</li> |
| * <li>{@code instantiatedMethodType} (allowing restrictions on invocation) |
| * has N parameters, of types (T1..Tn) and return type Rt.</li> |
| * </ul> |
| * |
| * <p>Then the following linkage invariants must hold: |
| * <ul> |
| * <li>Rd is an interface</li> |
| * <li>{@code implMethod} is a <em>direct method handle</em></li> |
| * <li>{@code samMethodType} and {@code instantiatedMethodType} have the same |
| * arity N, and for i=1..N, Ti and Ui are the same type, or Ti and Ui are |
| * both reference types and Ti is a subtype of Ui</li> |
| * <li>Either Rt and Ru are the same type, or both are reference types and |
| * Rt is a subtype of Ru</li> |
| * <li>K + N = M</li> |
| * <li>For i=1..K, Di = Ai</li> |
| * <li>For i=1..N, Ti is adaptable to Aj, where j=i+k</li> |
| * <li>The return type Rt is void, or the return type Ra is not void and is |
| * adaptable to Rt</li> |
| * </ul> |
| * |
| * <p>Further, at capture time, if {@code implMethod} corresponds to an instance |
| * method, and there are any capture arguments ({@code K > 0}), then the first |
| * capture argument (corresponding to the receiver) must be non-null. |
| * |
| * <p>A type Q is considered adaptable to S as follows: |
| * <table class="striped"> |
| * <caption style="display:none">adaptable types</caption> |
| * <thead> |
| * <tr><th scope="col">Q</th><th scope="col">S</th><th scope="col">Link-time checks</th><th scope="col">Invocation-time checks</th></tr> |
| * </thead> |
| * <tbody> |
| * <tr> |
| * <th scope="row">Primitive</th><th scope="row">Primitive</th> |
| * <td>Q can be converted to S via a primitive widening conversion</td> |
| * <td>None</td> |
| * </tr> |
| * <tr> |
| * <th scope="row">Primitive</th><th scope="row">Reference</th> |
| * <td>S is a supertype of the Wrapper(Q)</td> |
| * <td>Cast from Wrapper(Q) to S</td> |
| * </tr> |
| * <tr> |
| * <th scope="row">Reference</th><th scope="row">Primitive</th> |
| * <td>for parameter types: Q is a primitive wrapper and Primitive(Q) |
| * can be widened to S |
| * <br>for return types: If Q is a primitive wrapper, check that |
| * Primitive(Q) can be widened to S</td> |
| * <td>If Q is not a primitive wrapper, cast Q to the base Wrapper(S); |
| * for example Number for numeric types</td> |
| * </tr> |
| * <tr> |
| * <th scope="row">Reference</th><th scope="row">Reference</th> |
| * <td>for parameter types: S is a supertype of Q |
| * <br>for return types: none</td> |
| * <td>Cast from Q to S</td> |
| * </tr> |
| * </tbody> |
| * </table> |
| * |
| * @apiNote These linkage methods are designed to support the evaluation |
| * of <em>lambda expressions</em> and <em>method references</em> in the Java |
| * Language. For every lambda expressions or method reference in the source code, |
| * there is a target type which is a functional interface. Evaluating a lambda |
| * expression produces an object of its target type. The recommended mechanism |
| * for evaluating lambda expressions is to desugar the lambda body to a method, |
| * invoke an invokedynamic call site whose static argument list describes the |
| * sole method of the functional interface and the desugared implementation |
| * method, and returns an object (the lambda object) that implements the target |
| * type. (For method references, the implementation method is simply the |
| * referenced method; no desugaring is needed.) |
| * |
| * <p>The argument list of the implementation method and the argument list of |
| * the interface method(s) may differ in several ways. The implementation |
| * methods may have additional arguments to accommodate arguments captured by |
| * the lambda expression; there may also be differences resulting from permitted |
| * adaptations of arguments, such as casting, boxing, unboxing, and primitive |
| * widening. (Varargs adaptations are not handled by the metafactories; these are |
| * expected to be handled by the caller.) |
| * |
| * <p>Invokedynamic call sites have two argument lists: a static argument list |
| * and a dynamic argument list. The static argument list is stored in the |
| * constant pool; the dynamic argument is pushed on the operand stack at capture |
| * time. The bootstrap method has access to the entire static argument list |
| * (which in this case, includes information describing the implementation method, |
| * the target interface, and the target interface method(s)), as well as a |
| * method signature describing the number and static types (but not the values) |
| * of the dynamic arguments and the static return type of the invokedynamic site. |
| * |
| * @implNote The implementation method is described with a method handle. In |
| * theory, any method handle could be used. Currently supported are direct method |
| * handles representing invocation of virtual, interface, constructor and static |
| * methods. |
| * @since 1.8 |
| */ |
| public final class LambdaMetafactory { |
| |
| private LambdaMetafactory() {} |
| |
| /** Flag for alternate metafactories indicating the lambda object |
| * must be serializable */ |
| public static final int FLAG_SERIALIZABLE = 1 << 0; |
| |
| /** |
| * Flag for alternate metafactories indicating the lambda object implements |
| * other marker interfaces |
| * besides Serializable |
| */ |
| public static final int FLAG_MARKERS = 1 << 1; |
| |
| /** |
| * Flag for alternate metafactories indicating the lambda object requires |
| * additional bridge methods |
| */ |
| public static final int FLAG_BRIDGES = 1 << 2; |
| |
| private static final Class<?>[] EMPTY_CLASS_ARRAY = new Class<?>[0]; |
| private static final MethodType[] EMPTY_MT_ARRAY = new MethodType[0]; |
| |
| // LambdaMetafactory bootstrap methods are startup sensitive, and may be |
| // special cased in java.lang.invokeBootstrapMethodInvoker to ensure |
| // methods are invoked with exact type information to avoid generating |
| // code for runtime checks. Take care any changes or additions here are |
| // reflected there as appropriate. |
| |
| /** |
| * Facilitates the creation of simple "function objects" that implement one |
| * or more interfaces by delegation to a provided {@link MethodHandle}, |
| * after appropriate type adaptation and partial evaluation of arguments. |
| * Typically used as a <em>bootstrap method</em> for {@code invokedynamic} |
| * call sites, to support the <em>lambda expression</em> and <em>method |
| * reference expression</em> features of the Java Programming Language. |
| * |
| * <p>This is the standard, streamlined metafactory; additional flexibility |
| * is provided by {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}. |
| * A general description of the behavior of this method is provided |
| * {@link LambdaMetafactory above}. |
| * |
| * <p>When the target of the {@code CallSite} returned from this method is |
| * invoked, the resulting function objects are instances of a class which |
| * implements the interface named by the return type of {@code invokedType}, |
| * declares a method with the name given by {@code invokedName} and the |
| * signature given by {@code samMethodType}. It may also override additional |
| * methods from {@code Object}. |
| * |
| * @param caller Represents a lookup context with the accessibility |
| * privileges of the caller. Specifically, the lookup context |
| * must have |
| * <a href="MethodHandles.Lookup.html#privacc">private access</a> |
| * privileges. |
| * When used with {@code invokedynamic}, this is stacked |
| * automatically by the VM. |
| * @param invokedName The name of the method to implement. When used with |
| * {@code invokedynamic}, this is provided by the |
| * {@code NameAndType} of the {@code InvokeDynamic} |
| * structure and is stacked automatically by the VM. |
| * @param invokedType The expected signature of the {@code CallSite}. The |
| * parameter types represent the types of capture variables; |
| * the return type is the interface to implement. When |
| * used with {@code invokedynamic}, this is provided by |
| * the {@code NameAndType} of the {@code InvokeDynamic} |
| * structure and is stacked automatically by the VM. |
| * In the event that the implementation method is an |
| * instance method and this signature has any parameters, |
| * the first parameter in the invocation signature must |
| * correspond to the receiver. |
| * @param samMethodType Signature and return type of method to be implemented |
| * by the function object. |
| * @param implMethod A direct method handle describing the implementation |
| * method which should be called (with suitable adaptation |
| * of argument types, return types, and with captured |
| * arguments prepended to the invocation arguments) at |
| * invocation time. |
| * @param instantiatedMethodType The signature and return type that should |
| * be enforced dynamically at invocation time. |
| * This may be the same as {@code samMethodType}, |
| * or may be a specialization of it. |
| * @return a CallSite whose target can be used to perform capture, generating |
| * instances of the interface named by {@code invokedType} |
| * @throws LambdaConversionException If any of the linkage invariants |
| * described {@link LambdaMetafactory above} |
| * are violated, or the lookup context |
| * does not have private access privileges. |
| */ |
| public static CallSite metafactory(MethodHandles.Lookup caller, |
| String invokedName, |
| MethodType invokedType, |
| MethodType samMethodType, |
| MethodHandle implMethod, |
| MethodType instantiatedMethodType) |
| throws LambdaConversionException { |
| AbstractValidatingLambdaMetafactory mf; |
| mf = new InnerClassLambdaMetafactory(caller, invokedType, |
| invokedName, samMethodType, |
| implMethod, instantiatedMethodType, |
| false, EMPTY_CLASS_ARRAY, EMPTY_MT_ARRAY); |
| mf.validateMetafactoryArgs(); |
| return mf.buildCallSite(); |
| } |
| |
| /** |
| * Facilitates the creation of simple "function objects" that implement one |
| * or more interfaces by delegation to a provided {@link MethodHandle}, |
| * after appropriate type adaptation and partial evaluation of arguments. |
| * Typically used as a <em>bootstrap method</em> for {@code invokedynamic} |
| * call sites, to support the <em>lambda expression</em> and <em>method |
| * reference expression</em> features of the Java Programming Language. |
| * |
| * <p>This is the general, more flexible metafactory; a streamlined version |
| * is provided by {@link #metafactory(java.lang.invoke.MethodHandles.Lookup, |
| * String, MethodType, MethodType, MethodHandle, MethodType)}. |
| * A general description of the behavior of this method is provided |
| * {@link LambdaMetafactory above}. |
| * |
| * <p>The argument list for this method includes three fixed parameters, |
| * corresponding to the parameters automatically stacked by the VM for the |
| * bootstrap method in an {@code invokedynamic} invocation, and an {@code Object[]} |
| * parameter that contains additional parameters. The declared argument |
| * list for this method is: |
| * |
| * <pre>{@code |
| * CallSite altMetafactory(MethodHandles.Lookup caller, |
| * String invokedName, |
| * MethodType invokedType, |
| * Object... args) |
| * }</pre> |
| * |
| * <p>but it behaves as if the argument list is as follows: |
| * |
| * <pre>{@code |
| * CallSite altMetafactory(MethodHandles.Lookup caller, |
| * String invokedName, |
| * MethodType invokedType, |
| * MethodType samMethodType, |
| * MethodHandle implMethod, |
| * MethodType instantiatedMethodType, |
| * int flags, |
| * int markerInterfaceCount, // IF flags has MARKERS set |
| * Class... markerInterfaces, // IF flags has MARKERS set |
| * int bridgeCount, // IF flags has BRIDGES set |
| * MethodType... bridges // IF flags has BRIDGES set |
| * ) |
| * }</pre> |
| * |
| * <p>Arguments that appear in the argument list for |
| * {@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)} |
| * have the same specification as in that method. The additional arguments |
| * are interpreted as follows: |
| * <ul> |
| * <li>{@code flags} indicates additional options; this is a bitwise |
| * OR of desired flags. Defined flags are {@link #FLAG_BRIDGES}, |
| * {@link #FLAG_MARKERS}, and {@link #FLAG_SERIALIZABLE}.</li> |
| * <li>{@code markerInterfaceCount} is the number of additional interfaces |
| * the function object should implement, and is present if and only if the |
| * {@code FLAG_MARKERS} flag is set.</li> |
| * <li>{@code markerInterfaces} is a variable-length list of additional |
| * interfaces to implement, whose length equals {@code markerInterfaceCount}, |
| * and is present if and only if the {@code FLAG_MARKERS} flag is set.</li> |
| * <li>{@code bridgeCount} is the number of additional method signatures |
| * the function object should implement, and is present if and only if |
| * the {@code FLAG_BRIDGES} flag is set.</li> |
| * <li>{@code bridges} is a variable-length list of additional |
| * methods signatures to implement, whose length equals {@code bridgeCount}, |
| * and is present if and only if the {@code FLAG_BRIDGES} flag is set.</li> |
| * </ul> |
| * |
| * <p>Each class named by {@code markerInterfaces} is subject to the same |
| * restrictions as {@code Rd}, the return type of {@code invokedType}, |
| * as described {@link LambdaMetafactory above}. Each {@code MethodType} |
| * named by {@code bridges} is subject to the same restrictions as |
| * {@code samMethodType}, as described {@link LambdaMetafactory above}. |
| * |
| * <p>When FLAG_SERIALIZABLE is set in {@code flags}, the function objects |
| * will implement {@code Serializable}, and will have a {@code writeReplace} |
| * method that returns an appropriate {@link SerializedLambda}. The |
| * {@code caller} class must have an appropriate {@code $deserializeLambda$} |
| * method, as described in {@link SerializedLambda}. |
| * |
| * <p>When the target of the {@code CallSite} returned from this method is |
| * invoked, the resulting function objects are instances of a class with |
| * the following properties: |
| * <ul> |
| * <li>The class implements the interface named by the return type |
| * of {@code invokedType} and any interfaces named by {@code markerInterfaces}</li> |
| * <li>The class declares methods with the name given by {@code invokedName}, |
| * and the signature given by {@code samMethodType} and additional signatures |
| * given by {@code bridges}</li> |
| * <li>The class may override methods from {@code Object}, and may |
| * implement methods related to serialization.</li> |
| * </ul> |
| * |
| * @param caller Represents a lookup context with the accessibility |
| * privileges of the caller. Specifically, the lookup context |
| * must have |
| * <a href="MethodHandles.Lookup.html#privacc">private access</a> |
| * privileges. |
| * When used with {@code invokedynamic}, this is stacked |
| * automatically by the VM. |
| * @param invokedName The name of the method to implement. When used with |
| * {@code invokedynamic}, this is provided by the |
| * {@code NameAndType} of the {@code InvokeDynamic} |
| * structure and is stacked automatically by the VM. |
| * @param invokedType The expected signature of the {@code CallSite}. The |
| * parameter types represent the types of capture variables; |
| * the return type is the interface to implement. When |
| * used with {@code invokedynamic}, this is provided by |
| * the {@code NameAndType} of the {@code InvokeDynamic} |
| * structure and is stacked automatically by the VM. |
| * In the event that the implementation method is an |
| * instance method and this signature has any parameters, |
| * the first parameter in the invocation signature must |
| * correspond to the receiver. |
| * @param args An {@code Object[]} array containing the required |
| * arguments {@code samMethodType}, {@code implMethod}, |
| * {@code instantiatedMethodType}, {@code flags}, and any |
| * optional arguments, as described |
| * {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)} above} |
| * @return a CallSite whose target can be used to perform capture, generating |
| * instances of the interface named by {@code invokedType} |
| * @throws LambdaConversionException If any of the linkage invariants |
| * described {@link LambdaMetafactory above} |
| * are violated, or the lookup context |
| * does not have private access privileges. |
| */ |
| public static CallSite altMetafactory(MethodHandles.Lookup caller, |
| String invokedName, |
| MethodType invokedType, |
| Object... args) |
| throws LambdaConversionException { |
| MethodType samMethodType = (MethodType)args[0]; |
| MethodHandle implMethod = (MethodHandle)args[1]; |
| MethodType instantiatedMethodType = (MethodType)args[2]; |
| int flags = (Integer) args[3]; |
| Class<?>[] markerInterfaces; |
| MethodType[] bridges; |
| int argIndex = 4; |
| if ((flags & FLAG_MARKERS) != 0) { |
| int markerCount = (Integer) args[argIndex++]; |
| markerInterfaces = new Class<?>[markerCount]; |
| System.arraycopy(args, argIndex, markerInterfaces, 0, markerCount); |
| argIndex += markerCount; |
| } |
| else |
| markerInterfaces = EMPTY_CLASS_ARRAY; |
| if ((flags & FLAG_BRIDGES) != 0) { |
| int bridgeCount = (Integer) args[argIndex++]; |
| bridges = new MethodType[bridgeCount]; |
| System.arraycopy(args, argIndex, bridges, 0, bridgeCount); |
| argIndex += bridgeCount; |
| } |
| else |
| bridges = EMPTY_MT_ARRAY; |
| |
| boolean isSerializable = ((flags & FLAG_SERIALIZABLE) != 0); |
| if (isSerializable) { |
| boolean foundSerializableSupertype = Serializable.class.isAssignableFrom(invokedType.returnType()); |
| for (Class<?> c : markerInterfaces) |
| foundSerializableSupertype |= Serializable.class.isAssignableFrom(c); |
| if (!foundSerializableSupertype) { |
| markerInterfaces = Arrays.copyOf(markerInterfaces, markerInterfaces.length + 1); |
| markerInterfaces[markerInterfaces.length-1] = Serializable.class; |
| } |
| } |
| |
| AbstractValidatingLambdaMetafactory mf |
| = new InnerClassLambdaMetafactory(caller, invokedType, |
| invokedName, samMethodType, |
| implMethod, |
| instantiatedMethodType, |
| isSerializable, |
| markerInterfaces, bridges); |
| mf.validateMetafactoryArgs(); |
| return mf.buildCallSite(); |
| } |
| } |
