Package java.lang.invoke
java.lang.invoke
package contains dynamic language support provided directly by the Java core class libraries and virtual machine.As described in the Java Virtual Machine Specification, certain types in this package have special relations to dynamic language support in the virtual machine:
- The classes
MethodHandle
VarHandle
contain signature polymorphic methods which can be linked regardless of their type descriptor. Normally, method linkage requires exact matching of type descriptors. - The JVM bytecode format supports immediate constants of the classes
MethodHandle
andMethodType
.
Summary of relevant Java Virtual Machine changes
The following low-level information summarizes relevant parts of the Java Virtual Machine specification. For full details, please see the current version of that specification. Each occurrence of aninvokedynamic
instruction is called a dynamic call site . Each occurrence of an CONSTANT_ConstantDynamic
constant pool entry is called a dynamic constant .
invokedynamic
instructions
Bytecode may contain dynamic call sites equipped with equipped with bootstrap methods which perform their resolution. A dynamic call site is originally in an unlinked state. In this state, there is no target method for the call site to invoke. Before the JVM can execute a dynamic call site (an invokedynamic
instruction), the call site must first be linked. Linking is accomplished by calling a bootstrap method which is given the static information content of the call site, and which must produce a method handle
that gives the behavior of the call site. Each invokedynamic
instruction statically specifies its own bootstrap method as a constant pool reference. The constant pool reference also specifies the call site's name and method type descriptor, just like
and the other invoke instructions.
invokevirtual
invokestatic
constants with tag CONSTANT_ConstantDynamic
The constant pool may contain constants tagged CONSTANT_ConstantDynamic
, equipped with bootstrap methods which perform their resolution. Such a dynamic constant is originally in an unresolved state. Before the JVM can evaluate a dynamic constant, it must first be resolved. Dynamic constant resolution is accomplished by calling a bootstrap method which is given the static information content of the constant, and which must produce a value of the constant's statically declared type.
Each CONSTANT_ConstantDynamic
constant statically specifies its own bootstrap method as a constant pool reference. The constant pool reference also specifies the constant's name and field type descriptor, just like getstatic
and the other field reference instructions. (Roughly speaking, a dynamic constant is to a dynamic call descriptor as a CONSTANT_Fieldref
is to a CONSTANT_Methodref
.)
execution of bootstrap methods
Linking a dynamic call site or dynamic constant starts with resolving constants from the constant pool entryfor the following items:- the bootstrap method, and resolvingeither a
CONSTANT_MethodHandle
or aCONSTANT_ConstantDynamic
entry -
if linking a dynamic call site, the
MethodType
object forderived from type component of theCONSTANT_NameAndType
descriptor of the call -
if linking a dynamic constant, the
Class
derived from type component of theCONSTANT_NameAndType
descriptor of the dynamic call site.constant
The arity of the bootstrap method determines its invocation for linkage. If the bootstrap method is invoked onaccepts at least three parameters, or if it is a variable-arity method handle, the linkage information is pushed into the bootstrap method, by invoking it on these values:
- a
MethodHandles.Lookup
, which is a lookup object on the caller class in which dynamic call site or constant occurs - a
String
, the method or constant name mentioned in the call site or constant - a
MethodType
, the resolved type descriptor of the call site, if it is a dynamic call site -
a
Class
, the resolved type descriptor of the constant, if it is a dynamic constant - optionally, between 1 and 251any number of additional static arguments taken from the constant pool
If the bootstrap method accepts two parameters, and it is not a variable-arity method handle, then the linkage information is presented to the bootstrap method by a API which allows it to pull the static arguments. This allows the bootstrap logic the ability to order the resolution of constants and catch linkage exceptions. For this mode of linkage, the bootstrap method is is invoked on just two values:
-
a
MethodHandles.Lookup
, a lookup object on the caller class (as in the "push" mode) -
a
BootstrapCallInfo
object describing the linkage parameters of the dynamic call site or constant
In all cases, bootstrap method invocation is as if by MethodHandle.invoke. TheinvokeWithArguments
, (This is also equivalent to generic invocation if the number of arguments is small enough.)
For an invokedynamic
instruction, the returned result must be convertible to a non-null reference to a CallSite
(or a subclass), otherwise a. If the returned result cannot be converted to the expected type, BootstrapMethodError
is thrown. The type of the call site's target must be exactly equal to the type derived from the dynamic call site's type descriptor and passed to the bootstrap method, otherwise a BootstrapMethodError
is thrown. On success the call site then becomes permanently linked to the dynamic call site.
For a ConstantDynamic
constant, the result returned from the bootstrap method must be convertible (by the same conversions as a method handle transformed by {@code asType} ) to the statically declared type of the ConstantDynamic
constant. On success the constant then becomes permanently linked to the converted result of the bootstrap method.
If an exception, E
say, occurs when linking the call site or constant then the linkage fails and terminates abnormally. E
is rethrown if the type of E
is Error
or a subclass, otherwise a BootstrapMethodError
that wraps E
is thrown. If this happens, the same Error
or subclass will the thrown for all subsequent attempts to execute the dynamic call site or load the dynamic constant.
timing of linkage
A dynamic call site is linked just before its first execution. A dynamic constant is linked just before the first time it is used (by pushing on the stack or linking it as a bootstrap method parameter). The bootstrap method call implementing the linkage occurs within a thread that is attempting a first execution or first use. If there are several such threads, the bootstrap method may be invoked in several threads concurrently. Therefore, bootstrap methods which access global application data must take the usual precautions against race conditions. In any case, every invokedynamic
instruction is either unlinked or linked to a unique CallSite
object.
In an application which requires dynamic call sites with individually mutable behaviors, their bootstrap methods should produce distinct CallSite
objects, one for each linkage request. Alternatively, an application can link a single CallSite
object to several invokedynamic
instructions, in which case a change to the target method will become visible at each of the instructions.
If several threads simultaneously execute a bootstrap method for a single dynamic call site or constant, the JVM must choose one CallSite
objectbootstrap method result and install it visibly to all threads. Any other bootstrap method calls are allowed to complete, but their results are ignored, and their dynamic call site invocations or constant loads proceed with the originally chosen target object.
Discussion: These rules do not enable the JVM to duplicate dynamic call sites, or to issue “causeless” bootstrap method calls. Every dynamic call site transitions at most once from unlinked to linked, just before its first invocation. There is no way to undo the effect of a completed bootstrap method call.
types of bootstrap methods
As long as each bootstrap method can be correctly invoked byMethodHandle.invoke
, its detailed type is arbitrary. For example, the first argument could be Object
instead of MethodHandles.Lookup
, and the return type could also be Object
instead of CallSite
. (Note that the types and number of the stacked arguments limit the legal kinds of bootstrap methods to appropriately typed static methods and constructors of CallSite
subclasses.) If a given invokedynamic
instruction specifies no static arguments, the instruction's bootstrap method will be invoked on three arguments, conveying the instruction's caller class, name, and method type. If the invokedynamic
instruction specifies one or more static arguments, those values will be passed as additional arguments to the method handle. (Note that because there is a limit of 255 arguments to any method, at most 251 extra arguments can be supplied to a non-varargs bootstrap method, since the bootstrap method handle itself and its first three arguments must also be stacked.) The bootstrap method will be invoked as if by either MethodHandle.invoke
(if there are not too many arguments), or invokeWithArguments
. (There is no way to tell the difference.)
The normal argument conversion rules for MethodHandle.invoke
apply to all stacked arguments. For example, if a pushed value is a primitive type, it may be converted to a reference by boxing conversion. If the bootstrap method is a variable arity method (its modifier bit 0x0080
is set), then some or all of the arguments specified here may be collected into a trailing array parameter. (This is not a special rule, but rather a useful consequence of the interaction between CONSTANT_MethodHandle
constants, the modifier bit for variable arity methods, and the asVarargsCollector
transformation.)
Given these rules, here are examples of legal bootstrap method declarations, given various numbers N
of extra arguments. The first rows (marked *
) will work for any number of extra arguments.
N | sample bootstrap method |
---|---|
* | CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args) |
* | CallSite bootstrap(Object... args) |
* | CallSite bootstrap(Object caller, Object... nameAndTypeWithArgs) |
0 | CallSite bootstrap(Lookup caller, String name, MethodType type) |
0 | CallSite bootstrap(Lookup caller, Object... nameAndType) |
1 | CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg) |
2 | CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args) |
2 | CallSite bootstrap(Lookup caller, String name, MethodType type, String... args) |
2 | CallSite bootstrap(Lookup caller, String name, MethodType type, String x, int y) |
CONSTANT_String
and CONSTANT_Integer
, respectively. The second-to-last example assumes that all extra arguments are of type CONSTANT_String
. The other examples work with all types of extra arguments.
As noted above, the actual method type of the bootstrap method can vary. For example, the fourth argument could be MethodHandle
, if that is the type of the corresponding constant in the CONSTANT_InvokeDynamic
entry. In that case, the MethodHandle.invoke
call will pass the extra method handle constant as an Object
, but the type matching machinery of MethodHandle.invoke
will cast the reference back to MethodHandle
before invoking the bootstrap method. (If a string constant were passed instead, by badly generated code, that cast would then fail, resulting in a BootstrapMethodError
.)
Note that, as a consequence of the above rules, the bootstrap method may accept a primitive argument, if it can be represented by a constant pool entry. However, arguments of type boolean
, byte
, short
, or char
cannot be created for bootstrap methods, since such constants cannot be directly represented in the constant pool, and the invocation of the bootstrap method will not perform the necessary narrowing primitive conversions.
Extra bootstrap method arguments are intended to allow language implementors to safely and compactly encode metadata. In principle, the name and extra arguments are redundant, since each call site could be given its own unique bootstrap method. Such a practice is likely to produce large class files and constant pools.
- Since:
- 1.7
-
Interface Summary Interface Description BootstrapCallInfo<T> An interface providing full static information about a particular call to a bootstrap method of an dynamic call site or dynamic constant.ConstantGroup An ordered list of constants, some of which may not yet be linked.MethodHandleInfo A symbolic reference obtained by cracking a direct method handle into its consitutent symbolic parts. -
Class Summary Class Description CallSite ConstantCallSite ConstantGroup.AbstractImpl Utility class for implementing ConstantGroup.LambdaMetafactory Methods to facilitate the creation of simple "function objects" that implement one or more interfaces by delegation to a providedMethodHandle
, possibly after type adaptation and partial evaluation of arguments.MethodHandle A method handle is a typed, directly executable reference to an underlying method, constructor, field, or similar low-level operation, with optional transformations of arguments or return values.MethodHandleProxies This class consists exclusively of static methods that help adapt method handles to other JVM types, such as interfaces.MethodHandles This class consists exclusively of static methods that operate on or return method handles.MethodHandles.Lookup A lookup object is a factory for creating method handles, when the creation requires access checking.MethodType A method type represents the arguments and return type accepted and returned by a method handle, or the arguments and return type passed and expected by a method handle caller.MutableCallSite AMutableCallSite
is aCallSite
whose target variable behaves like an ordinary field.SerializedLambda Serialized form of a lambda expression.StringConcatFactory Methods to facilitate the creation of String concatenation methods, that can be used to efficiently concatenate a known number of arguments of known types, possibly after type adaptation and partial evaluation of arguments.SwitchPoint ASwitchPoint
is an object which can publish state transitions to other threads.VarHandle A VarHandle is a dynamically strongly typed reference to a variable, or to a parametrically-defined family of variables, including static fields, non-static fields, array elements, or components of an off-heap data structure.VolatileCallSite AVolatileCallSite
is aCallSite
whose target acts like a volatile variable. -
Enum Summary Enum Description VarHandle.AccessMode The set of access modes that specify how a variable, referenced by a VarHandle, is accessed. -
Exception Summary Exception Description LambdaConversionException LambdaConversionExceptionStringConcatException StringConcatException is thrown byStringConcatFactory
when linkage invariants are violated.WrongMethodTypeException Thrown to indicate that code has attempted to call a method handle via the wrong method type.