/*
* 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.
*/
package java.lang.constant;
import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodType;
import java.lang.invoke.VarHandle;
import java.util.Optional;
Represents a type which is constable. A constable type is one whose values are constants that can be represented in the constant pool of a Java classfile as described in JVMS 4.4, and whose instances can describe themselves nominally as a ConstantDesc
. Some constable types have a native representation in the constant pool: String
, Integer
, Long
, Float
, Double
, Class
, MethodType
, and MethodHandle
. The types String
, Integer
, Long
, Float
, and Double
serve as their own nominal descriptors; Class
, MethodType
, and MethodHandle
have corresponding nominal descriptors ClassDesc
, MethodTypeDesc
, and MethodHandleDesc
.
Other reference types can be constable if their instances can describe themselves in nominal form as a ConstantDesc
. Examples in the Java SE Platform API are types that support Java language features such as Enum
, and runtime support classes such as VarHandle
. These are typically described with a DynamicConstantDesc
, which describes dynamically generated constants (JVMS 4.4.10).
The nominal form of an instance of a constable type is obtained via describeConstable()
. A Constable need not be able to (or may choose not to) describe all its instances in the form of a ConstantDesc
; this method returns an Optional
that can be empty to indicate that a nominal descriptor could not be created for an instance. (For example, MethodHandle
will produce nominal descriptors for direct method handles, but not necessarily those produced by method handle combinators.)
@jvms 4.4 The Constant Pool @jvms 4.4.10 The CONSTANT_InvokeDynamic_info Structure Since: 12
/**
* Represents a type which is <em>constable</em>. A constable type is one whose
* values are constants that can be represented in the constant pool of a Java
* classfile as described in JVMS 4.4, and whose instances can describe themselves
* nominally as a {@link ConstantDesc}.
*
* <p>Some constable types have a native representation in the constant pool:
* {@link String}, {@link Integer}, {@link Long}, {@link Float},
* {@link Double}, {@link Class}, {@link MethodType}, and {@link MethodHandle}.
* The types {@link String}, {@link Integer}, {@link Long}, {@link Float},
* and {@link Double} serve as their own nominal descriptors; {@link Class},
* {@link MethodType}, and {@link MethodHandle} have corresponding nominal
* descriptors {@link ClassDesc}, {@link MethodTypeDesc}, and {@link MethodHandleDesc}.
*
* <p>Other reference types can be constable if their instances can describe
* themselves in nominal form as a {@link ConstantDesc}. Examples in the Java SE
* Platform API are types that support Java language features such as {@link Enum},
* and runtime support classes such as {@link VarHandle}. These are typically
* described with a {@link DynamicConstantDesc}, which describes dynamically
* generated constants (JVMS 4.4.10).
*
* <p>The nominal form of an instance of a constable type is obtained via
* {@link #describeConstable()}. A {@linkplain Constable} need
* not be able to (or may choose not to) describe all its instances in the form of
* a {@link ConstantDesc}; this method returns an {@link Optional} that can be
* empty to indicate that a nominal descriptor could not be created for an instance.
* (For example, {@link MethodHandle} will produce nominal descriptors for direct
* method handles, but not necessarily those produced by method handle
* combinators.)
* @jvms 4.4 The Constant Pool
* @jvms 4.4.10 The CONSTANT_InvokeDynamic_info Structure
*
* @since 12
*/
public interface Constable {
Returns an Optional
containing the nominal descriptor for this instance, if one can be constructed, or an empty Optional
if one cannot be constructed. Returns: An Optional
containing the resulting nominal descriptor, or an empty Optional
if one cannot be constructed.
/**
* Returns an {@link Optional} containing the nominal descriptor for this
* instance, if one can be constructed, or an empty {@link Optional}
* if one cannot be constructed.
*
* @return An {@link Optional} containing the resulting nominal descriptor,
* or an empty {@link Optional} if one cannot be constructed.
*/
Optional<? extends ConstantDesc> describeConstable();
}