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) 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 * 92 * @jvms 4.4 The Constant Pool 93 * 94 * @since 12 95 */ 96 package java.lang.constant; 97