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 package java.lang.constant;
  26 
  27 import java.lang.invoke.Intrinsics;
  28 import java.lang.Enum.EnumDesc;
  29 import java.lang.invoke.MethodHandle;
  30 import java.lang.invoke.MethodHandles;
  31 import java.lang.invoke.MethodType;
  32 import java.lang.invoke.VarHandle.VarHandleDesc;
  33 
  34 /**
  35  * A <a href="package-summary.html#nominal">nominal descriptor</a> for a loadable
  36  * constant value, as defined in JVMS 4.4. Such a descriptor can be resolved via
  37  * {@link ConstantDesc#resolveConstantDesc(MethodHandles.Lookup)} to yield the
  38  * constant value itself.
  39  *
  40  * <p>Class names in a nominal descriptor, like class names in the constant pool
  41  * of a classfile, must be interpreted with respect to a particular class
  42  * loader, which is not part of the nominal descriptor.
  43  *
  44  * <p>Static constants that are expressible natively in the constant pool ({@link String},
  45  * {@link Integer}, {@link Long}, {@link Float}, and {@link Double}) implement
  46  * {@link ConstantDesc}, and serve as nominal descriptors for themselves.
  47  * Native linkable constants ({@link Class}, {@link MethodType}, and
  48  * {@link MethodHandle}) have counterpart {@linkplain ConstantDesc} types:
  49  * {@link ClassDesc}, {@link MethodTypeDesc}, and {@link MethodHandleDesc}.
  50  * Other constants are represented by subtypes of {@link DynamicConstantDesc}.
  51  *
  52  * <p>APIs that perform generation or parsing of bytecode are encouraged to use
  53  * {@linkplain ConstantDesc} to describe the operand of an {@code ldc} instruction
  54  * (including dynamic constants), the static bootstrap arguments of
  55  * dynamic constants and {@code invokedynamic} instructions, and other
  56  * bytecodes or classfile structures that make use of the constant pool.
  57  *
  58  * <p>The {@linkplain ConstantDesc} types are also used by {@link Intrinsics}
  59  * to express {@code ldc} instructions.
  60  *
  61  * <p>Constants describing various common constants (such as {@link ClassDesc}
  62  * instances for platform types) can be found in {@link ConstantDescs}.
  63  *
  64  * <p>Implementations of {@linkplain ConstantDesc} must be
  65  * <a href="../doc-files/ValueBased.html">value-based</a> classes.
  66  *
  67  * <p>Non-platform classes should not implement {@linkplain ConstantDesc} directly.
  68  * Instead, they should extend {@link DynamicConstantDesc} (as {@link EnumDesc}
  69  * and {@link VarHandleDesc} do.)
  70  *
  71  * <p>Nominal descriptors should be compared using the
  72  * {@link Object#equals(Object)} method. There is no guarantee that any
  73  * particular entity will always be represented by the same descriptor instance.
  74  *
  75  * @apiNote In the future, if the Java language permits, {@linkplain ConstantDesc}
  76  * may become a {@code sealed} interface, which would prohibit subclassing except by
  77  * explicitly permitted types.  Clients can assume that the following
  78  * set of subtypes is exhaustive: {@link String}, {@link Integer},
  79  * {@link Long}, {@link Float}, {@link Double}, {@link ClassDesc},
  80  * {@link MethodTypeDesc}, {@link MethodHandleDesc}, and
  81  * {@link DynamicConstantDesc}; this list may be extended to reflect future
  82  * changes to the constant pool format as defined in JVMS 4.4.
  83  *
  84  * @see Constable
  85  * @see Intrinsics
  86  * @see ConstantDescs
  87  *
  88  * @jvms 4.4 The Constant Pool
  89  *
  90  * @since 12
  91  */
  92 public interface ConstantDesc {
  93     /**
  94      * Resolves this descriptor reflectively, emulating the resolution behavior
  95      * of JVMS 5.4.3 and the access control behavior of JVMS 5.4.4.  The resolution
  96      * and access control context is provided by the {@link MethodHandles.Lookup}
  97      * parameter.  No caching of the resulting value is performed.
  98      *
  99      * @param lookup The {@link MethodHandles.Lookup} to provide name resolution
 100      *               and access control context
 101      * @return the resolved constant value
 102      * @throws ReflectiveOperationException if a class, method, or field
 103      * could not be reflectively resolved in the course of resolution
 104      * @throws LinkageError if a linkage error occurs
 105      * @jvms 5.4.3 Resolution
 106      * @jvms 5.4.4 Access Control
 107      */
 108     Object resolveConstantDesc(MethodHandles.Lookup lookup) throws ReflectiveOperationException;
 109 }