Module dev.metaschema.core
Package dev.metaschema.core.metapath.item

Interface ISequence<ITEM extends IItem>

Type Parameters:
ITEM - the Java type of the items in a sequence
All Superinterfaces:
Collection<ITEM>, ICollectionValue, Iterable<ITEM>, List<ITEM>
public interface ISequence<ITEM extends IItem> extends List<ITEM>, ICollectionValue
Represents an ordered collection of Metapath expression results.

Items is a sequence are typically ordered based on their position in the original node graph based on a depth first ordering.

  • Method Details

    • empty

      @NonNull static <T extends IItem> ISequence<T> empty()
      Get an empty sequence.
      Type Parameters:
      T - the item type
      Returns:
      the empty sequence

    • reusable

      @NonNull default ISequence<ITEM> reusable()
      Ensure the sequence is able to be iterated over multiple times.

      This method can be used to ensure that the sequence can be streamed or iterated over multiple times. Implementations should make sure that when this method is called, the resulting stream is supported by an underlying list.

      Returns:
      a sequence with the same contents, which may be the same sequence

    • safeStream

      @NonNull default Stream<ITEM> safeStream()
      Get a stream guaranteed to be backed by a list.

      This call ensures that the sequence is backed by a List and not a Stream, so the underlying collection can be reused. This is done by first calling reusable().

      Returns:
      the stream

    • stream

      @NonNull Stream<ITEM> stream()
      Get the items in this sequence as a Stream.
      Specified by:
      stream in interface Collection<ITEM extends IItem>
      Returns:
      a stream containing all the items of the sequence

    • getFirstItem

      static <T extends IItem> T getFirstItem(@NonNull ISequence<T> items, boolean requireSingleton)
      Retrieves the first item in a sequence.

      If the sequence is empty, a null result is returned. If requireSingleton is true and the sequence contains more than one item, a TypeMetapathException is thrown.

      Type Parameters:
      T - the item type to return derived from the provided sequence
      Parameters:
      items - the sequence to retrieve the first item from
      requireSingleton - if true then a TypeMetapathException is thrown if the sequence contains more than one item
      Returns:
      null if the sequence is empty, or the item otherwise
      Throws:
      TypeMetapathException - if the sequence contains more than one item and requireSingleton is true

    • getFirstItem

      static <T extends IItem> T getFirstItem(@NonNull Stream<T> items, boolean requireSingleton)
      Retrieves the first item in a stream of items.

      If the sequence is empty, a null result is returned. If requireSingleton is true and the sequence contains more than one item, a TypeMetapathException is thrown.

      Type Parameters:
      T - the item type to return derived from the provided sequence
      Parameters:
      items - the sequence to retrieve the first item from
      requireSingleton - if true then a TypeMetapathException is thrown if the sequence contains more than one item
      Returns:
      null if the sequence is empty, or the item otherwise
      Throws:
      TypeMetapathException - if the sequence contains more than one item and requireSingleton is true

    • getFirstItem

      @Nullable default ITEM getFirstItem(boolean requireSingleton)
      Retrieves the first item in this sequence.

      If the sequence is empty, a null result is returned. If requireSingleton is true and the sequence contains more than one item, a TypeMetapathException is thrown.

      Parameters:
      requireSingleton - if true then a TypeMetapathException is thrown if the sequence contains more than one item
      Returns:
      null if the sequence is empty, or the item otherwise
      Throws:
      TypeMetapathException - if the sequence contains more than one item and requireSingleton is true

    • atomize

      @NonNull default Stream<IAnyAtomicItem> atomize()
      An implementation of XPath 3.1 fn:data supporting item atomization.
      Specified by:
      atomize in interface ICollectionValue
      Returns:
      the atomized result

    • toCollectionValue

      @NonNull default ICollectionValue toCollectionValue()
      Get this sequence as a collection value.
      Returns:
      the collection value

    • flatten

      default Stream<? extends IItem> flatten()
      Description copied from interface: ICollectionValue
      Get the stream of items for the collection value.

      If the collection value contains items, then these items are returned.

      Specified by:
      flatten in interface ICollectionValue
      Returns:
      a stream of related items

    • toSequence

      default ISequence<ITEM> toSequence()
      Get this sequence.
      Specified by:
      toSequence in interface ICollectionValue
      Returns:
      this sequence

    • contentsAsSequence

      default ISequence<?> contentsAsSequence()
      Description copied from interface: ICollectionValue
      Get the collection value as a sequence.

      If the value is already a sequence, the value is returned as a sequence. Otherwise, if the value is an item, what is returned depends on the item type:

      • IArrayItem or IMapItem: the contents of the returned sequence are the items of the array or map. Any member values that are a sequence are flattened.
      • Any other item: A singleton sequence is returned containing the item.
      Specified by:
      contentsAsSequence in interface ICollectionValue
      Returns:
      the resulting sequence

    • map

      static <T extends R, R extends IItem> ISequence<R> map(@NonNull Function<T,R> mapFunction, @NonNull ISequence<T> seq)
      Apply the provided mapFunction to each item in the sequence.
      Type Parameters:
      T - the Java type of the provided items
      R - the Java type of the resulting items
      Parameters:
      mapFunction - the map function to apply to each item in the provided sequence
      seq - the sequence of items to map
      Returns:
      a new sequence containing the mapped items

    • ofCollection

      @NonNull static <ITEM_TYPE extends IItem> ISequence<ITEM_TYPE> ofCollection(@NonNull Collection<ITEM_TYPE> items)
      Returns an unmodifiable sequence containing the provided items.

      If the provided collection is already an ISequence, it is returned unchanged. Otherwise, the collection is wrapped directly without making a defensive copy. If you need a sequence that is independent of the original collection, use copyOf(Collection) instead.

      Type Parameters:
      ITEM_TYPE - the type of items contained in the sequence.
      Parameters:
      items - the items to add to the sequence
      Returns:
      the new sequence, or the same sequence if items is already an ISequence

    • of

      @NonNull static <T extends IItem> ISequence<T> of(@Nullable T item)
      Returns an unmodifiable sequence containing the provided item.

      If the item is null and empty sequence will be created.

      Type Parameters:
      T - the type of items contained in the sequence.
      Parameters:
      item - the item to add to the sequence
      Returns:
      the new sequence

    • of

      @NonNull static <T extends IItem> ISequence<T> of(@NonNull Stream<T> items)
      Returns an unmodifiable sequence containing the provided items.
      Type Parameters:
      T - the type of items contained in the sequence.
      Parameters:
      items - the items to add to the sequence
      Returns:
      the new sequence

    • of

      @NonNull static <T extends IItem> ISequence<T> of()
      Returns an unmodifiable sequence containing zero elements.
      Type Parameters:
      T - the item type
      Returns:
      an empty ISequence

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2)
      Returns an unmodifiable sequence containing two items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2, T e3)
      Returns an unmodifiable sequence containing three elements.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      e3 - the third item
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2, T e3, T e4)
      Returns an unmodifiable sequence containing four items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      e3 - the third item
      e4 - the fourth item
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2, T e3, T e4, T e5)
      Returns an unmodifiable sequence containing five items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      e3 - the third item
      e4 - the fourth item
      e5 - the fifth item
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2, T e3, T e4, T e5, T e6)
      Returns an unmodifiable sequence containing six items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      e3 - the third item
      e4 - the fourth item
      e5 - the fifth item
      e6 - the sixth item
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2, T e3, T e4, T e5, T e6, T e7)
      Returns an unmodifiable sequence containing seven items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      e3 - the third item
      e4 - the fourth item
      e5 - the fifth item
      e6 - the sixth item
      e7 - the seventh item
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2, T e3, T e4, T e5, T e6, T e7, T e8)
      Returns an unmodifiable sequence containing eight items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      e3 - the third item
      e4 - the fourth item
      e5 - the fifth item
      e6 - the sixth item
      e7 - the seventh item
      e8 - the eighth item
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2, T e3, T e4, T e5, T e6, T e7, T e8, T e9)
      Returns an unmodifiable sequence containing nine items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      e3 - the third item
      e4 - the fourth item
      e5 - the fifth item
      e6 - the sixth item
      e7 - the seventh item
      e8 - the eighth item
      e9 - the ninth item
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @NonNull static <T extends IItem> ISequence<T> of(T e1, T e2, T e3, T e4, T e5, T e6, T e7, T e8, T e9, T e10)
      Returns an unmodifiable sequence containing ten items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      e1 - the first item
      e2 - the second item
      e3 - the third item
      e4 - the fourth item
      e5 - the fifth item
      e6 - the sixth item
      e7 - the seventh item
      e8 - the eighth item
      e9 - the ninth item
      e10 - the tenth item
      Returns:
      an IArrayItem containing the specified items
      Throws:
      NullPointerException - if an item is null

    • of

      @SafeVarargs @NonNull static <T extends IItem> ISequence<T> of(@NonNull T... items)
      Returns an unmodifiable sequence containing an arbitrary number of items.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      items - the items to be contained in the list
      Returns:
      an ISequence containing the specified items
      Throws:
      NullPointerException - if an item is null or if the array is null

    • copyOf

      @NonNull static <T extends IItem> ISequence<T> copyOf(Collection<? extends T> collection)
      Returns an unmodifiable sequence containing the items of the given Collection, in its iteration order. The given Collection must not be null, and it must not contain any null items. If the given Collection is subsequently modified, the returned array item will not reflect such modifications.
      Type Parameters:
      T - the ISequence's item type
      Parameters:
      collection - a Collection from which items are drawn, must be non-null
      Returns:
      an ISequence containing the items of the given Collection
      Throws:
      NullPointerException - if collection is null, or if it contains any nulls
      Since:
      10

    • countTypes

      @NonNull default <T extends IItem> Map<Class<? extends T>,Integer> countTypes(@NonNull Set<Class<? extends T>> classes)
      Count the occurrences of items in this sequence that are instances of the provided type classes.

      For each class in the provided set, this method counts how many items in the sequence are assignable to that class.

      Type Parameters:
      T - the base type of the classes to count
      Parameters:
      classes - the set of classes to count occurrences for
      Returns:
      a map from each class to the count of matching items

    • getItemTypes

      @NonNull default List<Class<? extends ITEM>> getItemTypes()
      Get a list of the Java class types for each item in this sequence.
      Returns:
      a list of class types corresponding to each item in the sequence