Spec-Zone .ru спецификации, руководства, описания, API

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.dyn

PROVISIONAL API, WORK IN PROGRESS: This package contains dynamic language support provided directly by the Java core class libraries and virtual machine.

See:
Description

Interface Summary

Interface	Description
MethodHandleProvider	An interface for an object to provide a target method handle to a invokedynamic instruction.

Class Summary

Class	Description
CallSite	A CallSite is a holder for a variable MethodHandle, which is called its target.
ClassValue<T>	Lazily associate a computed value with (potentially) every class.
ConstantCallSite	A ConstantCallSite is a CallSite whose target is permanent, and can never be changed.
InvokeDynamic	InvokeDynamic is a class with neither methods nor instances, which serves only as a syntactic marker in Java source code for an invokedynamic instruction.
Linkage	This class consists exclusively of static methods that control the linkage of invokedynamic instructions, and specifically their reification as CallSite objects.
LinkagePermission	PROVISIONAL API, WORK IN PROGRESS: This class is for managing runtime permission checking for operations performed by methods in the Linkage class.
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.

Exception Summary

Exception	Description
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.

Error Summary

Error	Description
InvokeDynamicBootstrapError	Thrown to indicate that an invokedynamic instruction has failed to find its bootstrap method, or the bootstrap method has failed to provide a CallSite call site with a non-null target of the correct method type.

Annotation Types Summary

Annotation Type	Description
BootstrapMethod	Annotation on InvokeDynamic method calls which requests the JVM to use a specific bootstrap method to link the call.

Package java.dyn Description

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:

• In source code, a call to MethodHandle.invokeExact or MethodHandle.invokeGeneric will compile and link, regardless of the requested type signature. As usual, the Java compiler emits an invokevirtual instruction 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.
• In source code, the class InvokeDynamic appears to accept any static method invocation, of any name and any signature. But instead of emitting an invokestatic instruction for such a call, the Java compiler emits an invokedynamic instruction with the given name and signature.
• 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.

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 17). See below for its format. The entry specifies the bootstrap method (a MethodHandle constant), 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 CONSTANT_InvokeDynamic entry. 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 of 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 CONSTANT_NameAndType 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 pool entries for invokedynamic instructions

If a constant pool entry has the tag 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_MethodHandle entry, 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_Class reference in a CONSTANT_Methodref entry is replaced by a bootstrap method reference.

constant pool entries for MethodTypes

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 signature.

The JVM will ensure that on first execution of an ldc instruction for this entry, a MethodType 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 references by ldc instructions to CONSTANT_Class constants.

constant pool entries for MethodHandles

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 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 <init> and <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 REF_getStatic, REF_putStatic, and REF_invokeStatic may force class initialization on their first invocation, just like the corresponding bytecodes.

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 signature, 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 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:

• a MethodHandle, the resolved bootstrap method itself
• a Class, the caller class in which dynamic call site occurs
• a String, the method name mentioned in the call site
• a MethodType, the resolved type signature of the call

The method handle is then applied to the other values as if by the invokeGeneric method. The returned result must be a CallSite, a MethodHandle, or another MethodHandleProvider value. The method asMethodHandle is then called on the returned value. The result of that second call is the MethodHandle which 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 InvokeDynamicBootstrapError, which is thrown as the abnormal termination of the dynamic call site execution. The following circumstances will cause this:

• the bootstrap method invocation completes abnormally
• the result from the bootstrap invocation is not a reference to an object of type MethodHandleProvider
• the call to asMethodHandle completes abnormally
• the call to asMethodHandle fails to return a reference to an object of type MethodHandle
• the method handle produced by asMethodHandle does not have 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 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, such as Linkage.invalidateCallerClass.

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 invokedynamic instructions is invalidated, subsequent execution of those invokedynamic instructions 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 invokedynamic 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 of invokedynamic bytecodes in class files and linkage events.

In principle, each individual execution of an invokedynamic 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.