OpenJDK 1.23 · java.lang.invoke.ConstantGroup · APIdia, the JavaDoc alternative

An ordered sequence of constants, some of which may not yet be present. This type is used by BootstrapCallInfo to represent the sequence of bootstrap arguments associated with a bootstrap method, without forcing their immediate resolution.

If you use the simple get method, the constant will be resolved, if this has not already happened. An occasional side effect of resolution is a LinkageError, which happens if the system could not resolve the constant in question.

In order to peek at a constant without necessarily resolving it, use the non-throwing get method. This method will never throw a resolution error. Instead, if the resolution would result in an error, or if the implementation elects not to attempt resolution at this point, then the method will return the user-supplied sentinel value.

To iterate through the constants, resolving as you go, use the iterator provided on the List-typed view. If you supply a sentinel, resolution will be suppressed.

Typically the constant is drawn from a constant pool entry in the virtual machine. Constant pool entries undergo a one-time state transition from unresolved to resolved, with a permanently recorded result. Usually that result is the desired constant value, but it may also be an error. In any case, the results displayed by a ConstantGroup are stable in the same way. If a query to a particular constant in a ConstantGroup throws an exception once, it will throw the same kind of exception forever after. If the query returns a constant value once, it will return the same value forever after.

The only possible change in the status of a constant is from the unresolved to the resolved state, and that happens exactly once. A constant will never revert to an unlinked state. However, from the point of view of this interface, constants may appear to spontaneously resolve. This is so because constant pools are global structures shared across threads, and because prefetching of some constants may occur, there are no strong guarantees when the virtual machine may resolve constants.

When choosing sentinel values, be aware that a constant pool which has CONSTANT_Dynamic entries can contain potentially any representable value, and arbitrary implementations of ConstantGroup are also free to produce arbitrary values. This means some obvious choices for sentinel values, such as null, may sometimes fail to distinguish a resolved from an unresolved constant in the group. The most reliable sentinel is a privately created object, or perhaps the ConstantGroup itself.

Method Summary

Modifier and Type	Method and Description
public default List<Object>	Returns: a `List` view on this group which will force resolution asList() Create a view on this group as a `List` view.
public default List<Object>	Returns: a `List` view on this group which will not force resolution asList(Object the sentinel value to return if a constant is not present ifNotPresent) Create a view on this group as a `List` view.
public default int	Returns: the limiting index, `end` copyConstants(int index of first constant to retrieve start, int limiting index of constants to retrieve end, Object[] array to receive the requested values buf, int position in the array to offset storing the values pos) Copy a sequence of constant values into a given buffer.
public default int	Returns: the limiting index, `end` copyConstants(int index of first constant to retrieve start, int limiting index of constants to retrieve end, Object[] array to receive the requested values buf, int position in the array to offset storing the values pos, Object sentinel value to store if a value is not available ifNotPresent) Copy a sequence of constant values into a given buffer.
public Object	Returns: the selected constant get(int which constant to select index) Returns the selected constant, resolving it if necessary.
public Object	Returns: the selected constant, if available, else the sentinel value get(int the selected constant index, Object the sentinel value to return if the constant is not present ifNotPresent) Returns the selected constant, or the given sentinel value if there is none available.
public boolean	Returns: `true` if the selected constant is known by this object to be present, `false` if it is known not to be present or isPresent(int the selected constant index) Returns an indication of whether a constant may be available.
public static ConstantGroup	Returns: a new constant group with the given constants and resolution behavior makeConstantGroup(List<Object> the elements of this constant group constants, Object sentinel value provided instead of a missing constant ifNotPresent, IntFunction<Object> function to call when a missing constant is resolved constantProvider) Make a new constant group with the given constants.
public static ConstantGroup	Returns: a new constant group with the given constants makeConstantGroup(List<Object> the constants of this constant group constants) Make a new constant group with the given constant values.
public int	Returns: the number of constants in this group size() Returns the number of constants in this group.
public default ConstantGroup	Returns: a view on the selected sub-group subGroup(int the index to begin the view start, int the index to end the view end) Create a view on a sub-sequence of this group.

Method Detail

asList back to summary

asList	back to summary
public default List<Object> asList() Create a view on this group as a `List` view. Any request for a constant through this view will force resolution. Returns:List<Object> a `List` view on this group which will force resolution

public default List<Object> asList()

Create a view on this group as a List view. Any request for a constant through this view will force resolution.

Returns:List<Object>: a List view on this group which will force resolution

asList back to summary

asList	back to summary
public default List<Object> asList(Object ifNotPresent) Create a view on this group as a `List` view. Any request for a constant through this view will return the given sentinel value, if the corresponding call to `get(int, Object)` would do so. Parameters ifNotPresent:Object the sentinel value to return if a constant is not present Returns:List<Object> a `List` view on this group which will not force resolution

public default List<Object> asList(Object ifNotPresent)

Create a view on this group as a List view. Any request for a constant through this view will return the given sentinel value, if the corresponding call to get(int, Object) would do so.

Parameters

ifNotPresent:Object: the sentinel value to return if a constant is not present

Returns:List<Object>

a List view on this group which will not force resolution

copyConstants back to summary

copyConstants	back to summary
public default int copyConstants(int start, int end, Object[] buf, int pos) throws LinkageError Copy a sequence of constant values into a given buffer. This is equivalent to `end-offset` separate calls to `get`, for each index in the range from `offset` up to but not including `end`. For the first constant that cannot be resolved, a `LinkageError` is thrown, but only after preceding constant value have been stored. Parameters start:int index of first constant to retrieve end:int limiting index of constants to retrieve buf:Object[] array to receive the requested values pos:int position in the array to offset storing the values Returns:int the limiting index, `end` Exceptions LinkageError: if a constant cannot be resolved

public default int copyConstants(int start, int end, Object[] buf, int pos) throws LinkageError

Copy a sequence of constant values into a given buffer. This is equivalent to end-offset separate calls to get, for each index in the range from offset up to but not including end. For the first constant that cannot be resolved, a LinkageError is thrown, but only after preceding constant value have been stored.

Parameters

start:int: index of first constant to retrieve
end:int: limiting index of constants to retrieve
buf:Object[]: array to receive the requested values
pos:int: position in the array to offset storing the values

Returns:int

the limiting index, end

Exceptions

LinkageError:: if a constant cannot be resolved

copyConstants back to summary

copyConstants	back to summary
public default int copyConstants(int start, int end, Object[] buf, int pos, Object ifNotPresent) Copy a sequence of constant values into a given buffer. This is equivalent to `end-offset` separate calls to `get`, for each index in the range from `offset` up to but not including `end`. Any constants that cannot be resolved are replaced by the given sentinel value. Parameters start:int index of first constant to retrieve end:int limiting index of constants to retrieve buf:Object[] array to receive the requested values pos:int position in the array to offset storing the values ifNotPresent:Object sentinel value to store if a value is not available Returns:int the limiting index, `end` Exceptions LinkageError: if `resolve` is true and a constant cannot be resolved

public default int copyConstants(int start, int end, Object[] buf, int pos, Object ifNotPresent)

Copy a sequence of constant values into a given buffer. This is equivalent to end-offset separate calls to get, for each index in the range from offset up to but not including end. Any constants that cannot be resolved are replaced by the given sentinel value.

Parameters

start:int: index of first constant to retrieve
end:int: limiting index of constants to retrieve
buf:Object[]: array to receive the requested values
pos:int: position in the array to offset storing the values
ifNotPresent:Object: sentinel value to store if a value is not available

Returns:int

the limiting index, end

Exceptions

LinkageError:: if resolve is true and a constant cannot be resolved

get	back to summary
public Object get(int index) throws LinkageError Returns the selected constant, resolving it if necessary. Throws a linkage error if resolution proves impossible. Parameters index:int which constant to select Returns:Object the selected constant Exceptions LinkageError: if the selected constant needs resolution and cannot be resolved

get

back to summary

public Object get(int index) throws LinkageError

Returns the selected constant, resolving it if necessary. Throws a linkage error if resolution proves impossible.

Parameters

index:int: which constant to select

Returns:Object

the selected constant

Exceptions

LinkageError:: if the selected constant needs resolution and cannot be resolved

get back to summary

get	back to summary
public Object get(int index, Object ifNotPresent) Returns the selected constant, or the given sentinel value if there is none available. If the constant cannot be resolved, the sentinel will be returned. If the constant can (perhaps) be resolved, but has not yet been resolved, then the sentinel may be returned, at the implementation's discretion. To force resolution (and a possible exception), call `get(int)`. Parameters index:int the selected constant ifNotPresent:Object the sentinel value to return if the constant is not present Returns:Object the selected constant, if available, else the sentinel value

public Object get(int index, Object ifNotPresent)

Returns the selected constant, or the given sentinel value if there is none available. If the constant cannot be resolved, the sentinel will be returned. If the constant can (perhaps) be resolved, but has not yet been resolved, then the sentinel may be returned, at the implementation's discretion. To force resolution (and a possible exception), call get(int).

Parameters

index:int: the selected constant
ifNotPresent:Object: the sentinel value to return if the constant is not present

Returns:Object

the selected constant, if available, else the sentinel value

isPresent back to summary

isPresent	back to summary
public boolean isPresent(int index) Returns an indication of whether a constant may be available. If it returns `true`, it will always return true in the future, and a call to `get(int)` will never throw an exception. After a normal return from `get(int)` or a present value is reported from `get(int, Object)`, this method must always return true. If this method returns `false`, nothing in particular can be inferred, since the query only concerns the internal logic of the `ConstantGroup` object which ensures that a successful query to a constant will always remain successful. The only way to force a permanent decision about whether a constant is available is to call `get(int)` and be ready for an exception if the constant is unavailable. Parameters index:int the selected constant Returns:boolean `true` if the selected constant is known by this object to be present, `false` if it is known not to be present or

public boolean isPresent(int index)

Returns an indication of whether a constant may be available. If it returns true, it will always return true in the future, and a call to get(int) will never throw an exception.

After a normal return from get(int) or a present value is reported from get(int, Object), this method must always return true.

If this method returns false, nothing in particular can be inferred, since the query only concerns the internal logic of the ConstantGroup object which ensures that a successful query to a constant will always remain successful. The only way to force a permanent decision about whether a constant is available is to call get(int) and be ready for an exception if the constant is unavailable.

Parameters

index:int: the selected constant

Returns:boolean

true if the selected constant is known by this object to be present, false if it is known not to be present or

makeConstantGroup back to summary

makeConstantGroup	back to summary
public static ConstantGroup makeConstantGroup(List<Object> constants, Object ifNotPresent, IntFunction<Object> constantProvider) Make a new constant group with the given constants. The value of `ifNotPresent` may be any reference. If this value is encountered as an element of the `constants` list, the new constant group will regard that element of the list as logically missing. If the new constant group is called upon to resolve a missing element of the group, it will refer to the given `constantProvider`, by calling it on the index of the missing element. The `constantProvider` must be stable, in the sense that the outcome of calling it on the same index twice will produce equivalent results. If `constantProvider` is the null reference, then it will be treated as if it were a function which raises `NoSuchElementException`. Parameters constants:List<Object> the elements of this constant group ifNotPresent:Object sentinel value provided instead of a missing constant constantProvider:IntFunction<Object> function to call when a missing constant is resolved Returns:ConstantGroup a new constant group with the given constants and resolution behavior

public static ConstantGroup makeConstantGroup(List<Object> constants, Object ifNotPresent, IntFunction<Object> constantProvider)

Make a new constant group with the given constants. The value of ifNotPresent may be any reference. If this value is encountered as an element of the constants list, the new constant group will regard that element of the list as logically missing. If the new constant group is called upon to resolve a missing element of the group, it will refer to the given constantProvider, by calling it on the index of the missing element. The constantProvider must be stable, in the sense that the outcome of calling it on the same index twice will produce equivalent results. If constantProvider is the null reference, then it will be treated as if it were a function which raises NoSuchElementException.

Parameters

constants:List<Object>: the elements of this constant group
ifNotPresent:Object: sentinel value provided instead of a missing constant
constantProvider:IntFunction<Object>: function to call when a missing constant is resolved

Returns:ConstantGroup

a new constant group with the given constants and resolution behavior

makeConstantGroup	back to summary
public static ConstantGroup makeConstantGroup(List<Object> constants) Make a new constant group with the given constant values. The constants will be copied from the given list into the new constant group, forcing resolution if any are missing. Parameters constants:List<Object> the constants of this constant group Returns:ConstantGroup a new constant group with the given constants

makeConstantGroup

back to summary

public static ConstantGroup makeConstantGroup(List<Object> constants)

Make a new constant group with the given constant values. The constants will be copied from the given list into the new constant group, forcing resolution if any are missing.

Parameters

constants:List<Object>: the constants of this constant group

Returns:ConstantGroup

a new constant group with the given constants

size	back to summary
public int size() Returns the number of constants in this group. This value never changes, for any particular group. Returns:int the number of constants in this group

size

back to summary

public int size()

Returns the number of constants in this group. This value never changes, for any particular group.

Returns:int: the number of constants in this group

subGroup	back to summary
public default ConstantGroup subGroup(int start, int end) Create a view on a sub-sequence of this group. Parameters start:int the index to begin the view end:int the index to end the view Returns:ConstantGroup a view on the selected sub-group

subGroup

back to summary

public default ConstantGroup subGroup(int start, int end)

Create a view on a sub-sequence of this group.

Parameters

start:int: the index to begin the view
end:int: the index to end the view

Returns:ConstantGroup

a view on the selected sub-group

pack-priv Interface ConstantGroup

Method Summary

Method Detail