java.lang.invokepackage 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
VarHandlecontain 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
invokedynamicinstruction is called a dynamic call site.
Before the JVM can execute a dynamic call site (an
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
that gives the behavior of the call site.
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 type descriptor,
invokevirtual and the other invoke instructions.
Linking starts with resolving the constant pool entry for the
bootstrap method, and resolving a
MethodType object for
the type descriptor of the dynamic call site.
This resolution process may trigger class loading.
It may therefore throw an error if a class fails to load.
This error becomes the abnormal termination of the dynamic
call site execution.
Linkage does not trigger class initialization.
The bootstrap method is invoked on at least three values:
MethodHandles.Lookup, a lookup object on the caller class in which dynamic call site occurs
String, the method name mentioned in the call site
MethodType, the resolved type descriptor of the call
- optionally, any number of additional static arguments taken from the constant pool
invokedynamic instruction, the
returned result must be convertible to a non-null reference to 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
If an exception,
E say, occurs when linking the call site then the
linkage fails and terminates abnormally.
E is rethrown if the type of
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.
timing of linkageA dynamic call site is linked just before its first execution. The bootstrap method call implementing the linkage occurs within a thread that is attempting a first execution.
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
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
invokedynamic instructions, in which case
a change to the target method will become visible at each of
If several threads simultaneously execute a bootstrap method for a single dynamic
call site, the JVM must choose one
CallSite object 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 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 methodsAs long as each bootstrap method can be correctly invoked by
MethodHandle.invoke, its detailed type is arbitrary. For example, the first argument could be
MethodHandles.Lookup, and the return type could also be
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
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.
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
A variable-arity bootstrap method can accept thousands of static arguments,
subject only by limits imposed by the class-file format.
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
CONSTANT_MethodHandle constants, the modifier bit for variable arity methods,
Given these rules, here are examples of legal bootstrap method declarations,
given various numbers
N of extra arguments.
The first row (marked
*) will work for any number of extra arguments.
|N||Sample bootstrap method|
int), respectively. The second-to-last example assumes that all extra arguments are of type
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
if that is the type of the corresponding constant in
In that case, the
MethodHandle.invoke call will pass the extra method handle
constant as an
Object, but the type matching machinery of
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
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
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 would be likely to produce large class files and constant pools.
Interface Summary Interface Description MethodHandleInfoA symbolic reference obtained by cracking a direct method handle into its consitutent symbolic parts.
Class Summary Class Description CallSiteA
CallSiteis a holder for a variable
MethodHandle, which is called its
CallSitewhose target is permanent, and can never be changed.
LambdaMetafactoryMethods to facilitate the creation of simple "function objects" that implement one or more interfaces by delegation to a provided
MethodHandle, possibly after type adaptation and partial evaluation of arguments.
MethodHandleA 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. MethodHandleProxiesThis class consists exclusively of static methods that help adapt method handles to other JVM types, such as interfaces. MethodHandlesThis class consists exclusively of static methods that operate on or return method handles. MethodHandles.LookupA lookup object is a factory for creating method handles, when the creation requires access checking. MethodTypeA 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. MutableCallSiteA
CallSitewhose target variable behaves like an ordinary field.
SerializedLambdaSerialized form of a lambda expression. StringConcatFactoryMethods 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. SwitchPointA
SwitchPointis an object which can publish state transitions to other threads.
VarHandleA 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. VolatileCallSiteA
CallSitewhose target acts like a volatile variable.
Enum Summary Enum Description VarHandle.AccessModeThe set of access modes that specify how a variable, referenced by a VarHandle, is accessed.
Exception Summary Exception Description LambdaConversionExceptionLambdaConversionException StringConcatExceptionStringConcatException is thrown by
StringConcatFactorywhen linkage invariants are violated.
WrongMethodTypeExceptionThrown to indicate that code has attempted to call a method handle via the wrong method type.