java.lang.invoke.LambdaMetafactory Maven / Gradle / Ivy
/*
* Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.lang.invoke;
import java.io.Serializable;
import java.util.Arrays;
/**
* 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
* method handle describing the desired implementation behavior
* for that method, and possibly other additional metadata, and produce a
* {@link CallSite} whose target can be used to create suitable function
* objects. Linkage may involve dynamically loading a new class that
* implements the target interface. The {@code CallSite} can be considered a
* "factory" for function objects and so these linkage methods are referred
* to as "metafactories".
*
* - 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}. Capture may involve allocation of a
* new function object, or may return an existing function object. The
* behavior {@code MethodHandle} may have additional parameters beyond those
* of the specified interface method; these are referred to as captured
* parameters, which must be provided as arguments to the
* {@code CallSite} target, and which may be early-bound to the behavior
* {@code MethodHandle}. The number of captured parameters and their types
* are determined during linkage.
*
* - 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 behavior {@code MethodHandle}
* is invoked with the captured arguments and any additional arguments
* provided on invocation, as if by {@link MethodHandle#invoke(Object...)}.
*
*
* It is sometimes useful to restrict the set of inputs or results permitted
* at invocation. For example, when the generic interface {@code Predicate}
* is parameterized as {@code Predicate}, the input must be a
* {@code String}, even though the method to implement allows any {@code Object}.
* At linkage time, an additional {@link MethodType} parameter describes the
* "instantiated" method type; on invocation, the arguments and eventual result
* are checked against this {@code MethodType}.
*
* 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:
*
*
* - Bridging. It is sometimes useful to implement multiple
* variations of the method signature, involving argument or return type
* adaptation. This occurs when multiple distinct VM signatures for a method
* are logically considered to be the same method by the language. The
* flag {@code FLAG_BRIDGES} indicates that a list of additional
* {@code MethodType}s will be provided, each of which will be implemented
* by the resulting function object. These methods will share the same
* name and instantiated type.
*
* - Multiple interfaces. If needed, more than one interface
* can be implemented by the function object. (These additional interfaces
* are typically marker interfaces with no methods.) The flag {@code FLAG_MARKERS}
* indicates that a list of additional interfaces will be provided, each of
* which should be implemented by the resulting function object.
*
* - Serializability. The generated function objects do not
* generally support serialization. If desired, {@code FLAG_SERIALIZABLE}
* can be used to indicate that the function objects should be serializable.
* Serializable function objects will use, as their serialized form,
* instances of the class {@code SerializedLambda}, which requires additional
* assistance from the capturing class (the class described by the
* {@link MethodHandles.Lookup} parameter {@code caller}); see
* {@link SerializedLambda} for details.
*
*
* Assume the linkage arguments are as follows:
*
* - {@code invokedType} (describing the {@code CallSite} signature) has
* K parameters of types (D1..Dk) and return type Rd;
* - {@code samMethodType} (describing the implemented method type) has N
* parameters, of types (U1..Un) and return type Ru;
* - {@code implMethod} (the {@code MethodHandle} providing the
* implementation has M parameters, of types (A1..Am) and return type Ra
* (if the method describes an instance method, the method type of this
* method handle already includes an extra first argument corresponding to
* the receiver);
* - {@code instantiatedMethodType} (allowing restrictions on invocation)
* has N parameters, of types (T1..Tn) and return type Rt.
*
*
* Then the following linkage invariants must hold:
*
* - Rd is an interface
* - {@code implMethod} is a direct method handle
* - {@code samMethodType} and {@code instantiatedMethodType} have the same
* arity N, and for i=1..N, Ti and Ui are the same type, or Ti and Ui are
* both reference types and Ti is a subtype of Ui
* - Either Rt and Ru are the same type, or both are reference types and
* Rt is a subtype of Ru
* - K + N = M
* - For i=1..K, Di = Ai
* - For i=1..N, Ti is adaptable to Aj, where j=i+k
* - The return type Rt is void, or the return type Ra is not void and is
* adaptable to Rt
*
*
* 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:
*
* 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 S
* If 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: none
* Cast from Q to S
*
*
*
* @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.)
*
* 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
* must be serializable */
public static final int FLAG_SERIALIZABLE = 1 << 0;
/**
* Flag for alternate metafactories indicating the lambda object implements
* other marker interfaces
* besides Serializable
*/
public static final int FLAG_MARKERS = 1 << 1;
/**
* Flag for alternate metafactories indicating the lambda object requires
* additional bridge methods
*/
public static final int FLAG_BRIDGES = 1 << 2;
private static final Class[] EMPTY_CLASS_ARRAY = new Class[0];
private static final MethodType[] EMPTY_MT_ARRAY = new MethodType[0];
/**
* 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 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 and this signature has any parameters,
* the first parameter in the invocation signature must
* correspond to the receiver.
* @param samMethodType Signature and return type of method to be implemented
* by the function object.
* @param implMethod A direct method handle describing the implementation
* method which should be called (with suitable adaptation
* of argument types, return types, and with captured
* arguments prepended to the invocation arguments) at
* invocation time.
* @param instantiatedMethodType The signature and return type that should
* be enforced dynamically at invocation time.
* This may be the same as {@code samMethodType},
* or may be a specialization of it.
* @return a CallSite whose target can be used to perform capture, generating
* instances of the interface named by {@code invokedType}
* @throws LambdaConversionException If any of the linkage invariants
* described {@link LambdaMetafactory above}
* are violated
*/
public static CallSite metafactory(MethodHandles.Lookup caller,
String invokedName,
MethodType invokedType,
MethodType samMethodType,
MethodHandle implMethod,
MethodType instantiatedMethodType)
{
throw new IllegalStateException();
}
/**
* 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 #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:
*
*
{@code
* CallSite altMetafactory(MethodHandles.Lookup caller,
* String invokedName,
* MethodType invokedType,
* Object... args)
* }
*
* but it behaves as if the argument list is as follows:
*
*
{@code
* CallSite altMetafactory(MethodHandles.Lookup caller,
* String invokedName,
* MethodType invokedType,
* MethodType samMethodType,
* MethodHandle implMethod,
* MethodType instantiatedMethodType,
* int flags,
* int markerInterfaceCount, // IF flags has MARKERS set
* Class... markerInterfaces, // IF flags has MARKERS set
* int bridgeCount, // IF flags has BRIDGES set
* MethodType... bridges // IF flags has BRIDGES set
* )
* }
*
* 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:
*
* - {@code flags} indicates additional options; this is a bitwise
* OR of desired flags. Defined flags are {@link #FLAG_BRIDGES},
* {@link #FLAG_MARKERS}, and {@link #FLAG_SERIALIZABLE}.
* - {@code markerInterfaceCount} is the number of additional interfaces
* the function object should implement, and is present if and only if the
* {@code FLAG_MARKERS} flag is set.
* - {@code markerInterfaces} is a variable-length list of additional
* interfaces to implement, whose length equals {@code markerInterfaceCount},
* and is present if and only if the {@code FLAG_MARKERS} flag is set.
* - {@code bridgeCount} is the number of additional method signatures
* the function object should implement, and is present if and only if
* the {@code FLAG_BRIDGES} flag is set.
* - {@code bridges} is a variable-length list of additional
* methods signatures to implement, whose length equals {@code bridgeCount},
* and is present if and only if the {@code FLAG_BRIDGES} flag is set.
*
*
* 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}.
*
*
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 class implements the interface named by the return type
* of {@code invokedType} and any interfaces named by {@code markerInterfaces}
* - The class declares methods with the name given by {@code invokedName},
* and the signature given by {@code samMethodType} and additional signatures
* given by {@code bridges}
* - The class may override methods from {@code Object}, and may
* implement methods related to serialization.
*
*
* @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 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)
{
throw new IllegalStateException();
}
}