Bootstrap methods for converting lambda expressions and method references to functional interface objects.
- * - *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 mechanism for - * evaluating lambda expressions is to invoke an invokedynamic call site, which takes arguments describing the sole - * method of the functional interface and the implementation method, and returns an object (the lambda object) that - * implements the target type. Methods of the lambda object invoke the implementation method. For method - * references, the implementation method is simply the referenced method; for lambda expressions, the - * implementation method is produced by the compiler based on the body of the lambda expression. The methods in - * this file are the bootstrap methods for those invokedynamic call sites, called lambda factories, and the - * bootstrap methods responsible for linking the lambda factories are called lambda meta-factories. - * - *
The bootstrap methods in this class take the information about the functional interface, the implementation - * method, and the static types of the captured lambda arguments, and link a call site which, when invoked, - * produces the lambda object. - * - *
When parameterized types are used, the instantiated type of the functional interface method may be different
- * from that in the functional interface. For example, consider
- * {@code interface I 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 bootstrap methods for {@code invokedynamic}
+ * call sites, to support the lambda expression and method
+ * reference expression features of the Java Programming Language.
*
- * The argument list of the implementation method and the argument list of the functional 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. They may also differ because of var-args,
- * but this is expected to be handled by the compiler.
- *
- * Invokedynamic call sites have two argument lists: a static argument list and a dynamic argument list. The
- * static argument list lives in the constant pool; the dynamic argument list lives on the operand stack at
- * invocation time. The bootstrap method has access to the entire static argument list (which in this case,
- * contains method handles describing the implementation method and the canonical functional interface method),
- * 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.
+ * Indirect access to the behavior specified by the provided {@code MethodHandle}
+ * proceeds in order through three phases:
+ * The implementation method is described with a method handle. In theory, any method handle could be used.
- * Currently supported are method handles representing invocation of virtual, interface, constructor and static
- * methods.
+ * Assume:
- * The following signature invariants must hold:
+ * It is sometimes useful to restrict the set of inputs or results permitted
+ * at invocation. For example, when the generic interface {@code Predicate 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:
+ *
* Note that the potentially parameterized implementation return type provides the value for the SAM. Whereas
- * the completely known instantiated return type is adapted to the implementation arguments. Because the
- * instantiated type of the implementation method is not available, the adaptability of return types cannot be
- * checked as precisely at link-time as the arguments can be checked. Thus a loose version of link-time checking is
- * done on return type, while a strict version is applied to arguments.
+ * Assume the linkage arguments are as follows:
+ * Then the following linkage invariants must hold:
+ * 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.
*
* A type Q is considered adaptable to S as follows:
* 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.)
+ *
+ * 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.
*/
public class LambdaMetafactory {
- /** Flag for alternate metafactories indicating the lambda object is
- * must to be serializable */
+ /** Flag for alternate metafactories indicating the lambda object
+ * must be serializable */
public static final int FLAG_SERIALIZABLE = 1 << 0;
/**
@@ -163,41 +235,58 @@
private static final MethodType[] EMPTY_MT_ARRAY = new MethodType[0];
/**
- * Standard meta-factory for conversion of lambda expressions or method
- * references to functional interfaces.
+ * 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 bootstrap method for {@code invokedynamic}
+ * call sites, to support the lambda expression and method
+ * reference expression features of the Java Programming Language.
+ *
+ * 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}.
+ *
+ * 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 Stacked automatically by VM; represents a lookup context
- * with the accessibility privileges of the caller.
- * @param invokedName Stacked automatically by VM; the name of the invoked
- * method as it appears at the call site.
- * Used as the name of the functional interface method
- * to which the lambda or method reference is being
- * converted.
- * @param invokedType Stacked automatically by VM; the signature of the
- * invoked method, which includes the expected static
- * type of the returned lambda object, and the static
- * types of the captured arguments for the lambda.
+ * @param caller Represents a lookup context with the accessibility
+ * privileges of the caller. 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, the first argument in the invocation
- * signature will correspond to the receiver.
- * @param samMethodType MethodType of the method in the functional interface
- * to which the lambda or method reference is being
- * converted, represented as a MethodType.
+ * 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 adjustment for
- * captured arguments) when methods of the resulting
- * functional interface instance are invoked.
- * @param instantiatedMethodType The signature of the primary functional
- * interface method after type variables
- * are substituted with their instantiation
- * from the capture site.
- * @return a CallSite, which, when invoked, will return an instance of the
- * functional interface
- * @throws ReflectiveOperationException if the caller is not able to
- * reconstruct one of the method handles
- * @throws LambdaConversionException If any of the meta-factory protocol
- * invariants are violated
+ * 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
*/
public static CallSite metafactory(MethodHandles.Lookup caller,
String invokedName,
@@ -205,7 +294,7 @@
MethodType samMethodType,
MethodHandle implMethod,
MethodType instantiatedMethodType)
- throws ReflectiveOperationException, LambdaConversionException {
+ throws LambdaConversionException {
AbstractValidatingLambdaMetafactory mf;
mf = new InnerClassLambdaMetafactory(caller, invokedType,
invokedName, samMethodType,
@@ -216,11 +305,23 @@
}
/**
- * Alternate meta-factory for conversion of lambda expressions or method
- * references to functional interfaces, which supports serialization and
- * other uncommon options.
+ * 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 bootstrap method for {@code invokedynamic}
+ * call sites, to support the lambda expression and method
+ * reference expression features of the Java Programming Language.
*
- * The declared argument list for this method is:
+ * This is the general, more flexible metafactory; a streamlined version
+ * is provided by {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}.
+ * A general description of the behavior of this method is provided
+ * {@link LambdaMetafactory above}.
+ *
+ * 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:
*
* but it behaves as if the argument list is as follows, where names that
- * appear in the argument list for
- * {@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)}
- * have the same specification as in that method:
+ * but it behaves as if the argument list is as follows:
*
* If the flags contains {@code FLAG_SERIALIZABLE}, or one of the marker
- * interfaces extends {@link Serializable}, the metafactory will link the
- * call site to one that produces a serializable lambda. In addition to
- * the lambda instance implementing {@code Serializable}, it will have a
- * {@code writeReplace} method that returns an appropriate {@link
- * SerializedLambda}, and an appropriate {@code $deserializeLambda$}
- * method.
+ * 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:
+ * 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}.
+ *
+ * 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}.
*
- * @param caller Stacked automatically by VM; represents a lookup context
- * with the accessibility privileges of the caller.
- * @param invokedName Stacked automatically by VM; the name of the invoked
- * method as it appears at the call site.
- * Used as the name of the functional interface method
- * to which the lambda or method reference is being
- * converted.
- * @param invokedType Stacked automatically by VM; the signature of the
- * invoked method, which includes the expected static
- * type of the returned lambda object, and the static
- * types of the captured arguments for the lambda.
+ * 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:
+ *
+ *
- *
*
- *
- *
*
- *
- *
- *
+ *
+ *
+ *
+ *
+ *
+ *
- *
*
- * The default bootstrap ({@link #metafactory}) represents the common cases and uses an optimized protocol.
- * Alternate bootstraps (e.g., {@link #altMetafactory}) exist to support uncommon cases such as serialization
- * or additional marker superinterfaces.
+ * @apiNote These linkage methods are designed to support the evaluation
+ * of lambda expressions and method references 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.)
*
+ * Q S Link-time checks Capture-time checks Q S Link-time checks Invocation-time checks
*
* Primitive Primitive
* Q can be converted to S via a primitive widening conversion
@@ -123,27 +163,59 @@
*
*
* Reference Primitive
- * strict: Q is a primitive wrapper and Primitive(Q) can be widened to S
- *
- *
loose: If Q is a primitive wrapper, check that Primitive(Q) can be widened to SIf Q is not a primitive wrapper, cast Q to the base Wrapper(S); for example Number for numeric types
+ * for parameter types: Q is a primitive wrapper and Primitive(Q)
+ * can be widened to S
+ *
+ *
for return types: If Q is a primitive wrapper, check that
+ * Primitive(Q) can be widened to SIf Q is not a primitive wrapper, cast Q to the base Wrapper(S);
+ * for example Number for numeric types
*
*
* Reference Reference
- * strict: S is a supertype of Q
- *
+ *
loose: nonefor parameter types: S is a supertype of Q
+ *
*
for return types: noneCast from Q to S
* {@code
* CallSite altMetafactory(MethodHandles.Lookup caller,
@@ -229,61 +330,103 @@
* Object... args)
* }
*
- * {@code
* CallSite altMetafactory(MethodHandles.Lookup caller,
* String invokedName,
* MethodType invokedType,
- * MethodType samMethodType
+ * 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
+ * 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
* )
* }
*
- *
+ *
+ *
+ *
+ *
+ *
+ * @param caller Represents a lookup context with the accessibility
+ * privileges of the caller. 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, the first argument in the invocation
- * signature will correspond to the receiver.
- * @param args flags and optional arguments, as described above.
- * @return a CallSite, which, when invoked, will return an instance of the
- * functional interface
- * @throws ReflectiveOperationException if the caller is not able to
- * reconstruct one of the method handles
- * @throws LambdaConversionException If any of the meta-factory protocol
- * invariants are violated
+ * 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
*/
public static CallSite altMetafactory(MethodHandles.Lookup caller,
String invokedName,
MethodType invokedType,
Object... args)
- throws ReflectiveOperationException, LambdaConversionException {
+ throws LambdaConversionException {
MethodType samMethodType = (MethodType)args[0];
MethodHandle implMethod = (MethodHandle)args[1];
MethodType instantiatedMethodType = (MethodType)args[2];
@@ -308,15 +451,15 @@
else
bridges = EMPTY_MT_ARRAY;
- boolean foundSerializableSupertype = Serializable.class.isAssignableFrom(invokedType.returnType());
- for (Class c : markerInterfaces)
- foundSerializableSupertype |= Serializable.class.isAssignableFrom(c);
- boolean isSerializable = ((flags & LambdaMetafactory.FLAG_SERIALIZABLE) != 0)
- || foundSerializableSupertype;
-
- if (isSerializable && !foundSerializableSupertype) {
- markerInterfaces = Arrays.copyOf(markerInterfaces, markerInterfaces.length + 1);
- markerInterfaces[markerInterfaces.length-1] = Serializable.class;
+ 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