/*

 * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/**

 * Classes and interfaces to represent <em>nominal descriptors</em> for run-time

 * entities such as classes or method handles, and classfile entities such as

 * constant pool entries or {@code invokedynamic} call sites.  These classes

 * are suitable for use in bytecode reading and writing APIs, {@code invokedynamic}

 * bootstraps, bytecode intrinsic APIs, and compile-time or link-time program

 * analysis tools.

 *

 * <p>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

 * {@link java.lang.constant.ConstantDesc} hierarchy provides a representation of

 * constant pool entries in nominal form that is convenient for APIs to model

 * operands of bytecode instructions.

 *

 * <h2><a id="nominal"></a>Nominal Descriptors</h2>

 *

 * <p>A {@link java.lang.constant.ConstantDesc} is a description of a constant

 * value.  Such a description is the <em>nominal form</em> 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 {@link java.lang.constant.ConstantDesc}

 * knows how to <em>resolve</em> itself -- compute the value that it describes --

 * This allows an API which accepts {@link java.lang.constant.ConstantDesc}

 * objects to evaluate them reflectively, provided that the classes and methods

 * referenced in their nominal description are present and accessible.

 *

 * <p>The subtypes of {@link java.lang.constant.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 {@link java.lang.constant.ConstantDesc}:

 * {@link java.lang.constant.ClassDesc}, {@link java.lang.constant.MethodTypeDesc},

 * {@link java.lang.constant.DirectMethodHandleDesc}, {@link java.lang.String},

 * {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Float},

 * {@link java.lang.Double}, and {@link java.lang.constant.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 {@link java.lang.constant.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

 * which will inspect the bootstrap and, for well-known bootstraps, return

 * a more specific subtype of {@link java.lang.constant.DynamicConstantDesc}, such as

 * {@link java.lang.Enum.EnumDesc}.

 *

 * <p>Another way to obtain the nominal description of a value is to ask the value

 * itself.  A {@link java.lang.constant.Constable} is a type whose values

 * can describe themselves in nominal form as a {@link java.lang.constant.ConstantDesc}.

 * Fundamental types such as {@link java.lang.String} and {@link java.lang.Class}

 * implement {@link java.lang.constant.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.

 *

 * <p>This package also includes {@link java.lang.constant.DynamicCallSiteDesc},

 * which represents a (non-loadable) {@code Constant_InvokeDynamic_info} constant

 * pool entry.  It describes the bootstrap method, invocation name and type,

 * and bootstrap arguments associated with an {@code invokedynamic} instruction.

 * It is also suitable for describing {@code invokedynamic} call sites in bytecode

 * reading and writing APIs.

 *

 * @jvms 4.4 The Constant Pool

 *

 * @since 12

 */

package java.lang.constant;