Please note that the specifications and other information contained herein are not final and are subject to change. The information is being made available to you solely for purpose of evaluation.

# Package java.lang.invoke

The `java.lang.invoke` package contains dynamic language support provided directly by the Java core class libraries and virtual machine.

See: Description

- Class Summary
  Class | Description
  --- | ---
  CallSite | A `CallSite` is a holder for a variable `MethodHandle`, which is called its `target`.
  ConstantCallSite | A `ConstantCallSite` is a `CallSite` whose target is permanent, and can never be changed.
  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.
  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 | A `MutableCallSite` is a `CallSite` whose target variable behaves like an ordinary field.
  SwitchPoint | A `SwitchPoint` is an object which can publish state transitions to other threads.
  VolatileCallSite | A `VolatileCallSite` is a `CallSite` whose target acts like a volatile variable.

- Exception Summary
  Exception | Description
  --- | ---
  WrongMethodTypeException | Thrown to indicate that code has attempted to call a method handle via the wrong method type.

## Package java.lang.invoke Description

The `java.lang.invoke` package contains dynamic language support provided directly by the Java core class libraries and virtual machine.

Certain types in this package have special relations to dynamic language support in the virtual machine:

- The class `MethodHandle` contains 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` and `MethodType`.

## Corresponding JVM bytecode format changes

The following low-level information is presented here as a preview of changes being made to the Java Virtual Machine specification for JSR 292. This information will be incorporated in a future version of the JVM specification.

### `invokedynamic` instruction format

In bytecode, an `invokedynamic` instruction is formatted as five bytes. The first byte is the opcode 186 (hexadecimal `BA`). The next two bytes are a constant pool index (in the same format as for the other `invoke` instructions). The final two bytes are reserved for future use and required to be zero. The constant pool reference of an `invokedynamic` instruction is to a entry with tag `CONSTANT_InvokeDynamic` (decimal 18). See below for its format. The entry specifies the following information:

- a bootstrap method (a `MethodHandle` constant)
- the dynamic invocation name (a UTF8 string)
- the argument and return types of the call (encoded as a type descriptor in a UTF8 string)
- optionally, a sequence of additional static arguments to the bootstrap method (`ldc`-type constants)

Each instance of an `invokedynamic` instruction is called a dynamic call site. Multiple instances of an `invokedynamic` instruction can share a single `CONSTANT_InvokeDynamic` entry. In any case, distinct call sites always have distinct linkage state.

A dynamic call site is originally in an unlinked state. In this state, there is no target method for the call site to invoke. A dynamic call site is linked by means of a bootstrap method, as described below.

### constant pool entries for `invokedynamic` instructions

If a constant pool entry has the tag `CONSTANT_InvokeDynamic` (decimal 18), it must contain exactly four more bytes after the tag. These bytes are interpreted as two 16-bit indexes, in the usual `u2` format. The first pair of bytes after the tag must be an index into a side table called the bootstrap method table, which is stored in the `BootstrapMethods` attribute as described below. The second pair of bytes must be an index to a `CONSTANT_NameAndType`.

The first index specifies a bootstrap method used by the associated dynamic call sites. The second index specifies the method name, argument types, and return type of the dynamic call site. The structure of such an entry is therefore analogous to a `CONSTANT_Methodref`, except that the bootstrap method specifier reference replaces the `CONSTANT_Class` reference of a `CONSTANT_Methodref` entry.

### constant pool entries for method types

If a constant pool entry has the tag `CONSTANT_MethodType` (decimal 16), it must contain exactly two more bytes, which must be an index to a `CONSTANT_Utf8` entry which represents a method type descriptor.

The JVM will ensure that on first execution of an `ldc` instruction for this entry, a `MethodType` will be created which represents the type descriptor. Any classes mentioned in the `MethodType` will be loaded if necessary, but not initialized. Access checking and error reporting is performed exactly as it is for references by `ldc` instructions to `CONSTANT_Class` constants.

### constant pool entries for method handles

If a constant pool entry has the tag `CONSTANT_MethodHandle` (decimal 15), it must contain exactly three more bytes. The first byte after the tag is a subtag value which must be in the range 1 through 9, and the last two must be an index to a `CONSTANT_Fieldref`, `CONSTANT_Methodref`, or `CONSTANT_InterfaceMethodref` entry which represents a field or method for which a method handle is to be created. Furthermore, the subtag value and the type of the constant index value must agree according to the table below.

The JVM will ensure that on first execution of an `ldc` instruction for this entry, a `MethodHandle` will be created which represents the field or method reference, according to the specific mode implied by the subtag.

As with `CONSTANT_Class` and `CONSTANT_MethodType` constants, the `Class` or `MethodType` object which reifies the field or method's type is created. Any classes mentioned in this reification will be loaded if necessary, but not initialized, and access checking and error reporting performed as usual.

Unlike the reflective `Lookup` API, there are no security manager calls made when these constants are resolved.

The method handle itself will have a type and behavior determined by the subtag as follows: ``

N | subtag name | member | MH type | bytecode behavior | lookup expression
--- | --- | --- | --- | --- | ---
1 | REF_getField | C.f:T | (C)T | getfield C.f:T | findGetter(C.class,"f",T.class)
2 | REF_getStatic | C.f:T | ( )T | getstatic C.f:T | findStaticGetter(C.class,"f",T.class)
3 | REF_putField | C.f:T | (C,T)void | putfield C.f:T | findSetter(C.class,"f",T.class)
4 | REF_putStatic | C.f:T | (T)void | putstatic C.f:T | findStaticSetter(C.class,"f",T.class)
5 | REF_invokeVirtual | C.m(A*)T | (C,A*)T | invokevirtual C.m(A*)T | findVirtual(C.class,"m",MT)
6 | REF_invokeStatic | C.m(A*)T | (C,A*)T | invokestatic C.m(A*)T | findStatic(C.class,"m",MT)
7 | REF_invokeSpecial | C.m(A*)T | (C,A*)T | invokespecial C.m(A*)T | findSpecial(C.class,"m",MT,this.class)
8 | REF_newInvokeSpecial | C.<init>(A*)void | (A*)C | new C; dup; invokespecial C.<init>(A*)void | findConstructor(C.class,MT)
9 | REF_invokeInterface | C.m(A*)T | (C,A*)T | invokeinterface C.m(A*)T | findVirtual(C.class,"m",MT)

Here, the type `C` is taken from the `CONSTANT_Class` reference associated with the `CONSTANT_NameAndType` descriptor. The field name `f` or method name `m` is taken from the `CONSTANT_NameAndType` as is the result type `T` and (in the case of a method or constructor) the argument type sequence `A*`.

Each method handle constant has an equivalent instruction sequence called its bytecode behavior. In general, creating a method handle constant can be done in exactly the same circumstances that the JVM would successfully resolve the symbolic references in the bytecode behavior. Also, the type of a method handle constant is such that a valid `invokeExact` call on the method handle has exactly the same JVM stack effects as the bytecode behavior. Finally, calling a method handle constant on a valid set of arguments has exactly the same effect and returns the same result (if any) as the corresponding bytecode behavior.

Each method handle constant also has an equivalent reflective lookup expression, which is a query to a method in `MethodHandles.Lookup`. In the example lookup method expression given in the table above, the name `MT` stands for a `MethodType` built from `T` and the sequence of argument types `A*`. (Note that the type `C` is not prepended to the query type `MT` even if the member is non-static.) In the case of `findSpecial`, the name `this.class` refers to the class containing the bytecodes.

The special name `<clinit>` is not allowed. The special name `<init>` is not allowed except for subtag 8 as shown.

The JVM verifier and linker apply the same access checks and restrictions for these references as for the hypothetical bytecode instructions specified in the last column of the table. A method handle constant will successfully resolve to a method handle if the symbolic references of the corresponding bytecode instruction(s) would also resolve successfully. Otherwise, an attempt to resolve the constant will throw equivalent linkage errors. In particular, method handles to private and protected members can be created in exactly those classes for which the corresponding normal accesses are legal.

A constant may refer to a method or constructor with the `varargs` bit (hexadecimal `0x0080`) set in its modifier bitmask. The method handle constant produced for such a method behaves as if it were created by `asVarargsCollector`. In other words, the constant method handle will exhibit variable arity, when invoked via `invokeGeneric`. On the other hand, its behavior with respect to `invokeExact` will be the same as if the `varargs` bit were not set.

Although the `CONSTANT_MethodHandle` and `CONSTANT_MethodType` constant types resolve class names, they do not force class initialization. Method handle constants for subtags `REF_getStatic`, `REF_putStatic`, and `REF_invokeStatic` may force class initialization on their first invocation, just like the corresponding bytecodes.

The rules of section 5.4.3 of the JVM Specification apply to the resolution of `CONSTANT_MethodType`, `CONSTANT_MethodHandle`, and `CONSTANT_InvokeDynamic` constants, by the execution of `invokedynamic` and `ldc` instructions. (Roughly speaking, this means that every use of a constant pool entry must lead to the same outcome. If the resolution succeeds, the same object reference is produced by every subsequent execution of the same instruction. If the resolution of the constant causes an error to occur, the same error will be re-thrown on every subsequent attempt to use this particular constant.)

Constants created by the resolution of these constant pool types are not necessarily interned. Except for `CONSTANT_Class` and `CONSTANT_String` entries, two distinct constant pool entries might not resolve to the same reference even if they contain the same symbolic reference.

## Bootstrap Methods

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 type descriptor, just like `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.

Next, the bootstrap method call is started, with at least four values being stacked:

- a `MethodHandle`, the resolved bootstrap method itself
- a `MethodHandles.Lookup`, a lookup object on the caller class in which dynamic call site occurs
- a `String`, the method name mentioned in the call site
- a `MethodType`, the resolved type descriptor of the call
- optionally, one or more additional static arguments

The method handle is then applied to the other values as if by `invokeGeneric`. The returned result must be a `CallSite` (or a subclass). 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. The call site then becomes permanently linked to the dynamic call site.

As long as each bootstrap method can be correctly invoked by `invokeGeneric`, 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.)

After resolution, the linkage process may fail in a variety of ways. All failures are reported by a `BootstrapMethodError`, which is thrown as the abnormal termination of the dynamic call site execution. The following circumstances will cause this:

- the index to the bootstrap method specifier is out of range
- the bootstrap method cannot be resolved
- the `MethodType` to pass to the bootstrap method cannot be resolved
- a static argument to the bootstrap method cannot be resolved (i.e., a `CONSTANT_Class`, `CONSTANT_MethodType`, or `CONSTANT_MethodHandle` argument cannot be linked)
- the bootstrap method has the wrong arity, causing `invokeGeneric` to throw `WrongMethodTypeException`
- the bootstrap method has a wrong argument or return type
- the bootstrap method invocation completes abnormally
- the result from the bootstrap invocation is not a reference to an object of type `CallSite`
- the target of the `CallSite` does not have a target of the expected `MethodType`

### timing of linkage

A 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 `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, 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.

### the `BootstrapMethods` attribute

Each `CONSTANT_InvokeDynamic` entry contains an index which references a bootstrap method specifier; all such specifiers are contained in a separate array. This array is defined by a class attribute named `BootstrapMethods`. The body of this attribute consists of a sequence of byte pairs, all interpreted as as 16-bit counts or constant pool indexes, in the `u2` format. The attribute body starts with a count of bootstrap method specifiers, which is immediately followed by the sequence of specifiers.

Each bootstrap method specifier contains an index to a `CONSTANT_MethodHandle` constant, which is the bootstrap method itself. This is followed by a count, and then a sequence (perhaps empty) of indexes to additional static arguments for the bootstrap method.

During class loading, the verifier must check the structure of the `BootstrapMethods` attribute. In particular, each constant pool index must be of the correct type. A bootstrap method index must refer to a `CONSTANT_MethodHandle` (tag 15). Every other index must refer to a valid operand of an `ldc_w` or `ldc2_w` instruction (tag 3..8 or 15..16).

### static arguments to the bootstrap method

An `invokedynamic` instruction specifies at least three arguments to pass to its bootstrap method: The caller class (expressed as a `Lookup object`, the name (extracted from the `CONSTANT_NameAndType` entry), and the type (also extracted from the `CONSTANT_NameAndType` entry). The `invokedynamic` instruction may specify additional metadata values to pass to its bootstrap method. Collectively, these values are called static arguments to the `invokedynamic` instruction, because they are used once at link time to determine the instruction's behavior on subsequent sets of dynamic arguments.

Static arguments are used to communicate application-specific meta-data to the bootstrap method. Drawn from the constant pool, they may include references to classes, method handles, strings, or numeric data that may be relevant to the task of linking that particular call site.

Static arguments are specified constant pool indexes stored in the `BootstrapMethods` attribute. Before the bootstrap method is invoked, each index is used to compute an `Object` reference to the indexed value in the constant pool. The valid constant pool entries are listed in this table: ``

entry type | argument type | argument value
--- | --- | ---
CONSTANT_String | `java.lang.String` | the indexed string literal
CONSTANT_Class | `java.lang.Class` | the indexed class, resolved
CONSTANT_Integer | `java.lang.Integer` | the indexed int value
CONSTANT_Long | `java.lang.Long` | the indexed long value
CONSTANT_Float | `java.lang.Float` | the indexed float value
CONSTANT_Double | `java.lang.Double` | the indexed double value
CONSTANT_MethodHandle | `java.lang.invoke.MethodHandle` | the indexed method handle constant
CONSTANT_MethodType | `java.lang.invoke.MethodType` | the indexed method type constant

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 252 extra arguments can be supplied.) The bootstrap method will be invoked as if by either `invokeGeneric` or `invokeWithArguments`. (There is no way to tell the difference.)

The normal argument conversion rules for `invokeGeneric` 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 `java.lang.invoke.MethodHandle#asVarargsCollector 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)`

The last example assumes that the extra arguments are of type `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 `invokeGeneric` call will pass the extra method handle constant as an `Object`, but the type matching machinery of `invokeGeneric` 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`.)

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.

## Structure Summary

>     // summary of constant and attribute structures
>     struct CONSTANT_MethodHandle_info {
>       u1 tag = 15;
>       u1 reference_kind;       // 1..8 (one of REF_invokeVirtual, etc.)
>       u2 reference_index;      // index to CONSTANT_Fieldref or *Methodref
>     }
>     struct CONSTANT_MethodType_info {
>       u1 tag = 16;
>       u2 descriptor_index;    // index to CONSTANT_Utf8, as in NameAndType
>     }
>     struct CONSTANT_InvokeDynamic_info {
>       u1 tag = 18;
>       u2 bootstrap_method_attr_index;  // index into BootstrapMethods_attr
>       u2 name_and_type_index;          // index to CONSTANT_NameAndType, as in Methodref
>     }
>     struct BootstrapMethods_attr {
>      u2 name;  // CONSTANT_Utf8 = "BootstrapMethods"
>      u4 size;
>      u2 bootstrap_method_count;
>      struct bootstrap_method_specifier {
>        u2 bootstrap_method_ref;  // index to CONSTANT_MethodHandle
>        u2 bootstrap_argument_count;
>        u2 bootstrap_arguments[bootstrap_argument_count];  // constant pool indexes
>      } bootstrap_methods[bootstrap_method_count];
>     }

Since:
  1.7

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.
DRAFT ea-b139