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. * *
Indirect access to the behavior specified by the provided {@code MethodHandle} * proceeds in order through three phases: *
Linkage occurs when the methods in this class are invoked. * They take as arguments an interface to be implemented (typically a * functional interface, one with a single abstract method), a * name and signature of a method from that interface to be implemented, a * {@linkplain MethodHandleInfo direct 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, or re-using a suitable existing class. * *
The {@code CallSite} can be considered a "factory" for function * objects and so these linkage methods are referred to as * "metafactories".
Capture 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}. * *
If the behavior {@code MethodHandle} has additional parameters beyond * those of the specified interface method, these are referred to as * captured parameters, which must be provided as arguments to the * {@code CallSite} target. The expected number and types of captured * parameters are determined during linkage. * *
Capture may involve allocation of a new function object, or may return * a suitable existing function object. The identity of a function object * produced by capture 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.
Invocation 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 implementation * {@code MethodHandle} is invoked, passing to it the captured arguments and * the invocation arguments. The result of the method is returned. *
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:
*
* Assume the linkage arguments are as follows:
* Then the following linkage invariants must hold:
* Further, at capture time, if {@code implementation} 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.
*
* The implementation method is described with a direct method handle
* referencing a method or constructor. In theory, any method handle could be
* used, but this is not compatible with some implementation techniques and
* would complicate the work implementations must do.
*
* Uses besides evaluation of lambda expressions and method references are
* unintended. These linkage methods may change their unspecified behaviors at
* any time to better suit the Java language features they were designed to
* support, and such changes may impact unintended uses. Unintended uses of
* these linkage methods may lead to resource leaks, or other unspecified
* negative effects.
*
* @implNote In the reference implementation, the classes implementing the created
* function objects are strongly reachable from the defining class loader of the
* caller, like classes and interfaces in Java source code. This technique
* reduces heap memory use, but as a consequence, the implementation classes can
* be unloaded only if the caller class can be unloaded. In particular, if the
* caller is a {@linkplain MethodHandles.Lookup.ClassOption#STRONG weak hidden
* class}, the implementation class, a strong hidden class, may not be unloaded
* even if the caller may be unloaded.
*
* @since 1.8
*/
public final class LambdaMetafactory {
private LambdaMetafactory() {}
/** Flag for {@link #altMetafactory} indicating the lambda object
* must be serializable */
public static final int FLAG_SERIALIZABLE = 1 << 0;
/**
* Flag for {@link #altMetafactory} indicating the lambda object implements
* other interfaces besides {@code Serializable}
*/
public static final int FLAG_MARKERS = 1 << 1;
/**
* Flag for alternate metafactories indicating the lambda object requires
* additional methods that invoke the {@code implementation}
*/
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.invoke.BootstrapMethodInvoker 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 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 factoryType},
* declares a method with the name given by {@code interfaceMethodName} and the
* signature given by {@code interfaceMethodType}. 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 {@linkplain MethodHandles.Lookup#hasFullPrivilegeAccess()
* full privilege access}.
* When used with {@code invokedynamic}, this is stacked
* automatically by the VM.
* @param interfaceMethodName 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 factoryType 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.
* @param interfaceMethodType Signature and return type of method to be
* implemented by the function object.
* @param implementation A direct method handle describing the implementation
* method which should be called (with suitable adaptation
* of argument types and return types, and with captured
* arguments prepended to the invocation arguments) at
* invocation time.
* @param dynamicMethodType The signature and return type that should
* be enforced dynamically at invocation time.
* In simple use cases this is the same as
* {@code interfaceMethodType}.
* @return a CallSite whose target can be used to perform capture, generating
* instances of the interface named by {@code factoryType}
* @throws LambdaConversionException If {@code caller} does not have full privilege
* access, or if {@code interfaceMethodName} is not a valid JVM
* method name, or if the return type of {@code factoryType} is not
* an interface, or if {@code implementation} is not a direct method
* handle referencing a method or constructor, or if the linkage
* invariants are violated, as defined {@link LambdaMetafactory above}.
* @throws NullPointerException If any argument is {@code null}.
*/
public static CallSite metafactory(MethodHandles.Lookup caller,
String interfaceMethodName,
MethodType factoryType,
MethodType interfaceMethodType,
MethodHandle implementation,
MethodType dynamicMethodType)
throws LambdaConversionException {
AbstractValidatingLambdaMetafactory mf;
mf = new InnerClassLambdaMetafactory(Objects.requireNonNull(caller),
Objects.requireNonNull(factoryType),
Objects.requireNonNull(interfaceMethodName),
Objects.requireNonNull(interfaceMethodType),
Objects.requireNonNull(implementation),
Objects.requireNonNull(dynamicMethodType),
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 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 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}.
*
* 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:
*
* 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 altInterfaces} is subject to the same
* restrictions as {@code Rd}, the return type of {@code factoryType},
* as described {@link LambdaMetafactory above}. Each {@code MethodType}
* named by {@code altMethods} is subject to the same restrictions as
* {@code interfaceMethodType}, 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}.
*
* 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:
*
*
*
*
*
*
*
*
*
*
*
*
*
*
* @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 Invocation-time checks
*
* Primitive Primitive
* Q can be converted to S via a primitive widening conversion
* None
*
*
* Primitive Reference
* S is a supertype of the Wrapper(Q)
* Cast from Wrapper(Q) to S
*
*
* Reference Primitive
* 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
* for parameter types: S is a supertype of Q
*
*
for return types: noneCast from Q to S
* {@code
* CallSite altMetafactory(MethodHandles.Lookup caller,
* String interfaceMethodName,
* MethodType factoryType,
* Object... args)
* }
*
* {@code
* CallSite altMetafactory(MethodHandles.Lookup caller,
* String interfaceMethodName,
* MethodType factoryType,
* MethodType interfaceMethodType,
* MethodHandle implementation,
* MethodType dynamicMethodType,
* int flags,
* int altInterfaceCount, // IF flags has MARKERS set
* Class... altInterfaces, // IF flags has MARKERS set
* int altMethodCount, // IF flags has BRIDGES set
* MethodType... altMethods // IF flags has BRIDGES set
* )
* }
*
*
*
*
*
*
*
* @param caller Represents a lookup context with the accessibility
* privileges of the caller. Specifically, the lookup context
* must have {@linkplain MethodHandles.Lookup#hasFullPrivilegeAccess()
* full privilege access}.
* When used with {@code invokedynamic}, this is stacked
* automatically by the VM.
* @param interfaceMethodName 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 factoryType 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.
* @param args An array of {@code Object} containing the required
* arguments {@code interfaceMethodType}, {@code implementation},
* {@code dynamicMethodType}, {@code flags}, and any
* optional arguments, as described above
* @return a CallSite whose target can be used to perform capture, generating
* instances of the interface named by {@code factoryType}
* @throws LambdaConversionException If {@code caller} does not have full privilege
* access, or if {@code interfaceMethodName} is not a valid JVM
* method name, or if the return type of {@code factoryType} is not
* an interface, or if any of {@code altInterfaces} is not an
* interface, or if {@code implementation} is not a direct method
* handle referencing a method or constructor, or if the linkage
* invariants are violated, as defined {@link LambdaMetafactory above}.
* @throws NullPointerException If any argument, or any component of {@code args},
* is {@code null}.
* @throws IllegalArgumentException If the number or types of the components
* of {@code args} do not follow the above rules, or if
* {@code altInterfaceCount} or {@code altMethodCount} are negative
* integers.
*/
public static CallSite altMetafactory(MethodHandles.Lookup caller,
String interfaceMethodName,
MethodType factoryType,
Object... args)
throws LambdaConversionException {
Objects.requireNonNull(caller);
Objects.requireNonNull(interfaceMethodName);
Objects.requireNonNull(factoryType);
Objects.requireNonNull(args);
int argIndex = 0;
MethodType interfaceMethodType = extractArg(args, argIndex++, MethodType.class);
MethodHandle implementation = extractArg(args, argIndex++, MethodHandle.class);
MethodType dynamicMethodType = extractArg(args, argIndex++, MethodType.class);
int flags = extractArg(args, argIndex++, Integer.class);
Class[] altInterfaces = EMPTY_CLASS_ARRAY;
MethodType[] altMethods = EMPTY_MT_ARRAY;
if ((flags & FLAG_MARKERS) != 0) {
int altInterfaceCount = extractArg(args, argIndex++, Integer.class);
if (altInterfaceCount < 0) {
throw new IllegalArgumentException("negative argument count");
}
if (altInterfaceCount > 0) {
altInterfaces = extractArgs(args, argIndex, Class.class, altInterfaceCount);
argIndex += altInterfaceCount;
}
}
if ((flags & FLAG_BRIDGES) != 0) {
int altMethodCount = extractArg(args, argIndex++, Integer.class);
if (altMethodCount < 0) {
throw new IllegalArgumentException("negative argument count");
}
if (altMethodCount > 0) {
altMethods = extractArgs(args, argIndex, MethodType.class, altMethodCount);
argIndex += altMethodCount;
}
}
if (argIndex < args.length) {
throw new IllegalArgumentException("too many arguments");
}
boolean isSerializable = ((flags & FLAG_SERIALIZABLE) != 0);
if (isSerializable) {
boolean foundSerializableSupertype = Serializable.class.isAssignableFrom(factoryType.returnType());
for (Class c : altInterfaces)
foundSerializableSupertype |= Serializable.class.isAssignableFrom(c);
if (!foundSerializableSupertype) {
altInterfaces = Arrays.copyOf(altInterfaces, altInterfaces.length + 1);
altInterfaces[altInterfaces.length-1] = Serializable.class;
}
}
AbstractValidatingLambdaMetafactory mf
= new InnerClassLambdaMetafactory(caller,
factoryType,
interfaceMethodName,
interfaceMethodType,
implementation,
dynamicMethodType,
isSerializable,
altInterfaces,
altMethods);
mf.validateMetafactoryArgs();
return mf.buildCallSite();
}
private static