jaroslav@1692: /* jaroslav@1692: * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. jaroslav@1692: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@1692: * jaroslav@1692: * This code is free software; you can redistribute it and/or modify it jaroslav@1692: * under the terms of the GNU General Public License version 2 only, as jaroslav@1692: * published by the Free Software Foundation. Oracle designates this jaroslav@1692: * particular file as subject to the "Classpath" exception as provided jaroslav@1692: * by Oracle in the LICENSE file that accompanied this code. jaroslav@1692: * jaroslav@1692: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@1692: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@1692: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@1692: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@1692: * accompanied this code). jaroslav@1692: * jaroslav@1692: * You should have received a copy of the GNU General Public License version jaroslav@1692: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@1692: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@1692: * jaroslav@1692: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@1692: * or visit www.oracle.com if you need additional information or have any jaroslav@1692: * questions. jaroslav@1692: */ jaroslav@1692: jaroslav@1692: package java.lang.invoke; jaroslav@1692: jaroslav@1692: import java.io.Serializable; jaroslav@1692: import java.util.Arrays; jaroslav@1692: jaroslav@1692: /** jaroslav@1692: *
Methods to facilitate the creation of simple "function objects" that jaroslav@1692: * implement one or more interfaces by delegation to a provided {@link MethodHandle}, jaroslav@1692: * possibly after type adaptation and partial evaluation of arguments. These jaroslav@1692: * methods are typically used as bootstrap methods for {@code invokedynamic} jaroslav@1692: * call sites, to support the lambda expression and method jaroslav@1692: * reference expression features of the Java Programming Language. jaroslav@1692: * jaroslav@1692: *
Indirect access to the behavior specified by the provided {@code MethodHandle} jaroslav@1692: * proceeds in order through three phases: jaroslav@1692: *
It is sometimes useful to restrict the set of inputs or results permitted
jaroslav@1692: * at invocation. For example, when the generic interface {@code Predicate This class provides two forms of linkage methods: a standard version
jaroslav@1692: * ({@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)})
jaroslav@1692: * using an optimized protocol, and an alternate version
jaroslav@1692: * {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}).
jaroslav@1692: * The alternate version is a generalization of the standard version, providing
jaroslav@1692: * additional control over the behavior of the generated function objects via
jaroslav@1692: * flags and additional arguments. The alternate version adds the ability to
jaroslav@1692: * manage the following attributes of function objects:
jaroslav@1692: *
jaroslav@1692: * Assume the linkage arguments are as follows:
jaroslav@1692: * Then the following linkage invariants must hold:
jaroslav@1692: * Further, at capture time, if {@code implMethod} corresponds to an instance
jaroslav@1692: * method, and there are any capture arguments ({@code K > 0}), then the first
jaroslav@1692: * capture argument (corresponding to the receiver) must be non-null.
jaroslav@1692: *
jaroslav@1692: * A type Q is considered adaptable to S as follows:
jaroslav@1692: * The argument list of the implementation method and the argument list of
jaroslav@1692: * the interface method(s) may differ in several ways. The implementation
jaroslav@1692: * methods may have additional arguments to accommodate arguments captured by
jaroslav@1692: * the lambda expression; there may also be differences resulting from permitted
jaroslav@1692: * adaptations of arguments, such as casting, boxing, unboxing, and primitive
jaroslav@1692: * widening. (Varargs adaptations are not handled by the metafactories; these are
jaroslav@1692: * expected to be handled by the caller.)
jaroslav@1692: *
jaroslav@1692: * Invokedynamic call sites have two argument lists: a static argument list
jaroslav@1692: * and a dynamic argument list. The static argument list is stored in the
jaroslav@1692: * constant pool; the dynamic argument is pushed on the operand stack at capture
jaroslav@1692: * time. The bootstrap method has access to the entire static argument list
jaroslav@1692: * (which in this case, includes information describing the implementation method,
jaroslav@1692: * the target interface, and the target interface method(s)), as well as a
jaroslav@1692: * method signature describing the number and static types (but not the values)
jaroslav@1692: * of the dynamic arguments and the static return type of the invokedynamic site.
jaroslav@1692: *
jaroslav@1692: * @implNote The implementation method is described with a method handle. In
jaroslav@1692: * theory, any method handle could be used. Currently supported are direct method
jaroslav@1692: * handles representing invocation of virtual, interface, constructor and static
jaroslav@1692: * methods.
jaroslav@1692: */
jaroslav@1692: public class LambdaMetafactory {
jaroslav@1692:
jaroslav@1692: /** Flag for alternate metafactories indicating the lambda object
jaroslav@1692: * must be serializable */
jaroslav@1692: public static final int FLAG_SERIALIZABLE = 1 << 0;
jaroslav@1692:
jaroslav@1692: /**
jaroslav@1692: * Flag for alternate metafactories indicating the lambda object implements
jaroslav@1692: * other marker interfaces
jaroslav@1692: * besides Serializable
jaroslav@1692: */
jaroslav@1692: public static final int FLAG_MARKERS = 1 << 1;
jaroslav@1692:
jaroslav@1692: /**
jaroslav@1692: * Flag for alternate metafactories indicating the lambda object requires
jaroslav@1692: * additional bridge methods
jaroslav@1692: */
jaroslav@1692: public static final int FLAG_BRIDGES = 1 << 2;
jaroslav@1692:
jaroslav@1692: private static final Class>[] EMPTY_CLASS_ARRAY = new Class>[0];
jaroslav@1692: private static final MethodType[] EMPTY_MT_ARRAY = new MethodType[0];
jaroslav@1692:
jaroslav@1692: /**
jaroslav@1692: * Facilitates the creation of simple "function objects" that implement one
jaroslav@1692: * or more interfaces by delegation to a provided {@link MethodHandle},
jaroslav@1692: * after appropriate type adaptation and partial evaluation of arguments.
jaroslav@1692: * Typically used as a bootstrap method for {@code invokedynamic}
jaroslav@1692: * call sites, to support the lambda expression and method
jaroslav@1692: * reference expression features of the Java Programming Language.
jaroslav@1692: *
jaroslav@1692: * This is the standard, streamlined metafactory; additional flexibility
jaroslav@1692: * is provided by {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}.
jaroslav@1692: * A general description of the behavior of this method is provided
jaroslav@1692: * {@link LambdaMetafactory above}.
jaroslav@1692: *
jaroslav@1692: * When the target of the {@code CallSite} returned from this method is
jaroslav@1692: * invoked, the resulting function objects are instances of a class which
jaroslav@1692: * implements the interface named by the return type of {@code invokedType},
jaroslav@1692: * declares a method with the name given by {@code invokedName} and the
jaroslav@1692: * signature given by {@code samMethodType}. It may also override additional
jaroslav@1692: * methods from {@code Object}.
jaroslav@1692: *
jaroslav@1692: * @param caller Represents a lookup context with the accessibility
jaroslav@1692: * privileges of the caller. When used with {@code invokedynamic},
jaroslav@1692: * this is stacked automatically by the VM.
jaroslav@1692: * @param invokedName The name of the method to implement. When used with
jaroslav@1692: * {@code invokedynamic}, this is provided by the
jaroslav@1692: * {@code NameAndType} of the {@code InvokeDynamic}
jaroslav@1692: * structure and is stacked automatically by the VM.
jaroslav@1692: * @param invokedType The expected signature of the {@code CallSite}. The
jaroslav@1692: * parameter types represent the types of capture variables;
jaroslav@1692: * the return type is the interface to implement. When
jaroslav@1692: * used with {@code invokedynamic}, this is provided by
jaroslav@1692: * the {@code NameAndType} of the {@code InvokeDynamic}
jaroslav@1692: * structure and is stacked automatically by the VM.
jaroslav@1692: * In the event that the implementation method is an
jaroslav@1692: * instance method and this signature has any parameters,
jaroslav@1692: * the first parameter in the invocation signature must
jaroslav@1692: * correspond to the receiver.
jaroslav@1692: * @param samMethodType Signature and return type of method to be implemented
jaroslav@1692: * by the function object.
jaroslav@1692: * @param implMethod A direct method handle describing the implementation
jaroslav@1692: * method which should be called (with suitable adaptation
jaroslav@1692: * of argument types, return types, and with captured
jaroslav@1692: * arguments prepended to the invocation arguments) at
jaroslav@1692: * invocation time.
jaroslav@1692: * @param instantiatedMethodType The signature and return type that should
jaroslav@1692: * be enforced dynamically at invocation time.
jaroslav@1692: * This may be the same as {@code samMethodType},
jaroslav@1692: * or may be a specialization of it.
jaroslav@1692: * @return a CallSite whose target can be used to perform capture, generating
jaroslav@1692: * instances of the interface named by {@code invokedType}
jaroslav@1692: * @throws LambdaConversionException If any of the linkage invariants
jaroslav@1692: * described {@link LambdaMetafactory above}
jaroslav@1692: * are violated
jaroslav@1692: */
jaroslav@1692: public static CallSite metafactory(MethodHandles.Lookup caller,
jaroslav@1692: String invokedName,
jaroslav@1692: MethodType invokedType,
jaroslav@1692: MethodType samMethodType,
jaroslav@1692: MethodHandle implMethod,
jaroslav@1692: MethodType instantiatedMethodType)
jaroslav@1692: {
jaroslav@1692: throw new IllegalStateException();
jaroslav@1692: }
jaroslav@1692:
jaroslav@1692: /**
jaroslav@1692: * Facilitates the creation of simple "function objects" that implement one
jaroslav@1692: * or more interfaces by delegation to a provided {@link MethodHandle},
jaroslav@1692: * after appropriate type adaptation and partial evaluation of arguments.
jaroslav@1692: * Typically used as a bootstrap method for {@code invokedynamic}
jaroslav@1692: * call sites, to support the lambda expression and method
jaroslav@1692: * reference expression features of the Java Programming Language.
jaroslav@1692: *
jaroslav@1692: * This is the general, more flexible metafactory; a streamlined version
jaroslav@1692: * is provided by {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}.
jaroslav@1692: * A general description of the behavior of this method is provided
jaroslav@1692: * {@link LambdaMetafactory above}.
jaroslav@1692: *
jaroslav@1692: * The argument list for this method includes three fixed parameters,
jaroslav@1692: * corresponding to the parameters automatically stacked by the VM for the
jaroslav@1692: * bootstrap method in an {@code invokedynamic} invocation, and an {@code Object[]}
jaroslav@1692: * parameter that contains additional parameters. The declared argument
jaroslav@1692: * list for this method is:
jaroslav@1692: *
jaroslav@1692: * but it behaves as if the argument list is as follows:
jaroslav@1692: *
jaroslav@1692: * Arguments that appear in the argument list for
jaroslav@1692: * {@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)}
jaroslav@1692: * have the same specification as in that method. The additional arguments
jaroslav@1692: * are interpreted as follows:
jaroslav@1692: * Each class named by {@code markerInterfaces} is subject to the same
jaroslav@1692: * restrictions as {@code Rd}, the return type of {@code invokedType},
jaroslav@1692: * as described {@link LambdaMetafactory above}. Each {@code MethodType}
jaroslav@1692: * named by {@code bridges} is subject to the same restrictions as
jaroslav@1692: * {@code samMethodType}, as described {@link LambdaMetafactory above}.
jaroslav@1692: *
jaroslav@1692: * When FLAG_SERIALIZABLE is set in {@code flags}, the function objects
jaroslav@1692: * will implement {@code Serializable}, and will have a {@code writeReplace}
jaroslav@1692: * method that returns an appropriate {@link SerializedLambda}. The
jaroslav@1692: * {@code caller} class must have an appropriate {@code $deserializeLambda$}
jaroslav@1692: * method, as described in {@link SerializedLambda}.
jaroslav@1692: *
jaroslav@1692: * When the target of the {@code CallSite} returned from this method is
jaroslav@1692: * invoked, the resulting function objects are instances of a class with
jaroslav@1692: * the following properties:
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: * @apiNote These linkage methods are designed to support the evaluation
jaroslav@1692: * of lambda expressions and method references in the Java
jaroslav@1692: * Language. For every lambda expressions or method reference in the source code,
jaroslav@1692: * there is a target type which is a functional interface. Evaluating a lambda
jaroslav@1692: * expression produces an object of its target type. The recommended mechanism
jaroslav@1692: * for evaluating lambda expressions is to desugar the lambda body to a method,
jaroslav@1692: * invoke an invokedynamic call site whose static argument list describes the
jaroslav@1692: * sole method of the functional interface and the desugared implementation
jaroslav@1692: * method, and returns an object (the lambda object) that implements the target
jaroslav@1692: * type. (For method references, the implementation method is simply the
jaroslav@1692: * referenced method; no desugaring is needed.)
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: * Q S Link-time checks Invocation-time checks
jaroslav@1692: *
jaroslav@1692: * Primitive Primitive
jaroslav@1692: * Q can be converted to S via a primitive widening conversion
jaroslav@1692: * None
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: * Primitive Reference
jaroslav@1692: * S is a supertype of the Wrapper(Q)
jaroslav@1692: * Cast from Wrapper(Q) to S
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: * Reference Primitive
jaroslav@1692: * for parameter types: Q is a primitive wrapper and Primitive(Q)
jaroslav@1692: * can be widened to S
jaroslav@1692: *
jaroslav@1692: *
for return types: If Q is a primitive wrapper, check that
jaroslav@1692: * Primitive(Q) can be widened to SIf Q is not a primitive wrapper, cast Q to the base Wrapper(S);
jaroslav@1692: * for example Number for numeric types
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: * Reference Reference
jaroslav@1692: * for parameter types: S is a supertype of Q
jaroslav@1692: *
jaroslav@1692: *
for return types: noneCast from Q to S
jaroslav@1692: * {@code
jaroslav@1692: * CallSite altMetafactory(MethodHandles.Lookup caller,
jaroslav@1692: * String invokedName,
jaroslav@1692: * MethodType invokedType,
jaroslav@1692: * Object... args)
jaroslav@1692: * }
jaroslav@1692: *
jaroslav@1692: * {@code
jaroslav@1692: * CallSite altMetafactory(MethodHandles.Lookup caller,
jaroslav@1692: * String invokedName,
jaroslav@1692: * MethodType invokedType,
jaroslav@1692: * MethodType samMethodType,
jaroslav@1692: * MethodHandle implMethod,
jaroslav@1692: * MethodType instantiatedMethodType,
jaroslav@1692: * int flags,
jaroslav@1692: * int markerInterfaceCount, // IF flags has MARKERS set
jaroslav@1692: * Class... markerInterfaces, // IF flags has MARKERS set
jaroslav@1692: * int bridgeCount, // IF flags has BRIDGES set
jaroslav@1692: * MethodType... bridges // IF flags has BRIDGES set
jaroslav@1692: * )
jaroslav@1692: * }
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: *
jaroslav@1692: * @param caller Represents a lookup context with the accessibility
jaroslav@1692: * privileges of the caller. When used with {@code invokedynamic},
jaroslav@1692: * this is stacked automatically by the VM.
jaroslav@1692: * @param invokedName The name of the method to implement. When used with
jaroslav@1692: * {@code invokedynamic}, this is provided by the
jaroslav@1692: * {@code NameAndType} of the {@code InvokeDynamic}
jaroslav@1692: * structure and is stacked automatically by the VM.
jaroslav@1692: * @param invokedType The expected signature of the {@code CallSite}. The
jaroslav@1692: * parameter types represent the types of capture variables;
jaroslav@1692: * the return type is the interface to implement. When
jaroslav@1692: * used with {@code invokedynamic}, this is provided by
jaroslav@1692: * the {@code NameAndType} of the {@code InvokeDynamic}
jaroslav@1692: * structure and is stacked automatically by the VM.
jaroslav@1692: * In the event that the implementation method is an
jaroslav@1692: * instance method and this signature has any parameters,
jaroslav@1692: * the first parameter in the invocation signature must
jaroslav@1692: * correspond to the receiver.
jaroslav@1692: * @param args An {@code Object[]} array containing the required
jaroslav@1692: * arguments {@code samMethodType}, {@code implMethod},
jaroslav@1692: * {@code instantiatedMethodType}, {@code flags}, and any
jaroslav@1692: * optional arguments, as described
jaroslav@1692: * {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)} above}
jaroslav@1692: * @return a CallSite whose target can be used to perform capture, generating
jaroslav@1692: * instances of the interface named by {@code invokedType}
jaroslav@1692: * @throws LambdaConversionException If any of the linkage invariants
jaroslav@1692: * described {@link LambdaMetafactory above}
jaroslav@1692: * are violated
jaroslav@1692: */
jaroslav@1692: public static CallSite altMetafactory(MethodHandles.Lookup caller,
jaroslav@1692: String invokedName,
jaroslav@1692: MethodType invokedType,
jaroslav@1692: Object... args)
jaroslav@1692: {
jaroslav@1692: throw new IllegalStateException();
jaroslav@1692: }
jaroslav@1692: }