Package io.datarouter.scanner

Interface Scanner<T>

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
AdvanceUntilScanner, AdvanceWhileScanner, ArrayScanner, BaseLinkedScanner, BaseScanner, BatchingScanner, CollatingScanner, ComparableScanner, ConcatenatingScanner, DeduplicatingScanner, DistinctScanner, EachScanner, EmptyScanner, FilteringScanner, GeneratingScanner, IteratingScanner, IteratorScanner, LimitingScanner, MappingScanner, NaturalSortingScanner, ObjectScanner, PagingScanner, ParallelMappingScanner, PrefetchingScanner, RandomAccessScanner, RetainingScanner, SamplingScanner, ShufflingScanner, SortingScanner, SplittingScanner, SteppingScanner, StreamScanner
public interface Scanner<T>
extends Closeable
A form of iterator that operates as lazily as possible, not knowing if the next item is available until advancing and dropping the reference to the previous item. Default interface methods are included so Scanners can be assembled into a pipeline before advancing through the items. Similar to Iterator or Stream, a Scanner can only be consumed once.

  • Method Details

    • advance

      boolean advance()
      Try to update current to the next item, if there is one.
      Returns:
      True if it advanced

    • current

      T current()
      Returns:
      The current item, only valid if advance() returned true

    • close

      default void close()
      Override to cleanup any resources. The call should be propagated to all parent scanners. In the infrequent case of calling advance/current in an application, the Scanner should be explicitly closed. Because the included Scanner operations will close themselves when they fail to advance, it frequently a no-op for the application, unless closing the scanner before it stops advancing.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • forEach

      default void forEach​(Consumer<? super T> action)
      Perform an operation on each item.
      Parameters:
      action - Consumer::accept is performed on each item

    • take

      default List<T> take​(int numToTake)
      Consume up to N items without closing, only closing the scanner if the last item was consumed.
      Parameters:
      numToTake - Maximum returned items
      Returns:
      List with up to numToTake items

    • empty

      static <T> Scanner<T> empty()
      Returns:
      A scanner that immediately returns advance=false

    • generate

      static <T> Scanner<T> generate​(Supplier<T> supplier)
      Parameters:
      supplier - Supplier that generates items indefinitely
      Returns:
      A scanner that advances through the items

    • iterate

      static <T> Scanner<T> iterate​(T seed, UnaryOperator<T> unaryOperator)
      Generate a sequence where each item is calculated off the one before it.
      Parameters:
      seed - The first item
      unaryOperator - A function applied to the current item to generate the next item
      Returns:
      A scanner that advances through the items

    • ofNullable

      static <T> Scanner<T> ofNullable​(T object)
      Convert an Object into a Scanner if non-null.
      Parameters:
      object - A nullable Object
      Returns:
      An empty scanner if the Object was null, otherwise a single-item Scanner with the Object

    • of

      static <T> Scanner<T> of​(T object)
      Convert an Object into a Scanner.
      Parameters:
      object - A non-null Object
      Returns:
      A single-item Scanner with the Object

    • of

      @SafeVarargs static <T> Scanner<T> of​(T... array)
      Create a Scanner of items in the array.
      Parameters:
      array - An array or var-args
      Returns:
      A Scanner that visits each item in the array

    • of

      static <T> Scanner<T> of​(Iterator<T> iterator)
      Create a Scanner of items in the Iterator.
      Parameters:
      iterator - An Iterator
      Returns:
      A Scanner that visits each item in the Iterator

    • of

      static <T> Scanner<T> of​(Iterable<T> iterable)
      Create a Scanner of items in the Iterable.
      Parameters:
      iterable - An Iterable, which includes any Collection
      Returns:
      A Scanner that visits each item in the Iterable

    • of

      static <T> Scanner<T> of​(Stream<T> stream)
      Create a Scanner of items in the Stream.
      Parameters:
      stream - A Stream
      Returns:
      A Scanner that visits each item in the Stream

    • concatIter

      default <R> Scanner<R> concatIter​(Function<? super T,​Iterable<R>> mapToIterable)
      Combine the items from multiple Iterables into a single Scanner. Use Function.identity() if they're already Iterables.
      Parameters:
      mapToIterable - Converts the input items into the Iterables to be combined
      Returns:
      Scanner containing the items from all input Iterables, starting with the first

    • concat

      default <R> Scanner<R> concat​(Function<? super T,​Scanner<R>> mapToScanner)
      Combine the items from multiple Scanners into a single Scanner. Use Function.identity() if they're already Scanners.
      Parameters:
      mapToScanner - Converts the input items into the Scanners to be combined
      Returns:
      Scanner containing the items from all input Scanners, starting with the first

    • concat

      @SafeVarargs static <T> Scanner<T> concat​(Scanner<T>... scanners)
      Combine the items from multiple Scanners into a single Scanner.
      Parameters:
      scanners - Input Scanners to be combined
      Returns:
      Scanner containing the items from all input Scanners, starting with the first

    • concat

      @SafeVarargs static <T> Scanner<T> concat​(Iterable<T>... iterables)
      Combine the items from multiple Iterables into a single Scanner.
      Parameters:
      iterables - Input Iterables to be combined, where Iterable includes any Collection
      Returns:
      Scanner containing the items from all input Iterables, starting with the first

    • append

      default Scanner<T> append​(Scanner<T> scanner)
      Concats the provided Scanner after the current Scanner.

    • append

      default Scanner<T> append​(T... items)
      Concats the provided array items after the current Scanner.

    • append

      default Scanner<T> append​(Iterable<T> iterable)
      Concats the provided Iterable items after the current Scanner.

    • collate

      default <R> Scanner<R> collate​(Function<? super T,​Scanner<R>> mapper)
      Similar to the merge phase of a merge sort, assuming the input Scanners are sorted. Converts the input items to Scanners and feeds all Scanners through a PriorityQueue with "natural" comparator ordering.
      Returns:
      Assuming input scanners are sorted, a single Scanner of all items in sorted order.

    • collate

      default <R> Scanner<R> collate​(Function<? super T,​Scanner<R>> mapper, Comparator<? super R> comparator)
      Similar to the merge phase of a merge sort, assuming the input Scanners are sorted. Converts the input items to Scanners and feeds all Scanners through a PriorityQueue with the provided comparator.
      Returns:
      Assuming input scanners are sorted according to the comparator, a single Scanner of all items in sorted order.

    • link

      default <R> Scanner<R> link​(Function<Scanner<T>,​BaseLinkedScanner<T,​R>> scannerBuilder)
      A caller can extend BaseLinkedScanner, which has exception handling logic, and fluently include it in the Scanner pipeline.
      Parameters:
      scannerBuilder - Function to build the BaseLinkedScanner

    • apply

      default <R> R apply​(Function<Scanner<T>,​R> function)
      Beta: Apply the provided Function which returns another Scanner. The other Scanner is now responsible for consuming the Scanner, or returning a continued Scanner.
      Parameters:
      function - A method reference that accepts this Scanner

    • then

      default void then​(Consumer<Scanner<T>> consumer)
      Beta: Pass the current Scanner to a method that will Consume this Scanner and return nothing.
      Parameters:
      consumer - A method reference that accepts this Scanner

    • parallel

      default ParallelScanner<T> parallel​(ParallelScannerContext context)

    • prefetch

      default Scanner<T> prefetch​(ExecutorService exec, int batchSize)

    • advanceUntil

      default Scanner<T> advanceUntil​(Predicate<? super T> predicate)
      Stop the scanner when the predicate matches, excluding the item that caused it to stop.

    • advanceWhile

      default Scanner<T> advanceWhile​(Predicate<? super T> predicate)
      Stop the scanner when the predicated fails to match, excluding the item that caused it to stop.

    • batch

      default Scanner<List<T>> batch​(int batchSize)

    • deduplicate

      default Scanner<T> deduplicate()
      Skips consecutive duplicates. Lighter weight than distinct() because all elements need not be collected into memory.

    • deduplicateBy

      default Scanner<T> deduplicateBy​(Function<T,​?> mapper)
      Skips items where the mapper outputs the same value as the previous item. Lighter weight than distinctBy() because all elements need not be collected into memory.

    • each

      default Scanner<T> each​(Consumer<? super T> consumer)
      Calls Consumer::accept on each item.

    • exclude

      default Scanner<T> exclude​(Predicate<? super T> predicate)
      Skips items where the Predicate returns true.

    • include

      default Scanner<T> include​(Predicate<? super T> predicate)
      Skips items where the Predicate returns false.

    • limit

      default Scanner<T> limit​(long limit)
      Ends the Scanner when the limit has been reached.

    • map

      default <R> Scanner<R> map​(Function<? super T,​? extends R> mapper)
      For each input item, outputs the result of Function::apply.

    • retain

      default Scanner<RetainingGroup<T>> retain​(int retaining)
      For retaining a window of N previous items.
      Parameters:
      retaining - The number of extra items to retain, in addition to the Scanner's default of zero.
      Returns:
      A RetainingGroup allowing you to call peekBack(1), to get the previous current() value. Calling peekBack with a value higher than the "retaining" param will cause an exception.

    • sample

      default Scanner<T> sample​(long sampleSize, boolean includeLast)
      Return every Nth item.
      Parameters:
      sampleSize - A Scanner with 8 items and sample size 8 will return either 2 or 3 results.
      includeLast - Whether to include the last item in case of a partial sample.
      Returns:
      A Scanner of the sampled items.

    • skip

      default Scanner<T> skip​(long numToSkip)
      Skip the leading items from the Scanner.
      Parameters:
      numToSkip - Skips up to this many items, or fewer if the Scanner had fewer items.
      Returns:
      A Scanner with the remaining items, or an empty Scanner if all items were dropped.

    • splitBy

      default Scanner<Scanner<T>> splitBy​(Function<T,​?> mapper)
      Applies the Function to each item in the Scanner, returning a new Scanner each time the mapped value changes. Similar to groupBy on an unbounded amount of data, but will result in multiple of the same groupings depending on the order of the input data. Useful in the case of Scanning child objects and grouping by a parent.

    • allMatch

      default boolean allMatch​(Predicate<? super T> predicate)
      Apply the Predicate to every item in the Scanner, returning whether they all match.

    • anyMatch

      default boolean anyMatch​(Predicate<? super T> predicate)
      Apply the predicate to each item in the Scanner until one matches, returning true, otherwise return false if the Scanner is consumed with no matches.

    • count

      default long count()
      Advance through every item in the Scanner, returning the count of items seen.

    • findAny

      default Optional<T> findAny()
      Return any item encountered in the Scanner, wrapped in an Optional, otherwise Optional.empty() if no items were found.

    • findFirst

      default Optional<T> findFirst()
      Return the first item encountered in the Scanner, wrapped in an Optional, otherwise Optional.empty() if no items were found.

    • findLast

      default Optional<T> findLast()
      Advance through every item in the Scanner, returning the last item wrapped in an Optional, otherwise Optional.empty() if the Scanner had no items.

    • hasAny

      default boolean hasAny()
      Test whether the first advance() returns true.

    • isEmpty

      default boolean isEmpty()
      Test whether the first advance() returns false.

    • max

      default Optional<T> max​(Comparator<? super T> comparator)
      Advance through all items, retaining the maximum as computed by the Comparator and returning it.

    • min

      default Optional<T> min​(Comparator<? super T> comparator)
      Advance through all items, retaining the minimum as computed by the Comparator and returning it.

    • noneMatch

      default boolean noneMatch​(Predicate<? super T> predicate)
      Return false as soon as the Predicate passes, otherwise true if all items fail the Predicate.

    • reduce

      default Optional<T> reduce​(BinaryOperator<T> reducer)

    • reduce

      default T reduce​(T seed, BinaryOperator<T> reducer)

    • collect

      default <C extends Collection<T>> C collect​(Supplier<C> collectionSupplier)

    • collect

      default <R,​ A> R collect​(Collector<? super T,​A,​R> collector)

    • distinct

      default Scanner<T> distinct()

    • distinctBy

      default Scanner<T> distinctBy​(Function<T,​?> mapper)

    • flush

      default Scanner<T> flush​(Consumer<List<T>> consumer)

    • list

      default List<T> list()

    • listTo

      default <R> R listTo​(Function<List<T>,​R> mapper)

    • shuffle

      default Scanner<T> shuffle()

    • sorted

      default Scanner<T> sorted()

    • sorted

      default Scanner<T> sorted​(Comparator<? super T> comparator)

    • toArray

      default Object[] toArray()

    • toMap

      default <K> Map<K,​T> toMap​(Function<T,​K> keyFunction)

    • toMap

      default <K,​ V> Map<K,​V> toMap​(Function<T,​K> keyFunction, Function<T,​V> valueFunction)

    • toMap

      default <K,​ V> Map<K,​V> toMap​(Function<T,​K> keyFunction, Function<T,​V> valueFunction, ScannerToMap.Replace replacePolicy)

    • toMap

      default <K,​ V> Map<K,​V> toMap​(Function<T,​K> keyFunction, Function<T,​V> valueFunction, BinaryOperator<V> mergeFunction)

    • toMapSupplied

      default <K,​ M extends Map<K,​ T>> M toMapSupplied​(Function<T,​K> keyFunction, Supplier<M> mapSupplier)

    • toMapSupplied

      default <K,​ V,​ M extends Map<K,​ V>> M toMapSupplied​(Function<T,​K> keyFunction, Function<T,​V> valueFunction, Supplier<M> mapSupplier)

    • toMapSupplied

      default <K,​ V,​ M extends Map<K,​ V>> M toMapSupplied​(Function<T,​K> keyFunction, Function<T,​V> valueFunction, ScannerToMap.Replace replacePolicy, Supplier<M> mapSupplier)

    • toMapSupplied

      default <K,​ V,​ M extends Map<K,​ V>> M toMapSupplied​(Function<T,​K> keyFunction, Function<T,​V> valueFunction, BinaryOperator<V> mergeFunction, Supplier<M> mapSupplier)

    • groupBy

      default <K> Map<K,​List<T>> groupBy​(Function<T,​K> keyFunction)

    • groupBy

      default <K,​ V> Map<K,​List<V>> groupBy​(Function<T,​K> keyFunction, Function<T,​V> valueFunction)

    • groupBy

      default <K,​ V,​ M extends Map<K,​ List<V>>> M groupBy​(Function<T,​K> keyFunction, Function<T,​V> valueFunction, Supplier<M> mapSupplier)

    • groupBy

      default <K,​ V,​ C extends Collection<V>,​ M extends Map<K,​ C>> M groupBy​(Function<T,​K> keyFunction, Function<T,​V> valueFunction, Supplier<M> mapSupplier, Supplier<C> collectionSupplier)

    • iterator

      default Iterator<T> iterator()

    • iterable

      default Iterable<T> iterable()

    • stream

      default Stream<T> stream()

    • streamInts

      default IntStream streamInts​(ToIntFunction<? super T> mapper)

    • streamLongs

      default LongStream streamLongs​(ToLongFunction<? super T> mapper)

    • streamDoubles

      default DoubleStream streamDoubles​(ToDoubleFunction<? super T> mapper)