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 /**
  29  * <p>Bootstrap methods for converting lambda expressions and method references to functional interface objects.</p>
  30  *
  31  * <p>For every lambda expressions or method reference in the source code, there is a target type which is a
  32  * functional interface. Evaluating a lambda expression produces an object of its target type. The mechanism for
  33  * evaluating lambda expressions is to invoke an invokedynamic call site, which takes arguments describing the sole
  34  * method of the functional interface and the implementation method, and returns an object (the lambda object) that
  35  * implements the target type. Methods of the lambda object invoke the implementation method. For method
  36  * references, the implementation method is simply the referenced method; for lambda expressions, the
  37  * implementation method is produced by the compiler based on the body of the lambda expression. The methods in
  38  * this file are the bootstrap methods for those invokedynamic call sites, called lambda factories, and the
  39  * bootstrap methods responsible for linking the lambda factories are called lambda meta-factories.
  40  *
  41  * <p>The bootstrap methods in this class take the information about the functional interface, the implementation
  42  * method, and the static types of the captured lambda arguments, and link a call site which, when invoked,
  43  * produces the lambda object.
  44  *
  45  * <p>When parameterized types are used, the instantiated type of the functional interface method may be different
  46  * from that in the functional interface. For example, consider
  47  * <code>interface I&lt;T&gt; { int m(T x); }</code> if this functional interface type is used in a lambda
  48  * <code>I&lt;Byte&gt; v = ...</code>, we need both the actual functional interface method which has the signature
  49  * <code>(Object)int</code> and the erased instantiated type of the functional interface method (or simply
  50  * <I>instantiated method type</I>), which has signature
  51  * <code>(Byte)int</code>.
  52  *
  53  * <p>While functional interfaces only have a single abstract method from the language perspective (concrete
  54  * methods in Object are and default methods may be present), at the bytecode level they may actually have multiple
  55  * methods because of the need for bridge methods. Invoking any of these methods on the lambda object will result
  56  * in invoking the implementation method.
  57  *
  58  * <p>The argument list of the implementation method and the argument list of the functional interface method(s)
  59  * may differ in several ways.  The implementation methods may have additional arguments to accommodate arguments
  60  * captured by the lambda expression; there may also be differences resulting from permitted adaptations of
  61  * arguments, such as casting, boxing, unboxing, and primitive widening. They may also differ because of var-args,
  62  * but this is expected to be handled by the compiler.
  63  *
  64  * <p>Invokedynamic call sites have two argument lists: a static argument list and a dynamic argument list.  The
  65  * static argument list lives in the constant pool; the dynamic argument list lives on the operand stack at
  66  * invocation time.  The bootstrap method has access to the entire static argument list (which in this case,
  67  * contains method handles describing the implementation method and the canonical functional interface method),
  68  * as well as a method signature describing the number and static types (but not the values) of the dynamic
  69  * arguments, and the static return type of the invokedynamic site.
  70  *
  71  * <p>The implementation method is described with a method handle. In theory, any method handle could be used.
  72  * Currently supported are method handles representing invocation of virtual, interface, constructor and static
  73  * methods.
  74  *
  75  * <p>Assume:
  76  * <ul>
  77  *      <li>the functional interface method has N arguments, of types (U1, U2, ... Un) and return type Ru</li>
  78  *      <li>then the instantiated method type also has N arguments, of types (T1, T2, ... Tn) and return type Rt</li>
  79  *      <li>the implementation method has M arguments, of types (A1..Am) and return type Ra,</li>
  80  *      <li>the dynamic argument list has K arguments of types (D1..Dk), and the invokedynamic return site has
  81  *          type Rd</li>
  82  *      <li>the functional interface type is F</li>
  83  * </ul>
  84  *
  85  * <p>The following signature invariants must hold:
  86  * <ul>
  87  *     <li>Rd is a subtype of F</li>
  88  *     <li>For i=1..N, Ti is a subtype of Ui</li>
  89  *     <li>Either Rt and Ru are primitive and are the same type, or both are reference types and
  90  *         Rt is a subtype of Ru</li>
  91  *     <li>If the implementation method is a static method:
  92  *     <ul>
  93  *         <li>K + N = M</li>
  94  *         <li>For i=1..K, Di = Ai</li>
  95  *         <li>For i=1..N, Ti is adaptable to Aj, where j=i+k</li>
  96  *     </ul></li>
  97  *     <li>If the implementation method is an instance method:
  98  *     <ul>
  99  *         <li>K + N = M + 1</li>
 100  *         <li>D1 must be a subtype of the enclosing class for the implementation method</li>
 101  *         <li>For i=2..K, Di = Aj, where j=i-1</li>
 102  *         <li>For i=1..N, Ti is adaptable to Aj, where j=i+k-1</li>
 103  *     </ul></li>
 104  *     <li>The return type Rt is void, or the return type Ra is not void and is adaptable to Rt</li>
 105  * </ul>
 106  *
 107  * <p>Note that the potentially parameterized implementation return type provides the value for the SAM. Whereas
 108  * the completely known instantiated return type is adapted to the implementation arguments. Because the
 109  * instantiated type of the implementation method is not available, the adaptability of return types cannot be
 110  * checked as precisely at link-time as the arguments can be checked. Thus a loose version of link-time checking is
 111  * done on return type, while a strict version is applied to arguments.
 112  *
 113  * <p>A type Q is considered adaptable to S as follows:
 114  * <table>
 115  *     <tr><th>Q</th><th>S</th><th>Link-time checks</th><th>Capture-time checks</th></tr>
 116  *     <tr>
 117  *         <td>Primitive</td><td>Primitive</td>
 118  *         <td>Q can be converted to S via a primitive widening conversion</td>
 119  *         <td>None</td>
 120  *     </tr>
 121  *     <tr>
 122  *         <td>Primitive</td><td>Reference</td>
 123  *         <td>S is a supertype of the Wrapper(Q)</td>
 124  *         <td>Cast from Wrapper(Q) to S</td>
 125  *     </tr>
 126  *     <tr>
 127  *         <td>Reference</td><td>Primitive</td>
 128  *         <td>strict: Q is a primitive wrapper and Primitive(Q) can be widened to S
 129  *         <br>loose: If Q is a primitive wrapper, check that Primitive(Q) can be widened to S</td>
 130  *         <td>If Q is not a primitive wrapper, cast Q to the base Wrapper(S); for example Number for numeric types</td>
 131  *     </tr>
 132  *     <tr>
 133  *         <td>Reference</td><td>Reference</td>
 134  *         <td>strict: S is a supertype of Q
 135  *         <br>loose: none</td>
 136  *         <td>Cast from Q to S</td>
 137  *     </tr>
 138  * </table>
 139  *
 140  * The default bootstrap ({@link #metaFactory}) represents the common cases and uses an optimized protocol.
 141  * Alternate bootstraps (e.g., {@link #altMetaFactory}) exist to support uncommon cases such as serialization
 142  * or additional marker superinterfaces.
 143  *
 144  */
 145 public class LambdaMetafactory {
 146 
 147     /** Flag for alternate metafactories indicating the lambda object is must to be serializable */
 148     public static final int FLAG_SERIALIZABLE = 1 << 0;
 149 
 150     /**
 151      * Flag for alternate metafactories indicating the lambda object implements other marker interfaces
 152      * besides Serializable
 153      */
 154     public static final int FLAG_MARKERS = 1 << 1;
 155 
 156     private static final Class<?>[] EMPTY_CLASS_ARRAY = new Class<?>[0];
 157 
 158 /**
 159      * Standard meta-factory for conversion of lambda expressions or method references to functional interfaces.
 160      *
 161      * @param caller Stacked automatically by VM; represents a lookup context with the accessibility privileges
 162      *               of the caller.
 163      * @param invokedName Stacked automatically by VM; the name of the invoked method as it appears at the call site.
 164      *                    Currently unused.
 165      * @param invokedType Stacked automatically by VM; the signature of the invoked method, which includes the
 166      *                    expected static type of the returned lambda object, and the static types of the captured
 167      *                    arguments for the lambda.  In the event that the implementation method is an instance method,
 168      *                    the first argument in the invocation signature will correspond to the receiver.
 169      * @param samMethod The primary method in the functional interface to which the lambda or method reference is
 170      *                  being converted, represented as a method handle.
 171      * @param implMethod The implementation method which should be called (with suitable adaptation of argument
 172      *                   types, return types, and adjustment for captured arguments) when methods of the resulting
 173      *                   functional interface instance are invoked.
 174      * @param instantiatedMethodType The signature of the primary functional interface method after type variables
 175      *                               are substituted with their instantiation from the capture site
 176      * @return a CallSite, which, when invoked, will return an instance of the functional interface
 177      * @throws ReflectiveOperationException
 178      * @throws LambdaConversionException If any of the meta-factory protocol invariants are violated
 179      */
 180     public static CallSite metaFactory(MethodHandles.Lookup caller,
 181                                        String invokedName,
 182                                        MethodType invokedType,
 183                                        MethodHandle samMethod,
 184                                        MethodHandle implMethod,
 185                                        MethodType instantiatedMethodType)
 186                    throws ReflectiveOperationException, LambdaConversionException {
 187         AbstractValidatingLambdaMetafactory mf;
 188         mf = new InnerClassLambdaMetafactory(caller, invokedType, samMethod, implMethod, instantiatedMethodType,
 189                 0, EMPTY_CLASS_ARRAY);
 190         mf.validateMetafactoryArgs();
 191         return mf.buildCallSite();
 192     }
 193 
 194     /**
 195      * Alternate meta-factory for conversion of lambda expressions or method references to functional interfaces,
 196      * which supports serialization and other uncommon options.
 197      *
 198      * The declared argument list for this method is:
 199      *
 200      *  CallSite altMetaFactory(MethodHandles.Lookup caller,
 201      *                          String invokedName,
 202      *                          MethodType invokedType,
 203      *                          Object... args)
 204      *
 205      * but it behaves as if the argument list is:
 206      *
 207      *  CallSite altMetaFactory(MethodHandles.Lookup caller,
 208      *                          String invokedName,
 209      *                          MethodType invokedType,
 210      *                          MethodHandle samMethod
 211      *                          MethodHandle implMethod,
 212      *                          MethodType instantiatedMethodType,
 213      *                          int flags,
 214      *                          int markerInterfaceCount, // IF flags has MARKERS set
 215      *                          Class... markerInterfaces // IF flags has MARKERS set
 216      *                          )
 217      *
 218      *
 219      * @param caller Stacked automatically by VM; represents a lookup context with the accessibility privileges
 220      *               of the caller.
 221      * @param invokedName Stacked automatically by VM; the name of the invoked method as it appears at the call site.
 222      *                    Currently unused.
 223      * @param invokedType Stacked automatically by VM; the signature of the invoked method, which includes thefu
 224      *                    expected static type of the returned lambda object, and the static types of the captured
 225      *                    arguments for the lambda.  In the event that the implementation method is an instance method,
 226      *                    the first argument in the invocation signature will correspond to the receiver.
 227      * @param  args       argument to pass, flags, marker interface count, and marker interfaces as described above
 228      * @return a CallSite, which, when invoked, will return an instance of the functional interface
 229      * @throws ReflectiveOperationException
 230      * @throws LambdaConversionException If any of the meta-factory protocol invariants are violated
 231      */
 232     public static CallSite altMetaFactory(MethodHandles.Lookup caller,
 233                                           String invokedName,
 234                                           MethodType invokedType,
 235                                           Object... args)
 236             throws ReflectiveOperationException, LambdaConversionException {
 237         MethodHandle samMethod = (MethodHandle)args[0];
 238         MethodHandle implMethod = (MethodHandle)args[1];
 239         MethodType instantiatedMethodType = (MethodType)args[2];
 240         int flags = (Integer) args[3];
 241         Class<?>[] markerInterfaces;
 242         int argIndex = 4;
 243         if ((flags & FLAG_MARKERS) != 0) {
 244             int markerCount = (Integer) args[argIndex++];
 245             markerInterfaces = new Class<?>[markerCount];
 246             System.arraycopy(args, argIndex, markerInterfaces, 0, markerCount);
 247             argIndex += markerCount;
 248         }
 249         else
 250             markerInterfaces = EMPTY_CLASS_ARRAY;
 251         AbstractValidatingLambdaMetafactory mf;
 252         mf = new InnerClassLambdaMetafactory(caller, invokedType, samMethod, implMethod, instantiatedMethodType,
 253                                              flags, markerInterfaces);
 254         mf.validateMetafactoryArgs();
 255         return mf.buildCallSite();
 256     }
 257 }