1 /*
   2  * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /**
  27  * Classes and interfaces to represent <em>nominal descriptors</em> for run-time
  28  * entities such as classes or method handles, and classfile entities such as
  29  * constant pool entries or {@code invokedynamic} call sites.  These classes
  30  * are suitable for use in bytecode reading and writing APIs, {@code invokedynamic}
  31  * bootstraps, bytecode intrinsic APIs, and compile-time or link-time program
  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 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.DirectMethodHandleDescImpl}, {@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  * provides 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  *
  92  * @jvms 4.4 The Constant Pool
  93  *
  94  * @since 12
  95  */
  96 package java.lang.constant;