ConstantBootstraps (Java SE 17 & JDK 17)
Description: declaration: module: java.base, package: java.lang.invoke, class: ConstantBootstraps
Keywords: java.lang.invoke.ConstantBootstraps class

Module java.base
Package java.lang.invoke

# Class ConstantBootstraps

java.lang.Object
java.lang.invoke.ConstantBootstraps

public final class ConstantBootstraps extends Object
Bootstrap methods for dynamically-computed constants.

The bootstrap methods in this class will throw a `NullPointerException` for any reference argument that is `null`, unless the argument is specified to be unused or specified to accept a `null` value.

Since:
  11

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static VarHandle`
  `arrayVarHandle(MethodHandles.Lookup lookup, String name, Class<VarHandle> type, Class<?> arrayClass)`
  Finds a `VarHandle` for an array type.
  `static <E extends Enum<E>>
  E`
  `enumConstant(MethodHandles.Lookup lookup, String name, Class<E> type)`
  Returns an `enum` constant of the type specified by `type` with the name specified by `name`.
  `static Object`
  `explicitCast(MethodHandles.Lookup lookup, String name, Class<?> dstType, Object value)`
  Applies a conversion from a source type to a destination type.
  `static VarHandle`
  `fieldVarHandle(MethodHandles.Lookup lookup, String name, Class<VarHandle> type, Class<?> declaringClass, Class<?> fieldType)`
  Finds a `VarHandle` for an instance field.
  `static Object`
  `getStaticFinal(MethodHandles.Lookup lookup, String name, Class<?> type)`
  Returns the value of a static final field declared in the class which is the same as the field's type (or, for primitive-valued fields, declared in the wrapper class.)
  `static Object`
  `getStaticFinal(MethodHandles.Lookup lookup, String name, Class<?> type, Class<?> declaringClass)`
  Returns the value of a static final field.
  `static Object`
  `invoke(MethodHandles.Lookup lookup, String name, Class<?> type, MethodHandle handle, Object... args)`
  Returns the result of invoking a method handle with the provided arguments.
  `static Object`
  `nullConstant(MethodHandles.Lookup lookup, String name, Class<?> type)`
  Returns a `null` object reference for the reference type specified by `type`.
  `static Class<?>`
  `primitiveClass(MethodHandles.Lookup lookup, String name, Class<?> type)`
  Returns a `Class` mirror for the primitive type whose type descriptor is specified by `name`.
  `static VarHandle`
  `staticFieldVarHandle(MethodHandles.Lookup lookup, String name, Class<VarHandle> type, Class<?> declaringClass, Class<?> fieldType)`
  Finds a `VarHandle` for a static field.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### nullConstant

    public static Object nullConstant(MethodHandles.Lookup lookup, String name, Class<?> type)
    Returns a `null` object reference for the reference type specified by `type`.
    Parameters:
      `lookup` - unused
      `name` - unused
      `type` - a reference type
    Returns:
      a `null` value
    Throws:
      `IllegalArgumentException` - if `type` is not a reference type

  - ### primitiveClass

    public static Class<?> primitiveClass(MethodHandles.Lookup lookup, String name, Class<?> type)
    Returns a `Class` mirror for the primitive type whose type descriptor is specified by `name`.
    Parameters:
      `lookup` - unused
      `name` - the descriptor (JVMS 4.3) of the desired primitive type
      `type` - the required result type (must be `Class.class`)
    Returns:
      the `Class` mirror
    Throws:
      `IllegalArgumentException` - if the name is not a descriptor for a primitive type or the type is not `Class.class`

  - ### enumConstant

    public static <E extends Enum<E>> E enumConstant(MethodHandles.Lookup lookup, String name, Class<E> type)
    Returns an `enum` constant of the type specified by `type` with the name specified by `name`.
    Type Parameters:
      `E` - The enum type for which a constant value is to be returned
    Parameters:
      `lookup` - the lookup context describing the class performing the operation (normally stacked by the JVM)
      `name` - the name of the constant to return, which must exactly match an enum constant in the specified type.
      `type` - the `Class` object describing the enum type for which a constant is to be returned
    Returns:
      the enum constant of the specified enum type with the specified name
    Throws:
      `IllegalAccessError` - if the declaring class or the field is not accessible to the class performing the operation
      `IllegalArgumentException` - if the specified enum type has no constant with the specified name, or the specified class object does not represent an enum type
    See Also:
      - `Enum.valueOf(Class, String)`

  - ### getStaticFinal

    public static Object getStaticFinal(MethodHandles.Lookup lookup, String name, Class<?> type, Class<?> declaringClass)
    Returns the value of a static final field.
    Parameters:
      `lookup` - the lookup context describing the class performing the operation (normally stacked by the JVM)
      `name` - the name of the field
      `type` - the type of the field
      `declaringClass` - the class in which the field is declared
    Returns:
      the value of the field
    Throws:
      `IllegalAccessError` - if the declaring class or the field is not accessible to the class performing the operation
      `NoSuchFieldError` - if the specified field does not exist
      `IncompatibleClassChangeError` - if the specified field is not `final`

  - ### getStaticFinal

    public static Object getStaticFinal(MethodHandles.Lookup lookup, String name, Class<?> type)
    Returns the value of a static final field declared in the class which is the same as the field's type (or, for primitive-valued fields, declared in the wrapper class.) This is a simplified form of `getStaticFinal(MethodHandles.Lookup, String, Class, Class)` for the case where a class declares distinguished constant instances of itself.
    Parameters:
      `lookup` - the lookup context describing the class performing the operation (normally stacked by the JVM)
      `name` - the name of the field
      `type` - the type of the field
    Returns:
      the value of the field
    Throws:
      `IllegalAccessError` - if the declaring class or the field is not accessible to the class performing the operation
      `NoSuchFieldError` - if the specified field does not exist
      `IncompatibleClassChangeError` - if the specified field is not `final`
    See Also:
      - `getStaticFinal(MethodHandles.Lookup, String, Class, Class)`

  - ### invoke

    public static Object invoke(MethodHandles.Lookup lookup, String name, Class<?> type, MethodHandle handle, Object... args) throws Throwable
    Returns the result of invoking a method handle with the provided arguments.

    This method behaves as if the method handle to be invoked is the result of adapting the given method handle, via `MethodHandle.asType(java.lang.invoke.MethodType)`, to adjust the return type to the desired type.

    Parameters:
      `lookup` - unused
      `name` - unused
      `type` - the desired type of the value to be returned, which must be compatible with the return type of the method handle
      `handle` - the method handle to be invoked
      `args` - the arguments to pass to the method handle, as if with `MethodHandle.invokeWithArguments(java.lang.Object...)`. Each argument may be `null`.
    Returns:
      the result of invoking the method handle
    Throws:
      `WrongMethodTypeException` - if the handle's method type cannot be adjusted to take the given number of arguments, or if the handle's return type cannot be adjusted to the desired type
      `ClassCastException` - if an argument or the result produced by invoking the handle cannot be converted by reference casting
      `Throwable` - anything thrown by the method handle invocation

  - ### fieldVarHandle

    public static VarHandle fieldVarHandle(MethodHandles.Lookup lookup, String name, Class<VarHandle> type, Class<?> declaringClass, Class<?> fieldType)
    Finds a `VarHandle` for an instance field.
    Parameters:
      `lookup` - the lookup context describing the class performing the operation (normally stacked by the JVM)
      `name` - the name of the field
      `type` - the required result type (must be `Class<VarHandle>`)
      `declaringClass` - the class in which the field is declared
      `fieldType` - the type of the field
    Returns:
      the `VarHandle`
    Throws:
      `IllegalAccessError` - if the declaring class or the field is not accessible to the class performing the operation
      `NoSuchFieldError` - if the specified field does not exist
      `IllegalArgumentException` - if the type is not `VarHandle`

  - ### staticFieldVarHandle

    public static VarHandle staticFieldVarHandle(MethodHandles.Lookup lookup, String name, Class<VarHandle> type, Class<?> declaringClass, Class<?> fieldType)
    Finds a `VarHandle` for a static field.
    Parameters:
      `lookup` - the lookup context describing the class performing the operation (normally stacked by the JVM)
      `name` - the name of the field
      `type` - the required result type (must be `Class<VarHandle>`)
      `declaringClass` - the class in which the field is declared
      `fieldType` - the type of the field
    Returns:
      the `VarHandle`
    Throws:
      `IllegalAccessError` - if the declaring class or the field is not accessible to the class performing the operation
      `NoSuchFieldError` - if the specified field does not exist
      `IllegalArgumentException` - if the type is not `VarHandle`

  - ### arrayVarHandle

    public static VarHandle arrayVarHandle(MethodHandles.Lookup lookup, String name, Class<VarHandle> type, Class<?> arrayClass)
    Finds a `VarHandle` for an array type.
    Parameters:
      `lookup` - the lookup context describing the class performing the operation (normally stacked by the JVM)
      `name` - unused
      `type` - the required result type (must be `Class<VarHandle>`)
      `arrayClass` - the type of the array
    Returns:
      the `VarHandle`
    Throws:
      `IllegalAccessError` - if the component type of the array is not accessible to the class performing the operation
      `IllegalArgumentException` - if the type is not `VarHandle`

  - ### explicitCast

    public static Object explicitCast(MethodHandles.Lookup lookup, String name, Class<?> dstType, Object value) throws ClassCastException
    Applies a conversion from a source type to a destination type.

    Given a destination type `dstType` and an input value `value`, one of the following will happen:

    - If `dstType` is `void.class`, a `ClassCastException` is thrown.
    - If `dstType` is `Object.class`, `value` is returned as is.

    Otherwise one of the following conversions is applied to `value`:

    1. If `dstType` is a reference type, a reference cast is applied to `value` as if by calling `dstType.cast(value)`.
    2. If `dstType` is a primitive type, then, if the runtime type of `value` is a primitive wrapper type (such as `Integer`), a Java unboxing conversion is applied 5.1.8 followed by a Java casting conversion 5.5 converting either directly to `dstType`, or, if `dstType` is `boolean`, to `int`, which is then converted to either `true` or `false` depending on whether the least-significant-bit is 1 or 0 respectively. If the runtime type of `value` is not a primitive wrapper type a `ClassCastException` is thrown.

    The result is the same as when using the following code:

    >      MethodHandle id = MethodHandles.identity(dstType);
    >      MethodType mt = MethodType.methodType(dstType, Object.class);
    >      MethodHandle conv = MethodHandles.explicitCastArguments(id, mt);
    >      return conv.invoke(value);

    Parameters:
      `lookup` - unused
      `name` - unused
      `dstType` - the destination type of the conversion
      `value` - the value to be converted
    Returns:
      the converted value
    Throws:
      `ClassCastException` - when `dstType` is `void`, when a cast per (1) fails, or when `dstType` is a primitive type and the runtime type of `value` is not a primitive wrapper type (such as `Integer`)
    Since:
      15