Specification for JEP 309: Dynamic Class-File Constants

This document proposes changes to the Java Virtual Machine Specification to introduce a new constant pool form, CONSTANT_Dynamic. See JEP 309 for an overview.

4.4 The Constant Pool

Java Virtual Machine instructions do not rely on the run-time layout of classes, interfaces, class instances, or arrays. Instead, instructions refer to symbolic information in the constant_pool table.

All constant_pool table entries have the following general format:

cp_info {
    u1 tag;
    u1 info[];
}

Each entry in the constant_pool table must begin with a 1-byte tag indicating the type of constant denoted by the entry. The constant types and their corresponding tag values are listed in Table 4.4-A. Each constant type is accompanied by the first version of the class file format in which it was defined, and the corresponding version of the Java SE Platform. (For old class file versions, the JDK release is used instead of the Java SE Platform version.)

In a class file of version V, each item in the constant_pool table must have a tag that was first defined in version V or before.

Each tag byte must be followed by two or more bytes giving information about the specific constant. The format of the additional information depends on the tag byte, that is, the content of the info array varies with the value of tag.

A loadable constant structure is an entry in the constant_pool table that represents a primitive or reference value, or that represents a symbolic reference that can be resolved to a primitive or reference value (5.1).

Some tags in Table 4.4-A are accompanied by the first version of the class file format in which the type was considered loadable. In a class file of version V, an entry in the constant_pool table represents a loadable constant structure if and only if it has a tag that was first considered loadable in version V or before.

Table 4.4-A. Constant pool tags

4.4.10 The CONSTANT_InvokeDynamic_info Structure

The CONSTANT_InvokeDynamic_info structure is used by an invokedynamic instruction (invokedynamic) to specify a bootstrap method, the dynamic invocation name, the argument and return types of the call, and optionally, a sequence of additional constants called static arguments to the bootstrap method.

The CONSTANT_InvokeDynamic_info structure is used to describe a dynamically-computed call site, a java.lang.invoke.CallSite object produced by invocation of a bootstrap method (4.7.23) for use by the invokedynamic instruction (invokedynamic). The structure specifies i) a bootstrap method handle with an optional sequence of static arguments and ii) a referenced name and type, where the type represents the method type of the java.lang.invoke.CallSite.

CONSTANT_InvokeDynamic_info {
   u1 tag;
   u2 bootstrap_method_attr_index;
   u2 name_and_type_index;
}

The items of the CONSTANT_InvokeDynamic_info structure are as follows:

tag

The tag item of the CONSTANT_InvokeDynamic_info structure has the value CONSTANT_InvokeDynamic (18).

bootstrap_method_attr_index

The value of the bootstrap_method_attr_index item must be a valid index into the bootstrap_methods array of the bootstrap method table (4.7.23) of this class file.

name_and_type_index

The value of the name_and_type_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_NameAndType_info structure (4.4.6) representing a method name and method descriptor (4.3.3).

4.4.13 The CONSTANT_Dynamic_info Structure

The CONSTANT_Dynamic_info structure is used to describe a dynamically-computed constant, an arbitrary primitive or reference value produced by invocation of a bootstrap method (4.7.23). The structure specifies i) a bootstrap method handle with an optional sequence of static arguments and ii) a referenced name and type.

CONSTANT_Dynamic_info {
   u1 tag;
   u2 bootstrap_method_attr_index;
   u2 name_and_type_index;
}

The items of the CONSTANT_Dynamic_info structure are as follows:

tag

The tag item of the CONSTANT_Dynamic_info structure has the value CONSTANT_Dynamic (17).

bootstrap_method_attr_index

The value of the bootstrap_method_attr_index item must be a valid index into the bootstrap_methods array of the bootstrap method table (4.7.23) of this class file.

name_and_type_index

The value of the name_and_type_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_NameAndType_info structure (4.4.6) representing a name and field descriptor (4.3.2).

4.7.23 The BootstrapMethods Attribute

The BootstrapMethods attribute is a variable-length attribute in the attributes table of a ClassFile structure (4.1). The BootstrapMethods attribute records bootstrap method specifiers referenced by invokedynamic instructions (invokedynamic) used to produce dynamically-computed call sites (4.4.10) and dynamically-computed constants (4.4.13).

There must be exactly one BootstrapMethods attribute in the attributes table of a ClassFile structure if the constant_pool table of the ClassFile structure has at least one CONSTANT_InvokeDynamic_info or CONSTANT_Dynamic_info entry (4.4.10).

There may be at most one BootstrapMethods attribute in the attributes table of a ClassFile structure.

The BootstrapMethods attribute has the following format:

BootstrapMethods_attribute { 
    u2 attribute_name_index;
    u4 attribute_length;
    u2 num_bootstrap_methods;
    {   u2 bootstrap_method_ref;
        u2 num_bootstrap_arguments;
        u2 bootstrap_arguments[num_bootstrap_arguments];
    } bootstrap_methods[num_bootstrap_methods];
}

attribute_name_index

The value of the attribute_name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing the string "BootstrapMethods".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

The value of the attribute_length item is thus dependent on the number of invokedynamic instructions in this ClassFile structure.

This assertion is false—invokedynamic instructions can share bootstrap methods—and not particularly useful.

num_bootstrap_methods

The value of the num_bootstrap_methods item determines the number of bootstrap method specifiers in the bootstrap_methods array.

bootstrap_methods[]

Each entry in the bootstrap_methods table contains an index to a CONSTANT_MethodHandle_info structure (4.4.8) which specifies a bootstrap method, and a sequence (perhaps empty) of indexes to static arguments for the bootstrap method.

Each bootstrap_methods entry must contain the following three items:

bootstrap_method_ref

The value of the bootstrap_method_ref item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_MethodHandle_info structure (4.4.8).

The form of the method handle is driven by the continuing resolution of the call site specifier in invokedynamic resolution of constant pool entries, where execution of invoke in java.lang.invoke.MethodHandle requires that the bootstrap method handle be adjustable to the actual arguments being passed, as if by a call to java.lang.invoke.MethodHandle.asType. Accordingly, the reference_kind item of the CONSTANT_MethodHandle_info structure should have the value 6 or 8 (5.4.3.5), and the reference_index item should specify a static method or constructor that takes three arguments of type java.lang.invoke.MethodHandles.Lookup, String, and java.lang.invoke.MethodType, in that order. Otherwise, invocation of the bootstrap method handle during call site specifier resolution will complete abruptly.

During resolution of a dynamically-computed call site or dynamically-computed constant (5.4.3.6), the method handle will be resolved (5.4.3.5) and invoked, as if by invocation of java.lang.invoke.MethodHandle.invokeWithArguments. The method handle must be able to accept the array of arguments, as described in 5.4.3.6, or resolution will fail.

num_bootstrap_arguments

The value of the num_bootstrap_arguments item gives the number of items in the bootstrap_arguments array.

bootstrap_arguments[]

Each entry in the bootstrap_arguments array must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_String_info, CONSTANT_Class_info, CONSTANT_Integer_info, CONSTANT_Float_info, CONSTANT_MethodHandle_info, or CONSTANT_MethodType_info structure (4.4.3, 4.4.1, 4.4.4, 4.4.5, 4.4.8, 4.4.9) loadable constant structure (4.4).

4.10.1.3 Instruction Representation

Individual bytecode instructions are represented in Prolog as terms whose functor is the name of the instruction and whose arguments are its parsed operands.

For example, an aload instruction is represented as the term aload(N), which includes the index N that is the operand of the instruction.

The instructions as a whole are represented as a list of terms of the form:

instruction(Offset, AnInstruction)

For example, instruction(21, aload(1)).

The order of instructions in this list must be the same as in the class file.

A few instructions have operands that are constant pool entries representing fields, methods, and dynamic call sites, and dynamic constants. In the constant pool, a field is represented by a CONSTANT_Fieldref_info structure, a method is represented by a CONSTANT_InterfaceMethodref_info structure (for an interface's method) or a CONSTANT_Methodref_info structure (for a class's method), and a dynamic call site is represented by a CONSTANT_InvokeDynamic_info structure (4.4.2, 4.4.10). Such structures These are represented as functor applications of the form:

• classConst(ClassName) for a CONSTANT_Class_info, where ClassName is the name of the class or interface referenced by the name_index item in the CONSTANT_Class_info structure;

• field(FieldClassName, FieldName, FieldDescriptor) for a field CONSTANT_Fieldref_info, where FieldClassName is the name of the class referenced by the class_index item in the CONSTANT_Fieldref_info structure, and FieldName and FieldDescriptor correspond to the name and field descriptor referenced by the name_and_type_index item of the CONSTANT_Fieldref_info structure;

• imethod(MethodIntfName, MethodName, MethodDescriptor) for an interface's method a CONSTANT_InterfaceMethodref_info, where MethodIntfName is the name of the interface referenced by the class_index item of the CONSTANT_InterfaceMethodref_info structure, and MethodName and MethodDescriptor correspond to the name and method descriptor referenced by the name_and_type_index item of the CONSTANT_InterfaceMethodref_info structure;

• method(MethodClassName, MethodName, MethodDescriptor) for a class's method CONSTANT_Methodref_info, where MethodClassName is the name of the class referenced by the class_index item of the CONSTANT_Methodref_info structure, and MethodName and MethodDescriptor correspond to the name and method descriptor referenced by the name_and_type_index item of the CONSTANT_Methodref_info structure; and

• string(Value) for a CONSTANT_String_info, where Value is the string referenced by the string_index item of the CONSTANT_String_info structure;

• int(Value) for a CONSTANT_Integer_info, where Value is the integer represented by the bytes item of the CONSTANT_Integer_info structure;

• float(Value) for a CONSTANT_Float_info, where Value is the floating-point number represented by the bytes item of the CONSTANT_Float_info structure;

• long(Value) for a CONSTANT_Long_info, where Value is the integer represented by the high_bytes and low_bytes items of the CONSTANT_Long_info structure;

• double(Value) for a CONSTANT_Double_info, where Value is the floating-point number represented by the high_bytes and low_bytes items of the CONSTANT_Double_info structure;

• methodHandle(Kind, Reference) for a CONSTANT_MethodHandle_info, where Kind is the value of the reference_kind item of the CONSTANT_MethodHandle_info structure, and Reference is the member reference referenced by the reference_index item of the CONSTANT_MethodHandle_info structure;

• methodType(MethodDescriptor) for a CONSTANT_MethodType_info, where MethodDescriptor is the method descriptor referenced by the descriptor_index item of the CONSTANT_MethodType_info structure;

• dmethod(CallSiteName, MethodDescriptor) for a dynamic call site CONSTANT_InvokeDynamic_info, where CallSiteName and MethodDescriptor correspond to the name and method descriptor referenced by the name_and_type_index item of the CONSTANT_InvokeDynamic_info structure (the bootstrap_method_attr_index item is irrelevant to verification).

• dynamic(ConstantName, FieldDescriptor) for a CONSTANT_Dynamic_info, where ConstantName and FieldDescriptor correspond to the name and field descriptor referenced by the name_and_type_index item of the CONSTANT_Dynamic_info structure (the bootstrap_method_attr_index item is irrelevant to verification);

For clarity, we assume that field and method descriptors (4.3.2, 4.3.3) are mapped into more readable names: the leading L and trailing ; are dropped from class names, and the BaseType characters used for primitive types are mapped to the names of those types.

For example, a getfield instruction whose operand was an index into the constant pool that refers to a field foo of type F in class Bar would be represented as getfield(field('Bar', 'foo', 'F')).

Constant pool entries that refer to constant values, such as CONSTANT_String, CONSTANT_Integer, CONSTANT_Float, CONSTANT_Long, CONSTANT_Double, and CONSTANT_Class, are encoded via the functors whose names are string, int, float, long, double, and classConstant respectively.

For example, an An ldc instruction for loading the integer 91 would be encoded as ldc(int(91)).

4.10.1.9 Type Checking Instructions

...

ldc, ldc_w, ldc2_w

An ldc instruction with operand CP is type safe iff CP refers to a loadable constant pool entry denoting an entity of type Type, where Type is either int, float, String, Class, java.lang.invoke.MethodType, or java.lang.invoke.MethodHandle not long or double, and one can validly push Type onto the incoming operand stack yielding the outgoing type state.

instructionIsTypeSafe(ldc(CP), Environment, _Offset, StackFrame, NextStackFrame, ExceptionStackFrame) :-

functor(CP, Tag, _),
isBootstrapLoader(BL),
member([Tag, Type], [
[int, int],
[float, float],
[string, class('java/lang/String', BL)],
[classConst, class('java/lang/Class', BL)],
[methodTypeConst, class('java/lang/invoke/MethodType', BL)],
[methodHandleConst, class('java/lang/invoke/MethodHandle', BL)]
]),
loadableConstantType(CP, Type),
Type \= long,
Type \= double,
validTypeTransition(Environment, [], Type, StackFrame, NextStackFrame),
exceptionStackFrame(StackFrame, ExceptionStackFrame).

loadableConstantType(CP, Type) :-

functor(CP, Tag, _),
isBootstrapLoader(BL),
member([Tag, Type], [
[int, int],
[float, float],
[long, long],
[double, double],
[string, class('java/lang/String', BL)],
[classConst, class('java/lang/Class', BL)],
[methodType, class('java/lang/invoke/MethodType', BL)],
[methodHandle, class('java/lang/invoke/MethodHandle', BL)]
]).

loadableConstantType(CP, Type) :-

CP = dynamic(ConstantName, FieldDescriptor),
parseFieldDescriptor(FieldDescriptor, Type).

An ldc_w instruction is type safe iff the equivalent ldc instruction is type safe.

instructionHasEquivalentTypeRule(ldc_w(CP), ldc(CP)).

An ldc2_w instruction with operand CP is type safe iff CP refers to a loadable constant pool entry denoting an entity of type Tag Type, where Tag Type is either long or double, and one can validly push Tag Type onto the incoming operand stack yielding the outgoing type state.

instructionIsTypeSafe(ldc2_w(CP), Environment, _Offset, StackFrame, NextStackFrame, ExceptionStackFrame) :-

functor(CP, Tag, _),
member(Tag, [ long, double ]),
loadableConstantType(CP, Type),
(Type = long; Type = double),
validTypeTransition(Environment, [], Tag Type, StackFrame, NextStackFrame),
exceptionStackFrame(StackFrame, ExceptionStackFrame).

5.1 The Run-Time Constant Pool

The Java Virtual Machine maintains a per-type constant pool (2.5.5), a run-time data structure that serves many of the purposes of the symbol table of a conventional programming language implementation.

The constant_pool table (4.4) in the binary representation of a class or interface is used to construct the run-time constant pool upon class or interface creation (5.3). All references in the run-time constant pool are initially symbolic. The symbolic references in the run-time constant pool are derived from structures in the binary representation of the class or interface as follows:

• A symbolic reference to a class or interface is derived from a CONSTANT_Class_info structure (4.4.1) in the binary representation of a class or interface. Such a reference gives the name of the class or interface in the form returned by the Class.getName method, that is:

  • For a nonarray class or an interface, the name is the binary name (4.2.1) of the class or interface.

  • For an array class of n dimensions, the name begins with n occurrences of the ASCII "[" character followed by a representation of the element type:

    • If the element type is a primitive type, it is represented by the corresponding field descriptor (4.3.2).
    • Otherwise, if the element type is a reference type, it is represented by the ASCII "L" character followed by the binary name (4.2.1) of the element type followed by the ASCII ";" character.

  Whenever this chapter refers to the name of a class or interface, it should be understood to be in the form returned by the Class.getName method.

• A symbolic reference to a field of a class or an interface is derived from a CONSTANT_Fieldref_info structure (4.4.2) in the binary representation of a class or interface. Such a reference gives the name and descriptor of the field, as well as a symbolic reference to the class or interface in which the field is to be found.

• A symbolic reference to a method of a class is derived from a CONSTANT_Methodref_info structure (4.4.2) in the binary representation of a class or interface. Such a reference gives the name and descriptor of the method, as well as a symbolic reference to the class in which the method is to be found.

• A symbolic reference to a method of an interface is derived from a CONSTANT_InterfaceMethodref_info structure (4.4.2) in the binary representation of a class or interface. Such a reference gives the name and descriptor of the interface method, as well as a symbolic reference to the interface in which the method is to be found.

• A symbolic reference to a method handle is derived from a CONSTANT_MethodHandle_info structure (4.4.8) in the binary representation of a class or interface. Such a reference gives a symbolic reference to a field of a class or interface, or a method of a class, or a method of an interface, depending on the kind of the method handle.

• A symbolic reference to a method type is derived from a CONSTANT_MethodType_info structure (4.4.9) in the binary representation of a class or interface. Such a reference gives a method descriptor (4.3.3).

• A symbolic reference to a dynamically-computed call site specifier is derived from a CONSTANT_InvokeDynamic_info structure (4.4.10) in the binary representation of a class or interface. Such a reference gives:

  • a symbolic reference to a method handle, which will serve as a bootstrap method for an invokedynamic instruction (invokedynamic) be used to produce a java.lang.invoke.CallSite;
  • a sequence of symbolic references (to classes, method types, and method handles), string literals, and run-time constant values which will serve as static arguments to a bootstrap method the method handle;
  • a method name and method descriptor.

• A symbolic reference to a dynamically-computed constant is derived from a CONSTANT_Dynamic_info structure (4.4.13) in the binary representation of a class or interface. Such a reference gives:

  • a symbolic reference to a method handle, which will be used to produce a value;
  • a sequence of symbolic references and run-time constant values which will serve as static arguments to the method handle;
  • a name and field descriptor.

In addition, certain run-time constant values which are not symbolic references are derived from items found in the constant_pool table:

• A string literal constant value is a reference to an instance of class String, and is derived from a CONSTANT_String_info structure (4.4.3) in the binary representation of a class or interface. The CONSTANT_String_info structure gives the sequence of Unicode code points constituting the string literal constant value.

  The Java programming language requires that identical string literals (that is, literals that contain the same sequence of code points) must refer to the same instance of class String (JLS 3.10.5). In addition, if the method String.intern is called on any string, the result is a reference to the same class instance that would be returned if that string appeared as a literal. Thus, the following expression must have the value true:

  ("a" + "b" + "c").intern() == "abc"

  The above comment is merely informative: it should not be typeset as part of the normative spec.

  To derive a string literal constant value, the Java Virtual Machine examines the sequence of code points given by the CONSTANT_String_info structure.

  • If the method String.intern has previously been called on an instance of class String containing a sequence of Unicode code points identical to that given by the CONSTANT_String_info structure, then the result of string literal derivation string constant value is a reference to that same instance of class String.

  • Otherwise, a new instance of class String is created containing the sequence of Unicode code points given by the CONSTANT_String_info structure; a reference to that class instance is the result of string literal derivation string constant value. Finally, the intern method of the new String instance is invoked.

• Run-time numeric constant values are derived from CONSTANT_Integer_info, CONSTANT_Float_info, CONSTANT_Long_info, or CONSTANT_Double_info structures (4.4.4, 4.4.5) in the binary representation of a class or interface.

  Note that CONSTANT_Float_info structures represent values in IEEE 754 single format and CONSTANT_Double_info structures represent values in IEEE 754 double format (4.4.4, 4.4.5). The run-time constant values derived from these structures must thus be values that can be represented using IEEE 754 single and double formats, respectively.

The remaining structures in the constant_pool table of the binary representation of a class or interface—the CONSTANT_NameAndType_info and CONSTANT_Utf8_info structures (4.4.6, 4.4.7)—are only used indirectly when deriving symbolic references to classes, interfaces, methods, fields, method types, and method handles, and when deriving string literals and call site specifiers constructing the run-time constant pool.

The CONSTANT_Module_info and CONSTANT_Package_info structures do not appear at all in the constant_pool table of the binary representation of a class or interface, so are not relevant to this discussion.

An entry in the run-time constant pool represents a loadable constant if it is derived from a loadable constant structure (4.4).

Loadable constants can be pushed onto the operand stack by the ldc, ldc_w, and ldc2_w instructions. They can also act as static arguments to a bootstrap method during resolution of dynamically-computed constants and dynamically-computed call sites (5.4.3.6).

5.4 Linking

Linking a class or interface involves verifying and preparing that class or interface, its direct superclass, its direct superinterfaces, and its element type (if it is an array type), if necessary. Resolution of symbolic references in the class or interface is an optional part of linking. Linking also includes resolution of symbolic references in the class or interface.

This specification allows an implementation flexibility as to when linking activities (and, because of recursion, loading) take place, provided that all of the following properties are maintained:

• A class or interface is completely loaded before it is linked.

• A class or interface is completely verified and prepared before it is initialized.

• Errors detected during linkage are thrown at a point in the program where some action is taken by the program that might, directly or indirectly, require linkage to the class or interface involved in the error. (These errors will always be instances of Error or one of its subclasses.)

• A symbolic reference to a dynamically-computed constant or call site is never resolved until the first time a referencing ldc, ldc_w, ldc2_w, or invokedynamic instruction is executed, or the first time a referencing bootstrap method is invoked.

  For example, a Java Virtual Machine implementation may choose to resolve each symbolic reference in a class or interface individually when it is used ("lazy" or "late" resolution), or to resolve them all at once when the class is being verified ("eager" or "static" resolution). This means that the resolution process may continue, in some implementations, after a class or interface has been initialized. Whichever strategy is followed, any error detected during resolution must be thrown at a point in the program that (directly or indirectly) uses a symbolic reference to the class or interface.

Because linking involves the allocation of new data structures, it may fail with an OutOfMemoryError.

5.4.3 Resolution

The Java Virtual Machine instructions anewarray, checkcast, getfield, getstatic, instanceof, invokedynamic, invokeinterface, invokespecial, invokestatic, invokevirtual, ldc, ldc_w, ldc2_w, multianewarray, new, putfield, and putstatic make symbolic references to the run-time constant pool (5.4). Execution of any of these instructions requires resolution of its symbolic reference.

Resolution is the process of dynamically determining concrete values from symbolic references in the run-time constant pool.

Resolution of the symbolic reference of one occurrence of an invokedynamic instruction does not imply that the same symbolic reference is considered resolved for any other invokedynamic instruction.

For all other instructions above, resolution of the symbolic reference of one occurrence of an instruction does imply that the same symbolic reference is considered resolved for any other non-invokedynamic instruction.

(The above text implies that the concrete value determined by resolution for a specific invokedynamic instruction is a call site object bound to that specific invokedynamic instruction.)

Resolution can be attempted on a symbolic reference that has already been resolved. An attempt to resolve a symbolic reference that has already successfully been resolved always succeeds trivially and always results in the same entity produced by the initial resolution of that reference.

If an error occurs during resolution of a symbolic reference, then an instance of IncompatibleClassChangeError (or a subclass) must be thrown at a point in the program that (directly or indirectly) uses the symbolic reference.

If an attempt by the Java Virtual Machine to resolve a symbolic reference fails because an error is thrown that is an instance of LinkageError (or a subclass), then subsequent attempts to resolve the reference always fail with the same error that was thrown as a result of the initial resolution attempt.

Resolution of a symbolic reference proceeds as follows:

• If no previous attempt to resolve the symbolic reference has been made, or if the symbolic reference is to a dynamically-computed call site and no previous attempt to resolve the symbolic reference has been made for the specific invokedynamic instruction that triggered resolution, the process described in the following sections is followed for the type of symbolic reference being resolved. This results in either a value or a thrown exception (specifically, a thrown instance of Error or a subclass of Error).

  Upon completion, if another resolution result has been produced since this attempt at resolution began, the result of this attempt is discarded, replaced with the other result.

  Another resolution result may have been produced by another thread, or by a nested resolution operation occurring in the same thread. In such cases, different resolution attempts must not produce different results.

  For example, in one thread resolution of a symbolic reference to a class may result in a Class object, while, at the same time, resolution in another thread fails with a NoClassDefFoundError. The Java Virtual Machine may choose either result, but must have the same result in both threads.

  This rule was previously stated for invokedynamic, but it is applicable generally. The previous rule failed to address the possibility of nested resolution occurring in a single thread.

• Otherwise, resolution trivially produces the result of the previous attempt, either a value or a thrown exception.

  In the case of a symbolic reference to a dynamically-computed call site, "the previous attempt" refers to the previous attempt for the specific invokedynamic instruction that triggered resolution.

  When the result of a previous attempt is used, the bootstrap method of a dynamically-computed constant or call site is not re-executed.

  This means, Because errors occuring on an initial attempt at resolution are thrown again on subsequent attempts, this means, for example, that a class in one module that attempts to access, via resolution of a symbolic reference in its run-time constant pool, an unexported public type in a different module will always receive the same error indicating an inaccessible type (5.4.4), even if the Java SE Platform API is used to dynamically export the public type's package at some time after the class's first attempt.

• Certain of the instructions above require additional linking checks when resolving symbolic references. Any such checks are performed, possibly resulting in an exception.

  For instance, in order for a getfield instruction to successfully resolve the symbolic reference to the field on which it operates, it must not only complete the field resolution steps given in 5.4.3.2 but also check that the field is not static. If it is a static field, a linking exception must be thrown.

• If any exception was thrown in the previous steps, resolution fails with this exception. Otherwise, resolution returns the resolved value.

A symbolic reference to a call site specifier by a specific invokedynamic instruction must not be resolved prior to execution of that instruction.

In the case of failed resolution of an invokedynamic instruction, the bootstrap method is not re-executed on subsequent resolution attempts.

Certain of the instructions above require additional linking checks when resolving symbolic references. For instance, in order for a getfield instruction to successfully resolve the symbolic reference to the field on which it operates, it must not only complete the field resolution steps given in 5.4.3.2 but also check that the field is not static. If it is a static field, a linking exception must be thrown.

Notably, in order for an invokedynamic instruction to successfully resolve the symbolic reference to a call site specifier, the bootstrap method specified therein must complete normally and return a suitable call site object. If the bootstrap method completes abruptly or returns an unsuitable call site object, a linking exception must be thrown.

Linking exceptions generated by checks that are specific to the execution of a particular Java Virtual Machine instruction are given in the description of that instruction and are not covered in this general discussion of resolution. Note that such exceptions, although described as part of the execution of Java Virtual Machine instructions rather than resolution, are still properly considered failures of resolution.

The following sections describe the initial process of resolving a symbolic reference in the run-time constant pool (5.1) of a class or interface D. Details of resolution differ with the kind of symbolic reference to be resolved.

5.4.3.5 Method Type and Method Handle Resolution

To resolve an unresolved symbolic reference to a method type, it is as if resolution occurs of unresolved symbolic references to classes and interfaces (5.4.3.1) whose names correspond to the types a reference to an instance of Class is produced for each parameter type and return type given in the method descriptor (4.3.3).

For each type named in the descriptor, if the type is a primitive type or void, an instance of Class representing that type is produced directly. Otherwise, an instance of Class corresponding to the type is produced as if by resolution of an unresolved symbolic reference to a class or interface with the given name (5.4.3.1).

Any exception that can be thrown as a result of failure of resolution of a class reference can thus be thrown as a result of failure of method type resolution.

The result of successful method type resolution is a reference to an instance of java.lang.invoke.MethodType which represents the method descriptor.

Method type resolution occurs regardless of whether the run time constant pool actually contains symbolic references to classes and interfaces indicated in the method descriptor. Also, the resolution is deemed to occur on unresolved symbolic references, so a failure to resolve one method type will not necessarily lead to a later failure to resolve another method type with the same textual method descriptor, if suitable classes and interfaces can be loaded by the later time.

...

5.4.3.6 Dynamically-Computed Constant and Call Site Specifier Resolution

To resolve an unresolved symbolic reference to a call site specifier dynamically-computed constant or call site, involves three eight steps are performed:

• A call site specifier gives The symbolic reference includes a symbolic reference to a bootstrap method handle which is to serve as the bootstrap method for a dynamic call site (4.7.23) to be invoked. The method handle is resolved to obtain a reference to an instance of java.lang.invoke.MethodHandle (5.4.3.5).

  Any exception that can be thrown as a result of failure of resolution of a symbolic reference to a method handle can be thrown in this step.

• The symbolic reference includes n static arguments (n ≥ 0). An argument array is created by allocating a new array with component type Object and length n+3 from the garbage-collected heap (2.5.3). The components of the array are initialized to null.

  In some cases, a Java Virtual Machine implementation may be able to skip allocation of the argument array and, without any change in observable behavior, pass the arguments directly to the bootstrap method handle.

  As usual, JVM implementations are free to make optimizations however they see fit, as long as there is no behavioral change. We highlight one possibility here.

  The eventual call to invokeWithArguments encapsulates many of the behavioral requirements. Calls to invoke or invokeExact will often have similar behavior, though they do not always agree in the treatment of conversions and error checks.

  Implementations may generally store static arguments in either boxed or unboxed forms, because invokeWithArguments freely converts between those forms.

• The first component of the argument array is set to a reference to an instance of java.lang.invoke.MethodHandles.Lookup for the class in which this symbolic reference occurs, produced as if by invocation of java.lang.invoke.MethodHandles.lookup.

• The symbolic reference includes a name, N. The second component of the argument array is set to a reference to a String denoting N.

• A call site specifier gives a method descriptor, TD The symbolic reference includes a field or method descriptor. A reference to an instance of java.lang.invoke.MethodType is obtained as if by resolution of a symbolic reference to a method type with the same parameter and return types as TD (5.4.3.5). The third component of the argument array is set to a reference to an object derived from the descriptor, as follows:

  • The field descriptor of a dynamically-computed constant may name a primitive type, a class or interface type, or an array type. If it names a primitive type, an instance of Class representing that type is produced. Otherwise, it is resolved as if by resolution of an unresolved symbolic reference to a class or interface with the given name (5.4.3.1), producing an instance of Class.

  • The method descriptor of a dynamically-computed call site is resolved as if by resolution of an unresolved symbolic reference to a method type with the given method descriptor (5.4.3.5), producing an instance of java.lang.invoke.MethodType.

  Any exception that can be thrown as a result of failure of resolution of a symbolic reference to a class or interface, or to a method type, can be thrown in this step.

• A call site specifier gives zero or more static arguments, which communicate application-specific metadata to the bootstrap method. Any static arguments which are symbolic references to classes, method handles, or method types are resolved, as if by invocation of the ldc instruction (ldc), to obtain references to Class objects, java.lang.invoke.MethodHandle objects, and java.lang.invoke.MethodType objects respectively. Any static arguments that are string literals are used to obtain references to String objects.

  For each static argument included in the symbolic reference, in the order in which they appear, the next component of the argument array is set to a reference to an object derived from the static argument, as follows:

  • If the static argument is a numeric constant value (5.1), then where v is the constant value, T is the field descriptor of its primitive type (4.3.3), and id is a method handle produced as if by invocation of java.lang.invoke.MethodHandles.identity with an argument representing the class Object, the array component is an object produced as if by the invocation id.invoke(v) with method descriptor (T)Ljava/lang/Object;.

  • If the static argument is a string constant value, the array component is a reference to that value.

  • If the static argument is a symbolic reference to a dynamically-computed constant with a primitive field descriptor, the dynamically-computed constant is resolved, producing a primitive value. The array component is an object derived from this value using the conversion process described above for numeric constant values.

  • If the static argument is any other symbolic reference, the array component is the result of resolution of the symbolic reference.

  Any exception that can be thrown as a result of failure of resolution of a symbolic reference can be thrown in this step.

  Let X be the symbolic reference currently being resolved, and let Y be a static argument of X to be resolved as described above. If X and Y are both dynamically-computed constants, and if Y is either the same as X or has a static argument that references X through its static arguments, directly or indirectly, resolution fails with a StackOverflowError.

  This rule allows some leeway in the sequencing of the error check: the implementation may resolve some of the static arguments of Y, or may not.

  CONSTANT_Dynamic structures are unique in that they are syntactically allowed to refer to themselves via the BootstrapMethods attribute. Rather than mandating that such cycles be detected at class load time (a potentially-expensive check), we permit cycles initially, but mandate a failure at resolution time.

  If an implementation of resolution makes recursive use of a Java Virtual Machine stack (2.5.2) or native method stack (2.5.6), the StackOverflowError will occur naturally. If not, we require the implementation to detect the error condition rather than, for example, looping infinitely.

  Tools and APIs that model unresolved constant pools are free to handle static argument cycles in ad hoc ways, and in general should consider them errors.

  A similar error condition may arise if the body of a bootstrap method makes reference to a constant currently being resolved. This has always been possible for invokedynamic bootstraps, and does not require special treatment in the specification: the recursive invokeWithArguments calls will naturally lead to a StackOverflowError.

The result of call site specifier resolution is a tuple consisting of:

• the reference to an instance of java.lang.invoke.MethodHandle,
• the reference to an instance of java.lang.invoke.MethodType,
• the references to instances of Class, java.lang.invoke.MethodHandle, java.lang.invoke.MethodType, and String.

During resolution of the symbolic reference to the method handle in the call site specifier, or resolution of the symbolic reference to the method type for the method descriptor in the call site specifier, or resolution of a symbolic reference to any static argument, any of the exceptions pertaining to method type or method handle resolution may be thrown (5.4.3.5).

• Next, the bootstrap method handle is invoked, as if by the invocation mh.invokeWithArguments(args), where mh is the bootstrap method handle and args is the argument array.

  Due to the behavior of the java.lang.invoke.MethodHandle.invokeWithArguments method, note that the method type of the bootstrap method handle need not exactly match the types of the arguments. For example, the first parameter type of the bootstrap method handle could be Object instead of java.lang.invoke.MethodHandles.Lookup. If the bootstrap method handle is variable arity, then some or all of the arguments may be collected into a trailing array parameter.

  If the invocation fails by throwing an instance of Error or a subclass of Error, resolution fails with that exception.

  If the invocation fails by throwing an exception that is not an instance of Error or a subclass of Error, resolution fails with a BootstrapMethodError whose cause is the thrown exception.

  For example, if the bootstrap method handle has the wrong arity, resolution will fail with a BootstrapMethodError whose cause is a java.lang.invoke.WrongMethodTypeException. If the bootstrap method handle has incompatible parameter types, resolution with fail with a BootstrapMethodError whose cause is a java.lang.invoke.ClassCastException.

  The old invokedynamic specification suggests that wrapping an exception in a BootstrapMethodError may need to occur during earlier steps of resolution as well, but those steps will never throw something other than an Error.

• Finally, the reference resulting from invocation of the bootstrap method handle is validated.

  • When resolving a dynamically-computed constant with field descriptor T, where obj is the reference resulting from invocation of the bootstrap method handle, and id is a method handle produced as if by invocation of java.lang.invoke.MethodHandles.identity with an argument representing the class Object, obj is converted to type T as if by the invocation id.invoke(obj) with method descriptor (Ljava/lang/Object;)T.

    The result of this conversion is the result of resolution.

    If the conversion fails by throwing a NullPointerException or a ClassCastException, resolution fails with a BootstrapMethodError.

    We could require that the thrown exception act as the cause of the BootstrapMethodError, but this would be more prescriptive than the pre-existing behavior for dynamically-computed call sites (described next). Implementations are free, of course, to do so anyway.

  • When resolving a dynamically-computed call site with referenced method descriptor MT, if the reference produced by the bootstrap method handle has all of the following properties, it is the result of resolution:

    • The reference is not null
    • The reference is to an instance of java.lang.invoke.CallSite or a subclass of java.lang.invoke.CallSite
    • The type of the CallSite is semantically equal to MT

    If the reference does not have these properties, resolution fails with a BootstrapMethodError.

These steps perform some computations "as if by invocation" of certain methods. In each case, the invocation behavior is given in detail by the specifications for invokestatic and invokevirtual. The invocation occurs in the thread and from the class that is attempting resolution of the symbolic reference. However, no corresponding method references are required to appear in the run-time constant pool, no particular method's operand stack is necessarily used, and the value of the max_stack item of any method's Code attribute is not enforced for the invocation.

If several threads attempt resolution at the same time, the bootstrap method may be invoked concurrently. Thus, bootstrap methods which access global application data must take precautions against race conditions.

6.5 invokedynamic

Operation

Invoke dynamic method a dynamically-computed call site

Format

getfield indexbyte1 indexbyte2 0 0

Forms

invokedynamic = 186 (0xba)

Operand Stack

..., [arg1, [arg2 ... ]] →
...

Description

Each specific lexical occurrence of an invokedynamic instruction is called a dynamic call site.

First, the unsigned indexbyte1 and indexbyte2 are used to construct an index into the run-time constant pool of the current class (2.6), where the value of the index is (indexbyte1 << 8) | indexbyte2. The run-time constant pool item at that index must be a symbolic reference to a dynamically-computed call site specifier (5.1). The values of the third and fourth operand bytes must always be zero.

The call site specifier symbolic reference is resolved (5.4.3, 5.4.3.6) for this specific dynamic call site invokedynamic instruction to obtain a reference to an instance of java.lang.invoke.MethodHandle that will serve as the bootstrap method, a reference to an instance of java.lang.invoke.MethodType, and references to static arguments a java.lang.invoke.CallSite object.

Next, as part of the continuing resolution of the call site specifier, the bootstrap method is invoked as if by execution of an invokevirtual instruction (invokevirtual) that indicates a run-time constant pool index to a symbolic reference R where:

• R is a symbolic reference to a method of a class (5.1);

• for the symbolic reference to the class in which the method is to be found, R specifies java.lang.invoke.MethodHandle;

• for the name of the method, R specifies invoke;

• for the descriptor of the method, R specifies a return type of java.lang.invoke.CallSite and parameter types derived from the items pushed onto the operand stack.

  The first three parameter types are java.lang.invoke.MethodHandles.Lookup, String, and java.lang.invoke.MethodType, in that order. If the call site specifier has any static arguments, then a parameter type for each argument is appended to the parameter types of the method descriptor in the order that the arguments were pushed on to the operand stack. These parameter types may be Class, java.lang.invoke.MethodHandle, java.lang.invoke.MethodType, String, int, long, float, or double.

and where it is as if the following items were pushed, in order, onto the operand stack:

• the reference to the instance of java.lang.invoke.MethodHandle that serves as the bootstrap method;

• a reference to an instance of java.lang.invoke.MethodHandles.Lookup for the class in which this dynamic call site occurs;

• a reference to a String denoting the method name in the call site specifier;

• the reference to the instance of java.lang.invoke.MethodType obtained for the method descriptor in the call site specifier;

• references to classes, method types, method handles, and string literals denoted as static arguments in the call site specifier, and numeric values (2.3.1, 2.3.2) denoted as static arguments in the call site specifier, in the order in which they appear in the call site specifier. (That is, no boxing occurs for primitive values.)

The symbolic reference R describes a method which is signature polymorphic (2.9.3). Due to the operation of invokevirtual on a signature polymorphic method called invoke, the type descriptor of the receiving method handle (representing the bootstrap method) need not be semantically equal to the method descriptor specified by R. For example, the first parameter type specified by R could be Object instead of java.lang.invoke.MethodHandles.Lookup, and the return type specified by R could be Object instead of java.lang.invoke.CallSite. As long as the bootstrap method can be invoked by the invoke method without a java.lang.invoke.WrongMethodTypeException being thrown, the type descriptor of the method handle which represents the bootstrap method is arbitrary.

If the bootstrap method is a variable arity method, then some or all of the arguments on the operand stack specified above may be collected into a trailing array parameter.

The invocation of a bootstrap method occurs within a thread that is attempting resolution of the symbolic reference to the call site specifier of this dynamic call site. 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.

The result returned by the bootstrap method must be a reference to an object whose class is java.lang.invoke.CallSite or a subclass of java.lang.invoke.CallSite. This object is known as the call site object. The reference is popped from the operand stack used as if in the execution of an invokevirtual instruction.

If several threads simultaneously execute the bootstrap method for the same dynamic call site, the Java Virtual Machine must choose one returned call site object and install it visibly to all threads. Any other bootstrap methods executing for the dynamic call site are allowed to complete, but their results are ignored, and the threads' execution of the dynamic call site proceeds with the chosen call site object.

The call site object has a type descriptor (an instance of java.lang.invoke.MethodType) which must be semantically equal to the java.lang.invoke.MethodType object obtained for the method descriptor in the call site specifier.

The result of successful call site specifier resolution is a call site object which is permanently bound to the dynamic call site.

The nargs argument values are popped from the operand stack. The method handle represented by the target of the bound call site object is invoked. The invocation occurs as if by execution of an invokevirtual instruction that indicates a run-time constant pool index to a symbolic reference T where:

• T is a symbolic reference to a method of a class;
• for the symbolic reference to the class in which the method is to be found, T specifies java.lang.invoke.MethodHandle;
• for the name of the method, T specifies invokeExact;
• for the descriptor of the method, T specifies the method descriptor in the call site specifier.

and where it is as if the following items were pushed, in order, onto the operand stack:

• the reference to the target of the call site object;
• the nargs argument values, where the number, type, and order of the values must be consistent with the method descriptor in the call site specifier.

Linking Exceptions

If resolution of the symbolic reference to the call site specifier throws an exception E, the invokedynamic instruction throws E if the type of E is Error or a subclass, else throws a BootstrapMethodError that wraps E.

Otherwise, during the continuing resolution of the call site specifier, if invocation of the bootstrap method completes abruptly ([2.6.5]) because of a throw of an exception E, the invokedynamic instruction throws E if the type of E is Error or a subclass, else throws a BootstrapMethodError that wraps E. (The latter can occur if the bootstrap method has the wrong arity, parameter type, or return type, causing java.lang.invoke.MethodHandle.invoke to throw java.lang.invoke.WrongMethodTypeException.)

Otherwise, during the continuing resolution of the call site specifier, if the result from the bootstrap method invocation is not a reference to an instance of java.lang.invoke.CallSite, the invokedynamic instruction throws a BootstrapMethodError.

Otherwise, during the continuing resolution of the call site specifier, if the type descriptor of the target of the call site object is not semantically equal to the method descriptor in the call site specifier, the invokedynamic instruction throws a BootstrapMethodError.

During resolution of the symbolic reference to a dynamically-computed call site, any of the exceptions pertaining to dynamically-computed call site resolution (5.4.3.6) can be thrown.

Run-time Exceptions Notes

If this specific dynamic call site completed resolution of its call site specifier, it implies that a non-null reference to an instance of java.lang.invoke.CallSite is bound to this dynamic call site. Therefore, the operand stack item which represents a reference to the target of the call site object is never null. Similarly, it implies that the method descriptor in the call site specifier is semantically equal to the type descriptor of the method handle to be invoked as if by execution of an invokevirtual instruction. Together, these invariants mean that an invokedynamic instruction which is bound to a call site object never throws a NullPointerException or a java.lang.invoke.WrongMethodTypeException.

6.5 ldc

Operation

Push item from run-time constant pool

Format

ldc index

Forms

ldc = 18 (0x12)

Operand Stack

... →
..., value

Description

The index is an unsigned byte that must be a valid index into the run-time constant pool of the current class (2.6). The run-time constant pool entry at index either must be a run-time constant of type int or float, or a reference to a string literal, or a symbolic reference to a class, method type, or method handle (5.1) loadable constant (5.1), and must not have type long or double.

If the run-time constant pool entry is a run-time constant of type int or float, the numeric value of that run-time constant is pushed onto the operand stack as an int or float, respectively constant value, that value is pushed onto the operand stack.

Otherwise, if the run-time constant pool entry is a reference to an instance of class String representing a string literal (5.1), then a reference to that instance, value, is pushed onto the operand stack.

Otherwise, if the run-time constant pool entry is a symbolic reference to a class (5.1), then the named class is resolved (5.4.3.1) and a reference to the Class object representing that class, value, is pushed onto the operand stack.

Otherwise, the run-time constant pool entry must be a symbolic reference to a method type or a method handle (5.1). The method type or method handle symbolic reference is resolved (5.4.3.5 5.4.3) and a reference to the resulting instance of java.lang.invoke.MethodType or java.lang.invoke.MethodHandle, value, the resulting value is pushed onto the operand stack.

Linking Exceptions

During resolution of a symbolic reference to a class, any of the exceptions pertaining to class resolution (5.4.3.1 5.4.3) can be thrown.

During resolution of a symbolic reference to a method type or method handle, any of the exception pertaining to method type or method handle resolution (5.4.3.5) can be thrown.

Notes

The ldc instruction can only be used to push a value of type float taken from the float value set (2.3.2) because a constant of type float in the constant pool (4.4.4) must be taken from the float value set.

6.5 ldc_w

Operation

Push item from run-time constant pool (wide index)

Format

ldc_w indexbyte1 indexbyte2

Forms

ldc_w = 19 (0x13)

Operand Stack

... →
..., value

Description

The unsigned indexbyte1 and indexbyte2 are assembled into an unsigned 16-bit index into the run-time constant pool of the current class (2.6), where the value of the index is calculated as (indexbyte1 << 8) | indexbyte2. The index must be a valid index into the run-time constant pool of the current class. The run-time constant pool entry at the index either must be a run-time constant of type int or float, or a reference to a string literal, or a symbolic reference to a class, method type, or method handle (5.1) loadable constant (5.1), and must not have type long or double.

If the run-time constant pool entry is a run-time constant of type int or float, the numeric value of that run-time constant is pushed onto the operand stack as an int or float, respectively constant value, that value is pushed onto the operand stack.

Otherwise, if the run-time constant pool entry is a reference to an instance of class String representing a string literal (5.1), then a reference to that instance, value, is pushed onto the operand stack.

Otherwise, if the run-time constant pool entry is a symbolic reference to a class (5.1), then the named class is resolved (5.4.3.1) and a reference to the Class object representing that class, value, is pushed onto the operand stack.

Otherwise, the run-time constant pool entry must be a symbolic reference to a method type or a method handle (5.1). The method type or method handle symbolic reference is resolved (5.4.3.5 5.4.3) and a reference to the resulting instance of java.lang.invoke.MethodType or java.lang.invoke.MethodHandle, value, the resulting value is pushed onto the operand stack.

Linking Exceptions

During resolution of a symbolic reference to a class, any of the exceptions pertaining to class resolution (5.4.3.1 5.4.3) can be thrown.

During resolution of a symbolic reference to a method type or method handle, any of the exception pertaining to method type or method handle resolution (5.4.3.5) can be thrown.

Notes

The ldc_w instruction is identical to the ldc instruction (ldc) except for its wider run-time constant pool index.

The ldc_w instruction can only be used to push a value of type float taken from the float value set (2.3.2) because a constant of type float in the constant pool (4.4.4) must be taken from the float value set.

6.5 ldc2_w

Operation

Push long or double from run-time constant pool (wide index)

Format

ldc2_w indexbyte1 indexbyte2

Forms

ldc2_w = 20 (0x14)

Operand Stack

... →
..., value

Description

The unsigned indexbyte1 and indexbyte2 are assembled into an unsigned 16-bit index into the run-time constant pool of the current class (2.6), where the value of the index is calculated as (indexbyte1 << 8) | indexbyte2. The index must be a valid index into the run-time constant pool of the current class. The run-time constant pool entry at the index must be a run-time constant of type long or double loadable constant (5.1), and must have type long or double. The numeric value of that run-time constant is pushed onto the operand stack as a long or double, respectively.

If the run-time constant pool entry is a constant value, that value is pushed onto the operand stack.

Otherwise, the run-time constant pool entry must be a symbolic reference. The symbolic reference is resolved (5.4.3) and the resulting value is pushed onto the operand stack.

Notes

Only a wide-index version of the ldc2_w instruction exists; there is no ldc2 instruction that pushes a long or double with a single-byte index.

The ldc2_w instruction can only be used to push a value of type double taken from the double value set (2.3.2) because a constant of type double in the constant pool (4.4.5) must be taken from the double value set.

Legal Notice