32  * analysis tools.
  33  *
  34  * <p>Every API that reads and writes bytecode instructions needs to model the
  35  * operands to these instructions and other classfile structures (such as entries
  36  * in the bootstrap methods table or stack maps, which frequently reference
  37  * entries in the classfile constant pool.) Such entries can denote values of
  38  * fundamental types, such as strings or integers; parts of a program, such as
  39  * classes or method handles; or values of arbitrary user-defined types.  The
  40  * {@link java.lang.constant.ConstantDesc} hierarchy provides a representation of
  41  * constant pool entries in nominal form that is convenient for APIs to model
  42  * operands of bytecode instructions.
  43  *
  44  * <h2><a id="nominal"></a>Nominal Descriptors</h2>
  45  *
  46  * <p>A {@link java.lang.constant.ConstantDesc} is a description of a constant
  47  * value.  Such a description is the <em>nominal form</em> of the constant value;
  48  * it is not the value itself, but rather a "recipe" for describing the value,
  49  * storing the value in a constant pool entry, or reconstituting the value given
  50  * a class loading context.  Every {@link java.lang.constant.ConstantDesc}
  51  * knows how to <em>resolve</em> itself -- compute the value that it describes --
  52  * via {@link java.lang.constant.ConstantDesc#resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup)}.
  53  * This allows an API which accepts {@link java.lang.constant.ConstantDesc}
  54  * objects to evaluate them reflectively, provided that the classes and methods
  55  * referenced in their nominal description are present and accessible.
  56  *
  57  * <p>The subtypes of {@link java.lang.constant.ConstantDesc} describe various kinds
  58  * of constant values.  For each type of loadable constant pool entry defined in JVMS 4.4,
  59  * there is a corresponding subtype of {@link java.lang.constant.ConstantDesc}:
  60  * {@link java.lang.constant.ClassDesc}, {@link java.lang.constant.MethodTypeDesc},
  61  * {@link java.lang.constant.DirectMethodHandleDesc}, {@link java.lang.String},
  62  * {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Float},
  63  * {@link java.lang.Double}, and {@link java.lang.constant.DynamicConstantDesc}.  These classes
  64  * provide type-specific accessor methods to extract the nominal information for
  65  * that kind of constant.  When a bytecode-writing API encounters a {@link java.lang.constant.ConstantDesc},
  66  * it should examine it to see which of these types it is, cast it, extract
  67  * its nominal information, and generate the corresponding entry to the constant pool.
  68  * When a bytecode-reading API encounters a constant pool entry, it can
  69  * convert it to the appropriate type of nominal descriptor.  For dynamic
  70  * constants, bytecode-reading APIs may wish to use the factory
  71  * {@link java.lang.constant.DynamicConstantDesc#ofCanonical(DirectMethodHandleDesc, java.lang.String, ClassDesc, ConstantDesc[])},
  72  * which will inspect the bootstrap and, for well-known bootstraps, return
  73  * a more specific subtype of {@link java.lang.constant.DynamicConstantDesc}, such as
  74  * {@link java.lang.Enum.EnumDesc}.
  75  *
  76  * <p>Another way to obtain the nominal description of a value is to ask the value
  77  * itself.  A {@link java.lang.constant.Constable} is a type whose values
  78  * can describe themselves in nominal form as a {@link java.lang.constant.ConstantDesc}.
  79  * Fundamental types such as {@link java.lang.String} and {@link java.lang.Class}
  80  * implement {@link java.lang.constant.Constable}, as can user-defined
  81  * classes.  Entities that generate classfiles (such as compilers) can introspect
  82  * over constable objects to obtain a more efficient way to represent their values
  83  * in classfiles.
  84  *
  85  * <p>This package also includes {@link java.lang.constant.DynamicCallSiteDesc},
  86  * which represents a (non-loadable) {@code Constant_InvokeDynamic_info} constant
  87  * pool entry.  It describes the bootstrap method, invocation name and type,
  88  * and bootstrap arguments associated with an {@code invokedynamic} instruction.
  89  * It is also suitable for describing {@code invokedynamic} call sites in bytecode
  90  * reading and writing APIs.
  91  *

  32  * analysis tools.
  33  *
  34  * <p>Every API that reads and writes bytecode instructions needs to model the
  35  * operands to these instructions and other classfile structures (such as entries
  36  * in the bootstrap methods table or stack maps, which frequently reference
  37  * entries in the classfile constant pool.) Such entries can denote values of
  38  * fundamental types, such as strings or integers; parts of a program, such as
  39  * classes or method handles; or values of arbitrary user-defined types.  The
  40  * {@link java.lang.constant.ConstantDesc} hierarchy provides a representation of
  41  * constant pool entries in nominal form that is convenient for APIs to model
  42  * operands of bytecode instructions.
  43  *
  44  * <h2><a id="nominal"></a>Nominal Descriptors</h2>
  45  *
  46  * <p>A {@link java.lang.constant.ConstantDesc} is a description of a constant
  47  * value.  Such a description is the <em>nominal form</em> of the constant value;
  48  * it is not the value itself, but rather a "recipe" for describing the value,
  49  * storing the value in a constant pool entry, or reconstituting the value given
  50  * a class loading context.  Every {@link java.lang.constant.ConstantDesc}
  51  * knows how to <em>resolve</em> itself -- compute the value that it describes --
  52  * via {@link java.lang.constant.ConstantDesc#resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup) ConstantDesc.resolveConstantDesc}.
  53  * This allows an API which accepts {@link java.lang.constant.ConstantDesc}
  54  * objects to evaluate them reflectively, provided that the classes and methods
  55  * referenced in their nominal description are present and accessible.
  56  *
  57  * <p>The subtypes of {@link java.lang.constant.ConstantDesc} describe various kinds
  58  * of constant values.  For each type of loadable constant pool entry defined in JVMS 4.4,
  59  * there is a corresponding subtype of {@link java.lang.constant.ConstantDesc}:
  60  * {@link java.lang.constant.ClassDesc}, {@link java.lang.constant.MethodTypeDesc},
  61  * {@link java.lang.constant.DirectMethodHandleDesc}, {@link java.lang.String},
  62  * {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Float},
  63  * {@link java.lang.Double}, and {@link java.lang.constant.DynamicConstantDesc}.  These classes
  64  * provide type-specific accessor methods to extract the nominal information for
  65  * that kind of constant.  When a bytecode-writing API encounters a {@link java.lang.constant.ConstantDesc},
  66  * it should examine it to see which of these types it is, cast it, extract
  67  * its nominal information, and generate the corresponding entry to the constant pool.
  68  * When a bytecode-reading API encounters a constant pool entry, it can
  69  * convert it to the appropriate type of nominal descriptor.  For dynamic
  70  * constants, bytecode-reading APIs may wish to use the factory
  71  * {@link java.lang.constant.DynamicConstantDesc#ofCanonical(DirectMethodHandleDesc, java.lang.String, ClassDesc, ConstantDesc[]) DynamicConstantDesc.ofCanonical},
  72  * which will inspect the bootstrap and, for well-known bootstraps, return
  73  * a more specific subtype of {@link java.lang.constant.DynamicConstantDesc}, such as
  74  * {@link java.lang.Enum.EnumDesc}.
  75  *
  76  * <p>Another way to obtain the nominal description of a value is to ask the value
  77  * itself.  A {@link java.lang.constant.Constable} is a type whose values
  78  * can describe themselves in nominal form as a {@link java.lang.constant.ConstantDesc}.
  79  * Fundamental types such as {@link java.lang.String} and {@link java.lang.Class}
  80  * implement {@link java.lang.constant.Constable}, as can user-defined
  81  * classes.  Entities that generate classfiles (such as compilers) can introspect
  82  * over constable objects to obtain a more efficient way to represent their values
  83  * in classfiles.
  84  *
  85  * <p>This package also includes {@link java.lang.constant.DynamicCallSiteDesc},
  86  * which represents a (non-loadable) {@code Constant_InvokeDynamic_info} constant
  87  * pool entry.  It describes the bootstrap method, invocation name and type,
  88  * and bootstrap arguments associated with an {@code invokedynamic} instruction.
  89  * It is also suitable for describing {@code invokedynamic} call sites in bytecode
  90  * reading and writing APIs.
  91  *