Overview Summary

Module java.base

# Package java.lang.constant

Classes and interfaces to represent nominal descriptors for run-time entities such as classes or method handles, and classfile entities such as constant pool entries or `invokedynamic` call sites. These classes are suitable for use in bytecode reading and writing APIs, `invokedynamic` bootstraps, bytecode intrinsic APIs, and compile-time or link-time program analysis tools.

Every API that reads and writes bytecode instructions needs to model the operands to these instructions and other classfile structures (such as entries in the bootstrap methods table or stack maps, which frequently reference entries in the classfile constant pool.) Such entries can denote values of fundamental types, such as strings or integers; parts of a program, such as classes or method handles; or values of arbitrary user-defined types. The `ConstantDesc` hierarchy provides a representation of constant pool entries in nominal form that is convenient for APIs to model operands of bytecode instructions.

## Nominal Descriptors

A `ConstantDesc` is a description of a constant value. Such a description is the nominal form of the constant value; it is not the value itself, but rather a "recipe" for describing the value, storing the value in a constant pool entry, or reconstituting the value given a class loading context. Every `ConstantDesc` knows how to resolve itself -- compute the value that it describes -- via `ConstantDesc.resolveConstantDesc`. This allows an API which accepts `ConstantDesc` objects to evaluate them reflectively, provided that the classes and methods referenced in their nominal description are present and accessible.

The subtypes of `ConstantDesc` describe various kinds of constant values. For each type of loadable constant pool entry defined in JVMS 4.4, there is a corresponding subtype of `ConstantDesc`: `ClassDesc`, `MethodTypeDesc`, `DirectMethodHandleDesc`, `String`, `Integer`, `Long`, `Float`, `Double`, and `DynamicConstantDesc`. These classes provide type-specific accessor methods to extract the nominal information for that kind of constant. When a bytecode-writing API encounters a `ConstantDesc`, it should examine it to see which of these types it is, cast it, extract its nominal information, and generate the corresponding entry to the constant pool. When a bytecode-reading API encounters a constant pool entry, it can convert it to the appropriate type of nominal descriptor. For dynamic constants, bytecode-reading APIs may wish to use the factory `DynamicConstantDesc.ofCanonical`, which will inspect the bootstrap and, for well-known bootstraps, return a more specific subtype of `DynamicConstantDesc`, such as `Enum.EnumDesc`.

Another way to obtain the nominal description of a value is to ask the value itself. A `Constable` is a type whose values can describe themselves in nominal form as a `ConstantDesc`. Fundamental types such as `String` and `Class` implement `Constable`, as can user-defined classes. Entities that generate classfiles (such as compilers) can introspect over constable objects to obtain a more efficient way to represent their values in classfiles.

This package also includes `DynamicCallSiteDesc`, which represents a (non-loadable) `Constant_InvokeDynamic_info` constant pool entry. It describes the bootstrap method, invocation name and type, and bootstrap arguments associated with an `invokedynamic` instruction. It is also suitable for describing `invokedynamic` call sites in bytecode reading and writing APIs.

Since:
  12

- Interface Summary
  Interface | Description
  --- | ---
  ClassDesc | A nominal descriptor for a `Class` constant.
  Constable | Represents a type which is constable.
  ConstantDesc | A nominal descriptor for a loadable constant value, as defined in JVMS 4.4.
  DirectMethodHandleDesc | A nominal descriptor for a direct `MethodHandle`.
  MethodHandleDesc | A nominal descriptor for a `MethodHandle` constant.
  MethodTypeDesc | A nominal descriptor for a MethodType constant.

- Class Summary
  Class | Description
  --- | ---
  ConstantDescs | Predefined values of nominal descriptor for common constants, including descriptors for primitive class types and other common platform types, and descriptors for method handles for standard bootstrap methods.
  DynamicCallSiteDesc | A nominal descriptor for an `invokedynamic` call site.
  DynamicConstantDesc<T> | A nominal descriptor for a dynamic constant (one described in the constant pool with `Constant_Dynamic_info`.)

- Enum Summary
  Enum | Description
  --- | ---
  DirectMethodHandleDesc.Kind | Kinds of method handles that can be described with DirectMethodHandleDesc.