JEP 334: JVM Constants API

AuthorBrian Goetz
OwnerVicente Arturo Romero Zaldivar
TypeFeature
ScopeSE
StatusCandidate
Componentcore-libs / java.lang.invoke
Discussionamber dash dev at openjdk dot java dot net
BlocksJEP 303: Intrinsics for the LDC and INVOKEDYNAMIC Instructions
Reviewed byAlex Buckley
Endorsed byBrian Goetz
Created2018/05/15 21:52
Updated2018/11/13 11:31
Issue8203252

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 a constant 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 as loadable constants because they may serve as operands for the ldc instruction ("load constant"). They may also appear in the static argument list of a bootstrap method for the invokedynamic instruction. Executing an ldc or invokedynamic instruction causes the loadable constant to be resolved into a “live” value of a standard Java type such as Class, String, or int.

Programs which manipulate class 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 (a CONSTANT_String_info entry), since producing a "live" String object is straightforward, but it is problematic for a loadable constant that describes a class (a CONSTANT_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 during jlink-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:

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 package java.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, and DynamicConstantDesc) that contain the nominal information to describe these constants.

A draft snapshot of the API specification can be found here, and more information on its relationship with the features in JEP 303 can be found in this companion document.

Dependencies

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