Module java.base
Package java.lang.invoke

Interface ConstantGroup

  • 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 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_ConstantDynamic 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.

    Since:
    1.10
    • 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), call get(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 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 - 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 a List 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 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 - 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 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 - 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 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 - 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 - if resolve 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 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 - 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