-
- All Known Subinterfaces:
-
BootstrapCallInfo<T>
public interface ConstantGroup
An ordered sequence of constants, some of which may not yet be present. This type is used byBootstrapCallInfo
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 aConstantGroup
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_ConstantDynamic
entries can contain potentially any representable value, and arbitrary implementations ofConstantGroup
are also free to produce arbitrary values. This means some obvious choices for sentinel values, such asnull
, 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 theConstantGroup
itself.- Since:
- 1.10
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default List<Object>
asList()
Create a view on this group as aList
view.default List<Object>
asList(Object ifNotPresent)
Create a view on this group as aList
view.default int
copyConstants(int start, int end, Object[] buf, int pos)
Copy a sequence of constant values into a given buffer.default int
copyConstants(int start, int end, Object[] buf, int pos, Object ifNotPresent)
Copy a sequence of constant values into a given buffer.Object
get(int index)
Returns the selected constant, resolving it if necessary.Object
get(int index, Object ifNotPresent)
Returns the selected constant, or the given sentinel value if there is none available.boolean
isPresent(int index)
Returns an indication of whether a constant may be available.static ConstantGroup
makeConstantGroup(List<Object> constants)
Make a new constant group with the given constant values.static ConstantGroup
makeConstantGroup(List<Object> constants, Object ifNotPresent, IntFunction<Object> constantProvider)
Make a new constant group with the given constants.int
size()
Returns the number of constants in this group.default ConstantGroup
subGroup(int start, int end)
Create a view on a sub-sequence of this group.
-
-
-
Method Detail
-
size
int size()
Returns the number of constants in this group. This value never changes, for any particular group.- Returns:
- the number of constants in this group
-
get
Object get(int index) throws LinkageError
Returns the selected constant, resolving it if necessary. Throws a linkage error if resolution proves impossible.- Parameters:
-
index
- which constant to select - Returns:
- the selected constant
- Throws:
-
LinkageError
- if the selected constant needs resolution and cannot be resolved
-
get
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), callget(int)
.- Parameters:
-
index
- the selected constant -
ifNotPresent
- the sentinel value to return if the constant is not present - Returns:
- the selected constant, if available, else the sentinel value
-
isPresent
boolean isPresent(int index)
Returns an indication of whether a constant may be available. If it returnstrue
, it will always return true in the future, and a call toget(int)
will never throw an exception.After a normal return from
get(int)
or a present value is reported fromget(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 theConstantGroup
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 callget(int)
and be ready for an exception if the constant is unavailable.- Parameters:
-
index
- the selected constant - Returns:
-
true
if the selected constant is known by this object to be present,false
if it is known not to be present or
-
asList
default List<Object> asList()
Create a view on this group as aList
view. Any request for a constant through this view will force resolution.- Returns:
- a
List
view on this group which will force resolution
-
asList
default List<Object> asList(Object ifNotPresent)
Create a view on this group as aList
view. Any request for a constant through this view will return the given sentinel value, if the corresponding call toget(int,Object)
would do so.- Parameters:
-
ifNotPresent
- the sentinel value to return if a constant is not present - Returns:
- a
List
view on this group which will not force resolution
-
subGroup
default ConstantGroup subGroup(int start, int end)
Create a view on a sub-sequence of this group.- Parameters:
-
start
- the index to begin the view -
end
- the index to end the view - Returns:
- a view on the selected sub-group
-
copyConstants
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 toend-offset
separate calls toget
, for each index in the range fromoffset
up to but not includingend
. For the first constant that cannot be resolved, aLinkageError
is thrown, but only after preceding constant value have been stored.- Parameters:
-
start
- index of first constant to retrieve -
end
- limiting index of constants to retrieve -
buf
- array to receive the requested values -
pos
- position in the array to offset storing the values - Returns:
- the limiting index,
end
- Throws:
-
LinkageError
- if a constant cannot be resolved
-
copyConstants
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 toend-offset
separate calls toget
, for each index in the range fromoffset
up to but not includingend
. Any constants that cannot be resolved are replaced by the given sentinel value.- Parameters:
-
start
- index of first constant to retrieve -
end
- limiting index of constants to retrieve -
buf
- array to receive the requested values -
pos
- position in the array to offset storing the values -
ifNotPresent
- sentinel value to store if a value is not available - Returns:
- the limiting index,
end
- Throws:
-
LinkageError
- ifresolve
is true and a constant cannot be resolved
-
makeConstantGroup
static ConstantGroup makeConstantGroup(List<Object> constants, Object ifNotPresent, IntFunction<Object> constantProvider)
Make a new constant group with the given constants. The value ofifNotPresent
may be any reference. If this value is encountered as an element of theconstants
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 givenconstantProvider
, by calling it on the index of the missing element. TheconstantProvider
must be stable, in the sense that the outcome of calling it on the same index twice will produce equivalent results. IfconstantProvider
is the null reference, then it will be treated as if it were a function which raisesNoSuchElementException
.- Parameters:
-
constants
- the elements of this constant group -
ifNotPresent
- sentinel value provided instead of a missing constant -
constantProvider
- function to call when a missing constant is resolved - Returns:
- a new constant group with the given constants and resolution behavior
-
makeConstantGroup
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
- the constants of this constant group - Returns:
- a new constant group with the given constants
-
-