* As described in the Java Virtual Machine Specification, certain types in this package * are given special treatment by the virtual machine: *
* Before the JVM can execute an {@code invokedynamic} instruction, * the instruction must first be linked. * Linking is accomplished by calling a bootstrap method * which is given the static information content of the call, * and which must produce a {@link java.lang.invoke.CallSite} * that gives the behavior of the invocation. *
* Each {@code invokedynamic} instruction statically specifies its own * bootstrap method as a constant pool reference. * The constant pool reference also specifies the invocation's name and method type descriptor, * just like {@code invokestatic} and the other invoke instructions. * *
* Each dynamically-computed 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 {@code getstatic} and the other field reference instructions. * (Roughly speaking, a dynamically-computed constant is to a dynamically-computed call site * as a {@code CONSTANT_Fieldref} is to a {@code CONSTANT_Methodref}.) * *
* The bootstrap method is then invoked, as if by * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke}, * with the following arguments: *
* For a dynamically-computed call site, the returned result must be a non-null reference to a * {@link java.lang.invoke.CallSite CallSite}. * The type of the call site's target must be exactly equal to the type * derived from the invocation's type descriptor and passed to * the bootstrap method. If these conditions are not met, a {@code BootstrapMethodError} is thrown. * On success the call site then becomes permanently linked to the {@code invokedynamic} * instruction. *
* For a dynamically-computed constant, the first parameter of the bootstrap * method must be assignable to {@code MethodHandles.Lookup}. If this condition * is not met, a {@code BootstrapMethodError} is thrown. * On success the result of the bootstrap method is cached as the resolved * constant value. *
* If an exception, {@code E} say, occurs during execution of the bootstrap method, then * resolution fails and terminates abnormally. {@code E} is rethrown if the type of * {@code E} is {@code Error} or a subclass, otherwise a * {@code BootstrapMethodError} that wraps {@code E} is thrown. * If this happens, the same error will be thrown for all * subsequent attempts to execute the {@code invokedynamic} instruction or load the * dynamically-computed constant. * *
* 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 {@code invokedynamic} instruction is either * unlinked or linked to a unique {@code CallSite} object. *
* In an application which requires {@code invokedynamic} instructions with individually * mutable behaviors, their bootstrap methods should produce distinct * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request. * Alternatively, an application can link a single {@code CallSite} object * to several {@code 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 dynamically-computed * call site or constant, the JVM must choose one bootstrap method result and install it visibly to * all threads. Any other bootstrap method calls are allowed to complete, but their * results are ignored. *
* Discussion: * These rules do not enable the JVM to share call sites, * or to issue “causeless” bootstrap method calls. * Every {@code invokedynamic} instruction 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. * *
* For a dynamically-computed constant, the bootstrap method is invoked with parameter types * {@code MethodHandles.Lookup}, {@code String}, {@code Class}, and the types of any * static arguments; the return type is the type represented by the {@code Class}. *
* Because {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke} allows for * adaptations between the invoked method type and the bootstrap method handle's method type, * there is flexibility in the declaration of the bootstrap method. * For a dynamically-computed constant the first parameter type of the bootstrap method handle * must be assignable to {@code MethodHandles.Lookup}, other than that constraint the same degree * of flexibility applies to bootstrap methods of dynamically-computed call sites and * dynamically-computed constants. * Note: this constraint allows for the future possibility where the bootstrap method is * invoked with just the parameter types of static arguments, thereby supporting a wider * range of methods compatible with the static arguments (such as methods that don't declare * or require the lookup, name, and type meta-data parameters). *
For example, for dynamically-computed call site, a the first argument * could be {@code Object} instead of {@code MethodHandles.Lookup}, and the return type * could also be {@code Object} instead of {@code 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.) *
* 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 {@code 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 {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.) *
* Given these rules, here are examples of legal bootstrap method declarations for * dynamically-computed call sites, given various numbers {@code N} of extra arguments. * The first row (marked {@code *}) will work for any number of extra arguments. *
| N | Sample bootstrap method |
|---|---|
| * |
*
|
| 0 |
*
|
| 1 | * {@code CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)} |
| 2 |
*
|
* Since dynamically-computed constants can be provided as static arguments to bootstrap * methods, there are no limitations on the types of bootstrap arguments. * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} * cannot be directly supplied by {@code CONSTANT_Integer} * constant pool entries, since the {@code asType} conversions do * not perform the necessary narrowing primitive conversions. *
* In the above examples, the return type is always {@code CallSite}, * but that is not a necessary feature of bootstrap methods. * In the case of a dynamically-computed call site, the only requirement is that * the return type of the bootstrap method must be convertible * (using the {@code asType} conversions) to {@code CallSite}, which * means the bootstrap method return type might be {@code Object} or * {@code ConstantCallSite}. * In the case of a dynamically-resolved constant, the return type of the bootstrap * method must be convertible to the type of the constant, as * represented by its field type descriptor. For example, if the * dynamic constant has a field type descriptor of {@code "C"} * ({@code char}) then the bootstrap method return type could be * {@code Object}, {@code Character}, or {@code char}, but not * {@code int} or {@code Integer}. * * @author John Rose, JSR 292 EG * @since 1.7 */ package java.lang.invoke;