src/java.base/share/classes/java/lang/constant/package-info.java - master - githubmirror/riscv-port

src/java.base/share/classes/java/lang/constant/package-info.java
101 строка6 KB
Adam Sotona
8306729: Add nominal descriptors of modules and packages to Constants API
03 май 2023, 09:34
03 май 2023, 09:34c8f3756
/*
 * Copyright (c) 2018, 2022, 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 {@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.
 *
 * <p>Other members of this package are {@link ModuleDesc}
 * and  {@link PackageDesc}. They represent module and package
 * info structures, suitable for describing modules and their content in bytecode
 * reading and writing APIs.
 *
 * @jvms 4.4 The Constant Pool
 *
 * @since 12
 */
package java.lang.constant;