/*
* 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 --
* via {@link java.lang.constant.ConstantDesc#resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup) ConstantDesc.resolveConstantDesc}.
* 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
* {@link java.lang.constant.DynamicConstantDesc#ofCanonical(DirectMethodHandleDesc, java.lang.String, ClassDesc, ConstantDesc[]) DynamicConstantDesc.ofCanonical},
* 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;