Standard Ed. 7
|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|
|MethodHandleProvider||An interface for an object to provide a target method handle to a
|ClassValue<T>||Lazily associate a computed value with (potentially) every class.|
|Linkage||This class consists exclusively of static methods that control
the linkage of
|LinkagePermission||PROVISIONAL API, WORK IN PROGRESS:
This class is for managing runtime permission checking for
operations performed by methods in the
|MethodHandle||A method handle is a typed, directly executable reference to a 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.|
|NoAccessException||Thrown to indicate that a caller has attempted to create a method handle which accesses a field, method, or class to which the caller does not have access.|
|WrongMethodTypeException||Thrown to indicate that code has attempted to call a method handle via the wrong method type.|
|InvokeDynamicBootstrapError||Thrown to indicate that an
|BootstrapMethod||Annotation on InvokeDynamic method calls which requests the JVM to use a specific bootstrap method to link the call.|
PROVISIONAL API, WORK IN PROGRESS: This 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:
MethodHandle.invokeGenericwill compile and link, regardless of the requested type signature. As usual, the Java compiler emits an
invokevirtualinstruction with the given signature against the named method. The JVM links any such call (regardless of signature) to a dynamically typed method handle invocation. In the case of
invokeGeneric, argument and return value conversions are applied.
InvokeDynamicappears to accept any static method invocation, of any name and any signature. But instead of emitting an
invokestaticinstruction for such a call, the Java compiler emits an
invokedynamicinstruction with the given name and signature.
invokedynamicinstruction 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
invokeinstructions). The final two bytes are reserved for future use and required to be zero. The constant pool reference of an
invokedynamicinstruction is to a entry with tag
CONSTANT_InvokeDynamic(decimal 17). See below for its format. The entry specifies the bootstrap method (a
MethodHandleconstant), the dynamic invocation name, and the argument types and return type of the call.
Each instance of an
invokedynamic instruction is called a dynamic call site.
Multiple instances of an
invokedynamic instruction can share a single
In any case, distinct call sites always have distinct linkage state.
Moreover, for the purpose of distinguishing dynamic call sites,
the JVM is allowed (but not required) to make internal copies
invokedynamic instructions, each one
constituting a separate dynamic call site with its own linkage state.
Such copying, if it occurs, cannot be observed except indirectly via
execution of bootstrap methods and target methods.
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.
(Historic Note: Some older JVMs may allow the index of a
instead of a
CONSTANT_InvokeDynamic. In earlier, obsolete versions of this API, the
bootstrap method was specified dynamically, in a per-class basis, during class initialization.)
CONSTANT_InvokeDynamic(decimal 17), it must contain exactly four more bytes. The first two bytes after the tag must be an index to a
CONSTANT_MethodHandleentry, and the second two 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
CONSTANT_Classreference in a
CONSTANT_Methodrefentry is replaced by a bootstrap method reference.
CONSTANT_MethodType(decimal 16), it must contain exactly two more bytes, which must be an index to a
CONSTANT_Utf8entry which represents a method type signature.
The JVM will ensure that on first
execution of an
ldc instruction for this entry, a
will be created which represents the signature.
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
ldc instructions to
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_InterfaceMethodrefentry 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
for this entry, a
MethodHandle will be created which represents
the field or method reference, according to the specific mode implied by the subtag.
MethodType object which reifies the field or method's
type is created. Any classes mentioned in this reificaiton will be loaded if necessary,
but not initialized, and access checking and error reporting performed as usual.
The method handle itself will have a type and behavior determined by the subtag as follows:
N subtag name member MH type MH behavior 1 REF_getField C.f:T (C)T getfield C.f:T 2 REF_getStatic C.f:T ( )T getstatic C.f:T 3 REF_putField C.f:T (C,T)void putfield C.f:T 4 REF_putStatic C.f:T (T)void putstatic C.f:T 5 REF_invokeVirtual C.m(A*)T (C,A*)T invokevirtual C.m(A*)T 6 REF_invokeStatic C.m(A*)T (C,A*)T invokestatic C.m(A*)T 7 REF_invokeSpecial C.m(A*)T (C,A*)T invokespecial C.m(A*)T 8 REF_newInvokeSpecial C.<init>(A*)void (A*)C new C; dup; invokespecial C.<init>(A*)void 9 REF_invokeInterface C.m(A*)T (C,A*)T invokeinterface C.m(A*)T
The special names
<clinit> are not allowed except for subtag 8 as shown.
The verifier applies the same access checks and restrictions for these references as for the hypothetical bytecode instructions specified in the last column of the table. In particular, method handles to private and protected members can be created in exactly those classes for which the corresponding normal accesses are legal.
None of these constant types force class initialization.
Method handles for subtags
may force class initialization on their first invocation, just like the corresponding bytecodes.
invokedynamicinstruction), 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 handlethat 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 signature,
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 signature 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 four values being stacked:
MethodHandle, the resolved bootstrap method itself
Class, the caller class in which dynamic call site occurs
String, the method name mentioned in the call site
MethodType, the resolved type signature of the call
invokeGenericmethod. The returned result must be a
MethodHandle, or another
MethodHandleProvidervalue. The method asMethodHandle is then called on the returned value. The result of that second call is the
MethodHandlewhich becomes the permanent binding for the dynamic call site. That method handle's type must be exactly equal to the type derived from the dynamic call site signature and passed to the bootstrap method.
After resolution, the linkage process may fail in a variety of ways.
All failures are reported by an
which is thrown as the abnormal termination of the dynamic call
The following circumstances will cause this:
asMethodHandlefails to return a reference to an object of type
asMethodHandledoes not have the expected
If there are several such threads, the JVM picks one thread and runs the bootstrap method while the others wait for the invocation to terminate normally or abnormally.
After a bootstrap method is called and a method handle target successfully extracted, the JVM attempts to link the instruction being executed to the target method handle. This may fail if there has been intervening linkage or invalidation event for the same instruction. If such a failure occurs, the dynamic call site must be re-executed from the beginning, either re-linking it (if it has been invalidated) or invoking the target (if it the instruction has been linked by some other means).
If the instruction is linked successfully, the target method
handle is invoked to complete the instruction execution.
The state of linkage continues until the method containing the
dynamic call site is garbage collected, or the dynamic call site
is invalidated by an explicit request,
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.
If a class containing
subsequent execution of those
will require linking.
It is as if they had never been executed in the first place.
(However, invalidation does not cause constant pool entries to be
resolved a second time.)
Invalidation events and bootstrap method calls for a particular dynamic call site are globally ordered relative to each other. When an invokedynamic instruction is invalidated, if there is simultaneously a bootstrap method invocation in process (in the same thread or a different thread), the result eventually returned must not be used to link the call site. Put another way, when a call site is invalidated, its subsequent linkage (if any) must be performed by a bootstrap method call initiated after the invalidation occurred.
If several threads simultaneously execute a bootstrap method for a single dynamic call site, the JVM must choose one target object and installs 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.
The JVM is free to duplicate dynamic call sites.
This means that, even if a class contains just one
instruction, its bootstrap method may be executed several times,
once for each duplicate. Thus, bootstrap method code should not
assume an exclusive one-to-one correspondence between particular occurrences
invokedynamic bytecodes in class files and linkage events.
In principle, each individual execution of an
instruction could be deemed (by a conforming implementation) to be a separate
duplicate, requiring its own execution of the bootstrap method.
However, implementations are expected to perform code duplication
(if at all) in order to improve performance, not make it worse.
Standard Ed. 7
|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|
Copyright © 1993, 2010, Oracle Corporation. All rights reserved.