Module org.apache.jena.ontapi
Package org.apache.jena.ontapi.utils

Class Iterators

java.lang.Object
org.apache.jena.ontapi.utils.Iterators
public class Iterators extends Object
Misc utils to work with Iterators, Streams, Collections, etc.
See Also:
  • ExtendedIterator
  • ClosableIterator
  • Iter

  • Constructor Summary

    Constructors
    Constructor
    Description
    Iterators()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static <X, C extends Collection<X>>
    C
    addAll(Iterator<? extends X> source, C target)
    Puts all the remaining items of the given iterator into the collection, and returns this collection itself.
    static <X> boolean
    allMatch(Iterator<X> iterator, Predicate<? super X> predicate)
    Returns whether all elements of the given iterator match the provided predicate.
    static <X> boolean
    anyMatch(Iterator<X> iterator, Predicate<? super X> predicate)
    Returns whether any elements of the given iterator match the provided predicate.
    static <X> Spliterator<X>
    asSpliterator(Iterator<? extends X> iterator, long size, int characteristics)
    Creates a Spliterator using a given Iterator as the source of elements.
    static <X> Stream<X>
    asStream(Iterator<? extends X> iterator)
    Creates a new sequential Stream from the given Iterator, which is expected to deliver nonnull items: it is required that the operation Iterator.next() must not return null if the method Iterator.hasNext() answers true.
    static <X> Stream<X>
    asStream(Iterator<? extends X> iterator, int characteristics)
    Constructs a new sequential Stream from the given Iterator, with the specified characteristics.
    static <X> Stream<X>
    asStream(Iterator<? extends X> iterator, long size, int characteristics)
    Constructs a new sequential Stream from the given Iterator, with the specified characteristics and estimated size.
    static <X> Stream<X>
    asStream(org.apache.jena.util.iterator.ExtendedIterator<? extends X> iterator)
    Creates a new sequential Stream from the given ExtendedIterator.
    static void
    close(Iterator<?> iterator)
    Closes iterator if it is CloseableIterator.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    concat(org.apache.jena.util.iterator.ExtendedIterator<? extends X>... iterators)
    Creates a lazily concatenated Extended Iterator whose elements are all the elements of the given iterators.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    concat(org.apache.jena.util.iterator.ExtendedIterator<? extends X> a, org.apache.jena.util.iterator.ExtendedIterator<? extends X> b)
    Creates a lazily concatenated Extended Iterator whose elements are all the elements of the first iterator followed by all the elements of the second iterator.
    static long
    count(Iterator<?> iterator)
    Returns the count of elements in the given iterator.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    create(Collection<? extends X> members)
    Creates a new Extended Iterator} over all elements of the specified collection.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    create(Supplier<Iterator<? extends X>> provider)
    Creates a new Extended Iterator over all elements of an iterator which will be created by the provider on first iteration.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    create(Iterator<? extends X> iterator)
    Answers an ExtendedIterator returning the elements of the specified iterator.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    distinct(org.apache.jena.util.iterator.ExtendedIterator<X> base)
    Returns an Extended Iterator consisting of the distinct elements (according to Object.equals(Object)) of the given iterator.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    filter(org.apache.jena.util.iterator.ExtendedIterator<X> iterator, Predicate<? super X> predicate)
    Returns an extended iterator consisting of the elements of the specified extended iterator that match the given predicate.
    static <X> Optional<X>
    findFirst(Iterator<X> iterator)
    Returns an Optional describing the first element of the iterator, or an empty Optional if the iterator is empty.
    static <T, F> org.apache.jena.util.iterator.ExtendedIterator<T>
    flatMap(org.apache.jena.util.iterator.ExtendedIterator<F> base, Function<? super F,? extends Iterator<? extends T>> mapper)
    Returns an Extended Iterator consisting of the results of replacing each element of the given base iterator with the contents of a mapped iterator produced by applying the provided mapping function (map) to each element.
    static <X> void
    forEach(Iterator<X> iterator, Consumer<X> action)
    Performs forEach.
    static <X> Stream<X>
    fromSet(Supplier<Set<X>> getAsSet)
    Creates a Stream for a future Set, which is produced by the factory-parameter getAsSet.
    static boolean
    hasAtLeast(Iterator<?> iterator, int n)
    Answers true iff the given iterator has more than n or equal to n elements.
    static boolean
    hasExactly(Iterator<?> iterator, int n)
    Answers true iff the given iterator has exactly n elements.
    static <X> boolean
    noneMatch(Iterator<X> iterator, Predicate<? super X> predicate)
    Returns whether no elements of the given iterator match the provided predicate.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    of()
    Creates a new Extended Iterator} containing nothing.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    of(X item)
    Creates a new Extended Iterator} containing a single specified element.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    of(X... members)
    Creates a new Extended Iterator} containing the specified elements.
    static <X> org.apache.jena.util.iterator.ExtendedIterator<X>
    peek(org.apache.jena.util.iterator.ExtendedIterator<X> base, Consumer<? super X> action)
    Returns an Extended Iterator consisting of the elements of the given base iterator, additionally performing the provided action on each element as elements are consumed from the resulting iterator.
    static <X> Set<X>
    takeAsSet(Iterator<? extends X> source, int number)
    Takes the specified number of items from the source iterator.
    static <X, K, V, M extends Map<K, V>>
    M
    toMap(Iterator<X> iterator, Function<? super X,? extends K> keyMapper, Function<? super X,? extends V> valueMapper, BinaryOperator<V> mergeFunction, Supplier<M> mapSupplier)
    Returns a Map (of the type of M) whose keys and values are the result of applying the provided mapping functions to the input elements.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Iterators

      public Iterators()

  • Method Details

    • asStream

      public static <X> Stream<X> asStream(org.apache.jena.util.iterator.ExtendedIterator<? extends X> iterator)
      Creates a new sequential Stream from the given ExtendedIterator. Takes care about degenerate cases empty and single-element iterator.
      Type Parameters:
      X - anything
      Parameters:
      iterator - ExtendedIterator of X-elements
      Returns:
      a Stream of X
      See Also:

    • asStream

      public static <X> Stream<X> asStream(Iterator<? extends X> iterator)
      Creates a new sequential Stream from the given Iterator, which is expected to deliver nonnull items: it is required that the operation Iterator.next() must not return null if the method Iterator.hasNext() answers true. The method asStream(Iterator, int) with the second parameter equals 0 can be used to create a Stream for an iterator that may deliver nulls.

      If the given parameter is ClosableIterator, remember to call BaseStream.close() explicitly if the iterator is not exhausted (i.e. in case Iterator.hasNext() is still true). It should be done for all short-circuiting terminal operations such as Stream.findFirst(), Stream.findAny(), Stream.anyMatch(Predicate) etc.

      Type Parameters:
      X - the type of iterator-items
      Parameters:
      iterator - Iterator that delivers nonnull elements, cannot be null
      Returns:
      Stream

    • asStream

      public static <X> Stream<X> asStream(Iterator<? extends X> iterator, int characteristics)
      Constructs a new sequential Stream from the given Iterator, with the specified characteristics. If the given parameter is ClosableIterator, an explicit call to the BaseStream.close() method is required for all short-circuiting terminal operations.
      Type Parameters:
      X - the type of iterator-items
      Parameters:
      iterator - Iterator, the Spliterator's source, not null
      characteristics - int, characteristics of the Spliterator's source
      Returns:
      a non-parallel Stream, that wraps the iterator with the given characteristics

    • asStream

      public static <X> Stream<X> asStream(Iterator<? extends X> iterator, long size, int characteristics)
      Constructs a new sequential Stream from the given Iterator, with the specified characteristics and estimated size. If the given parameter is ClosableIterator, an explicit call to the BaseStream.close() method is required for all short-circuiting terminal operations.
      Type Parameters:
      X - the type of iterator-items
      Parameters:
      iterator - Iterator, the Spliterator's source, not null
      size - long, a Spliterator's estimates size, positive number or -1
      characteristics - int, characteristics of the Spliterator's source
      Returns:
      a non-parallel Stream, that wraps the iterator with the given parameters

    • asSpliterator

      public static <X> Spliterator<X> asSpliterator(Iterator<? extends X> iterator, long size, int characteristics)
      Creates a Spliterator using a given Iterator as the source of elements. If the size is not -1, the returned Spliterator will report this number as the initial estimated size.
      Type Parameters:
      X - the type of iterator-items
      Parameters:
      iterator - Iterator, not null
      size - long, a positive number or -1
      characteristics - int, characteristics of the spliterator's source
      Returns:
      Spliterator
      Throws:
      NullPointerException - if the given iterator is null

    • fromSet

      public static <X> Stream<X> fromSet(Supplier<Set<X>> getAsSet)
      Creates a Stream for a future Set, which is produced by the factory-parameter getAsSet. The produced Set must not change and must not contain null.
      Type Parameters:
      X - the type of items
      Parameters:
      getAsSet - Supplier that produces a Set of X
      Returns:
      distinct sequential Stream
      See Also:

    • flatMap

      public static <T, F> org.apache.jena.util.iterator.ExtendedIterator<T> flatMap(org.apache.jena.util.iterator.ExtendedIterator<F> base, Function<? super F,? extends Iterator<? extends T>> mapper)
      Returns an Extended Iterator consisting of the results of replacing each element of the given base iterator with the contents of a mapped iterator produced by applying the provided mapping function (map) to each element. A functional equivalent of Stream.flatMap(Function), but for ExtendedIterators.
      Type Parameters:
      F - the element type of the base iterator (from)
      T - the element type of the new iterator (to)
      Parameters:
      base - ExtendedIterator with elements of type F
      mapper - Function map-function with Object of type of F (or any super type) as an input, and an Iterator of type T (or any extended type) as an output
      Returns:
      new ExtendedIterator of type F

    • concat

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> concat(org.apache.jena.util.iterator.ExtendedIterator<? extends X> a, org.apache.jena.util.iterator.ExtendedIterator<? extends X> b)
      Creates a lazily concatenated Extended Iterator whose elements are all the elements of the first iterator followed by all the elements of the second iterator. A functional equivalent of Stream.concat(Stream, Stream), but for ExtendedIterators.
      Type Parameters:
      X - the type of iterator elements
      Parameters:
      a - the first iterator
      b - the second iterator
      Returns:
      the concatenation of the two input iterators
      See Also:

    • concat

      @SafeVarargs public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> concat(org.apache.jena.util.iterator.ExtendedIterator<? extends X>... iterators)
      Creates a lazily concatenated Extended Iterator whose elements are all the elements of the given iterators. If the specified array has length equals 2, than this method is equivalent to the method concat(ExtendedIterator, ExtendedIterator)). An ExtendedIterator-based functional equivalent of the expression Stream#of(Stream, ..., Stream).flatMap(Function.identity()).
      Type Parameters:
      X - the type of iterator elements
      Parameters:
      iterators - Array of iterators
      Returns:
      all input elements as a single ExtendedIterator of type X
      See Also:

    • filter

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> filter(org.apache.jena.util.iterator.ExtendedIterator<X> iterator, Predicate<? super X> predicate)
      Returns an extended iterator consisting of the elements of the specified extended iterator that match the given predicate. A functional equivalent of Stream.filter(Predicate), but for ExtendedIterators.
      Type Parameters:
      X - the element type of the input and output iterators
      Parameters:
      iterator - ExtendedIterator with elements of type X
      predicate - Predicate to apply to elements of the iterator
      Returns:
      a new iterator

    • peek

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> peek(org.apache.jena.util.iterator.ExtendedIterator<X> base, Consumer<? super X> action)
      Returns an Extended Iterator consisting of the elements of the given base iterator, additionally performing the provided action on each element as elements are consumed from the resulting iterator. A functional equivalent of Stream.peek(Consumer), but for ExtendedIterators.
      Type Parameters:
      X - the element type of the input and output iterators
      Parameters:
      base - ExtendedIterator with elements of type X
      action - Consumer action
      Returns:
      new ExtendedIterator of type X

    • distinct

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> distinct(org.apache.jena.util.iterator.ExtendedIterator<X> base)
      Returns an Extended Iterator consisting of the distinct elements (according to Object.equals(Object)) of the given iterator. A functional equivalent of Stream.distinct(), but for ExtendedIterators. Warning: the result is temporary stored in memory!
      Type Parameters:
      X - the element type of the input and output iterators
      Parameters:
      base - ExtendedIterator with elements of type X
      Returns:
      new ExtendedIterator of type X without duplicates

    • anyMatch

      public static <X> boolean anyMatch(Iterator<X> iterator, Predicate<? super X> predicate)
      Returns whether any elements of the given iterator match the provided predicate. A functional equivalent of Stream.anyMatch(Predicate), but for Iterators.
      Type Parameters:
      X - the element type of the iterator
      Parameters:
      iterator - Iterator with elements of type X
      predicate - Predicate to apply to elements of the iterator
      Returns:
      true if any elements of the stream match the provided predicate, otherwise false
      See Also:

    • allMatch

      public static <X> boolean allMatch(Iterator<X> iterator, Predicate<? super X> predicate)
      Returns whether all elements of the given iterator match the provided predicate. A functional equivalent of Stream.allMatch(Predicate), but for Iterators.
      Type Parameters:
      X - the element type of the iterator
      Parameters:
      iterator - Iterator with elements of type X
      predicate - Predicate to apply to elements of the iterator
      Returns:
      true if either all elements of the iterator match the provided predicate or the iterator is empty, otherwise false
      See Also:

    • noneMatch

      public static <X> boolean noneMatch(Iterator<X> iterator, Predicate<? super X> predicate)
      Returns whether no elements of the given iterator match the provided predicate. A functional equivalent of Stream.noneMatch(Predicate), but for Iterators.
      Type Parameters:
      X - the element type of the iterator
      Parameters:
      iterator - Iterator with elements of type X
      predicate - Predicate to apply to elements of the iterator
      Returns:
      true if either no elements of the iterator match the provided predicate or the iterator is empty, otherwise false
      See Also:

    • findFirst

      public static <X> Optional<X> findFirst(Iterator<X> iterator)
      Returns an Optional describing the first element of the iterator, or an empty Optional if the iterator is empty. A functional equivalent of Stream.findFirst(), but for Iterators. Warning: the method closes the specified iterator, so it is not possible to reuse it after calling this method.
      Type Parameters:
      X - the element type of the iterator
      Parameters:
      iterator - Iterator, not null
      Returns:
      Optional of X
      Throws:
      NullPointerException - if the element selected is null

    • count

      public static long count(Iterator<?> iterator)
      Returns the count of elements in the given iterator. A functional equivalent of Stream.count(), but for Iterators. Warning: the method closes the specified iterator, so it is not possible to reuse it after.
      Parameters:
      iterator - Iterator, not null
      Returns:
      long, the count of elements in the given iterator

    • hasAtLeast

      public static boolean hasAtLeast(Iterator<?> iterator, int n)
      Answers true iff the given iterator has more than n or equal to n elements.
      Parameters:
      n - positive number
      iterator - Iterator, not null
      Returns:
      true if the specified iterator has at least n elements

    • hasExactly

      public static boolean hasExactly(Iterator<?> iterator, int n)
      Answers true iff the given iterator has exactly n elements.
      Parameters:
      n - positive number
      iterator - Iterator, not null
      Returns:
      true if the specified iterator has exactly n elements

    • forEach

      public static <X> void forEach(Iterator<X> iterator, Consumer<X> action)
      Performs forEach. On finish iteration, the iterator will be closed.
      Type Parameters:
      X - any
      Parameters:
      iterator - Iterator, not null
      action - Consumer accepting X

    • addAll

      public static <X, C extends Collection<X>> C addAll(Iterator<? extends X> source, C target)
      Puts all the remaining items of the given iterator into the collection, and returns this collection itself. This is a terminal operation.
      Type Parameters:
      X - the element type of the iterator, not null
      C - the Collection type, not null
      Parameters:
      source - the Iterator with elements of type X
      target - the collection of type C
      Returns:
      C, the same instance as specified

    • takeAsSet

      public static <X> Set<X> takeAsSet(Iterator<? extends X> source, int number)
      Takes the specified number of items from the source iterator.
      Type Parameters:
      X - any
      Parameters:
      source - Iterator
      number - int, positive
      Returns:
      Set

    • toMap

      public static <X, K, V, M extends Map<K, V>> M toMap(Iterator<X> iterator, Function<? super X,? extends K> keyMapper, Function<? super X,? extends V> valueMapper, BinaryOperator<V> mergeFunction, Supplier<M> mapSupplier)
      Returns a Map (of the type of M) whose keys and values are the result of applying the provided mapping functions to the input elements. A functional equivalent of stream.collect(Collectors.toMap(...)), but for plain Iterators. This method makes no guarantees about synchronization or atomicity properties of it.
      Type Parameters:
      X - the type of the input elements
      K - the output type of the key mapping function
      V - the output type of the value mapping function
      M - the type of the resulting Map
      Parameters:
      iterator - input elements in the form of Iterator
      keyMapper - a mapping function to produce keys
      valueMapper - a mapping function to produce values
      mergeFunction - a merge function, used to resolve collisions between values associated with the same key, as supplied to Map.merge(Object, Object, BiFunction)
      mapSupplier - a function which returns new, empty Map into which the results will be inserted
      Returns:
      a Map whose keys are the result of applying a key mapping function to the input elements, and whose values are the result of applying a value mapping function to all input elements equal to the key and combining them using the merge function
      See Also:

    • close

      public static void close(Iterator<?> iterator)
      Closes iterator if it is CloseableIterator.
      Parameters:
      iterator - Iterator

    • of

      @SafeVarargs public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> of(X... members)
      Creates a new Extended Iterator} containing the specified elements.
      Type Parameters:
      X - the element type of the new iterator
      Parameters:
      members - Array of elements of the type X
      Returns:
      a fresh ExtendedIterator instance

    • of

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> of()
      Creates a new Extended Iterator} containing nothing.
      Type Parameters:
      X - the element type of the new iterator
      Returns:
      a fresh ExtendedIterator instance

    • of

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> of(X item)
      Creates a new Extended Iterator} containing a single specified element.
      Type Parameters:
      X - the element type of the new iterator
      Parameters:
      item - - an object of type X
      Returns:
      a fresh ExtendedIterator instance

    • create

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> create(Collection<? extends X> members)
      Creates a new Extended Iterator} over all elements of the specified collection.
      Type Parameters:
      X - the element type of the new iterator
      Parameters:
      members - Collection of elements of the type X
      Returns:
      a fresh ExtendedIterator instance

    • create

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> create(Iterator<? extends X> iterator)
      Answers an ExtendedIterator returning the elements of the specified iterator. If the given iterator is itself an ExtendedIterator, return that; otherwise wrap iterator.
      Type Parameters:
      X - the element type of the iterator
      Parameters:
      iterator - Iterator, not null
      Returns:
      ExtendedIterator instance

    • create

      public static <X> org.apache.jena.util.iterator.ExtendedIterator<X> create(Supplier<Iterator<? extends X>> provider)
      Creates a new Extended Iterator over all elements of an iterator which will be created by the provider on first iteration. The returned iterator does not contain any elements, but they will be derived at once when calling any of the ExtendedIterator methods.

      The idea is to provide a truly lazy iterator and, subsequently, a stream (through the asStream(Iterator) method). When any distinct operation (i.e. distinct(ExtendedIterator) or Stream.distinct()) is used, it, in fact, collects on demand an in-memory Set containing all elements, but it will be appeared in process and an iterator or a stream initially weighs nothing. This method allows achieving a similar behavior: when creating an ExtendedIterator does not weight anything, but it materializes itself when processing. Therefore, operations such as (stream-1 + stream-2).findFirst() will demand less memory.

      The returned iterator is not thread-safe, just as like any other RDF extended iterator we work with.

      Type Parameters:
      X - the element type of the new iterator
      Parameters:
      provider - Supplier deriving nonnull Iterator, cannot be null
      Returns:
      a fresh ExtendedIterator instance wrapping a feature iterator