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