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.MethodHandle;
  28 import java.lang.invoke.MethodType;
  29 import java.lang.invoke.VarHandle;
  30 import java.util.Optional;
  31 
  32 /**
  33  * Represents a type which is <em>constable</em>.  A constable type is one whose
  34  * values are constants that can be represented in the constant pool of a Java
  35  * classfile as described in JVMS 4.4, and whose instances can describe themselves
  36  * nominally as a {@link ConstantDesc}.
  37  *
  38  * <p>Some constable types have a native representation in the constant pool:
  39  * {@link String}, {@link Integer}, {@link Long}, {@link Float},
  40  * {@link Double}, {@link Class}, {@link MethodType}, and {@link MethodHandle}.
  41  * The types {@link String}, {@link Integer}, {@link Long}, {@link Float},
  42  * and {@link Double} serve as their own nominal descriptors; {@link Class},
  43  * {@link MethodType}, and {@link MethodHandle} have corresponding nominal
  44  * descriptors {@link ClassDesc}, {@link MethodTypeDesc}, and {@link MethodHandleDesc}.
  45  *
  46  * <p>Other reference types can be constable if their instances can describe
  47  * themselves in nominal form as a {@link ConstantDesc}. Examples in the Java SE
  48  * Platform API are types that support Java language features such as {@link Enum},
  49  * and runtime support classes such as {@link VarHandle}.  These are typically
  50  * described with a {@link DynamicConstantDesc}, which describes dynamically
  51  * generated constants (JVMS 4.4.10).
  52  *
  53  * <p>The nominal form of an instance of a constable type is obtained via
  54  * {@link #describeConstable()}. A {@linkplain Constable} need
  55  * not be able to (or may choose not to) describe all its instances in the form of
  56  * a {@link ConstantDesc}; this method returns an {@link Optional} that can be
  57  * empty to indicate that a nominal descriptor could not be created for an instance.
  58  * (For example, {@link MethodHandle} will produce nominal descriptors for direct
  59  * method handles, but not necessarily those produced by method handle
  60  * combinators.)
  61  * @jvms 4.4 The Constant Pool
  62  * @jvms 4.4.10 The {@code CONSTANT_Dynamic_info} and {@code CONSTANT_InvokeDynamic_info} Structures
  63  *
  64  * @since 12
  65  */
  66 public interface Constable {
  67     /**
  68      * Returns an {@link Optional} containing the nominal descriptor for this
  69      * instance, if one can be constructed, or an empty {@link Optional}
  70      * if one cannot be constructed.
  71      *
  72      * @return An {@link Optional} containing the resulting nominal descriptor,
  73      * or an empty {@link Optional} if one cannot be constructed.
  74      */
  75     Optional<? extends ConstantDesc> describeConstable();
  76 }