Summary

Introduce an API to model nominal descriptions of key class-file and run-time artifacts, in particular constants that are loadable from the constant pool.

Motivation

Every Java class file has aconstant pool which stores the operands for bytecode instructions in the class. Broadly speaking, entries in the constant pool describe either run-time artifacts such as classes and methods, or simple values such as strings and integers. All these entries are known asloadable constants because they may serve as operands for theldc instruction ("load constant"). They may also appear in the static argument list of a bootstrap method for theinvokedynamic instruction. Executing anldc orinvokedynamic instruction causes the loadable constant to be resolved into a “live” value of a standard Java type such asClass,String, orint.

Programs which manipulateclass files need to model bytecode instructions, and in turn loadable constants. However, using the standard Java types to model loadable constants is inadequate. It may be acceptable for a loadable constant that describes a string (aCONSTANT_String_info entry), since producing a "live"String object is straightforward, but it is problematic for a loadable constant that describes a class (aCONSTANT_Class_info entry), because producing a "live"Class object relies on the correctness and consistency of class loading. Unfortunately, class loading has many environmental dependencies and failure modes: the desired class does not exist or may not be accessible to the requester; the result of class loading varies with context; loading classes has side-effects; and sometimes class loading may not be possible at all (such as when the classes being described do not yet exist or are otherwise not loadable, as in during compilation of those same classes, or duringjlink-time transformation).

Consequently, programs which deal with loadable constants would be simpler if they could manipulate classes and methods, and less well-known artifacts such as method handles and dynamically-computed constants, in a purely nominal, symbolic form:

• Bytecode parsing and generation libraries must describe classes and method handles in symbolic form. Without a standard mechanism, they must resort to ad-hoc mechanisms, whether descriptor types such as ASM'sHandle, or tuples of strings (method owner, method name, method descriptor), or ad-hoc (and error-prone) encodings of these into a single string.

• Bootstraps forinvokedynamic that operate by spinning bytecode (such asLambdaMetafactory) would be simpler if they could work in a symbolic domain rather than with "live" classes and method handles.

• Compilers and offline transformers (such asjlink plugins) need to describe classes and members for classes that cannot be loaded into the running VM. Compiler plugins (such as annotation processors) similarly need to describe program elements in symbolic terms.

These kinds of libraries and tools would all benefit from having a single, standard way to describe loadable constants.

Description

We define a family of value-based symbolic reference (JVMS 5.1) types, in the new packagejava.lang.invoke.constant, capable of describing each kind of loadable constant. A symbolic reference describes a loadable constant in purely nominal form, separate from class loading or accessibility context. Some classes can act as their own symbolic references (e.g.,String); for linkable constants we define a family of symbolic reference types (ClassDesc,MethodTypeDesc,MethodHandleDesc, andDynamicConstantDesc) that contain the nominal information to describe these constants.

A draft snapshot of the API specification can be foundhere, and more information on its relationship with the features inJEP 303 can be found in thiscompanion document.

Dependencies

This JEP was originally a sub-feature ofJEP 303 (Intrinsics for the LDC and INVOKEDYNAMIC Instructions). JEP 303 now depends upon this JEP.