io.datarouter.scanner

Interface Scanner<T>

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AdvanceUntilScanner, AdvanceWhileScanner, ArrayScanner, BaseLinkedScanner, BaseScanner, BatchingScanner, CollatingScanner, ComparableScanner, ConcatenatingScanner, DeduplicatingConsecutiveScanner, DistinctScanner, EachScanner, EmptyScanner, FilteringScanner, GeneratingScanner, IteratingScanner, IteratorScanner, LimitingScanner, MappingScanner, NaturalSortingScanner, ObjectScanner, PagingScanner, ParallelMappingScanner, PrefetchingScanner, RandomAccessScanner, RetainingScanner, ReverseListScanner, 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 Summary

Modifier and Type	Method and Description
boolean	advance() Try to update current to the next item, if there is one.
default Scanner<T>	advanceUntil(Predicate<? super T> predicate) Stop the scanner when the predicate matches, excluding the item that caused it to stop.
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.
default boolean	allMatch(Predicate<? super T> predicate) Apply the Predicate to every item in the Scanner, returning whether they all match.
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.
default Scanner<T>	append(Iterable<T> iterable) Concats the provided Iterable items after the current Scanner.
default Scanner<T>	append(Scanner<T> scanner) Concats the provided Scanner after the current Scanner.
default Scanner<T>	append(T... items) Concats the provided array items after the current Scanner.
default <R> R	apply(Function<Scanner<T>,R> function) Beta: Apply the provided Function which returns another Scanner.
default Scanner<List<T>>	batch(int batchSize)
default void	close() Override to cleanup any resources.
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.
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.
default <R,A> R	collect(Collector<? super T,A,R> collector)
default <C extends Collection<T>> C	collect(Supplier<C> collectionSupplier)
default <R> Scanner<R>	concat(Function<? super T,Scanner<R>> mapToScanner) Combine the items from multiple Scanners into a single Scanner.
static <T> Scanner<T>	concat(Iterable<T>... iterables) Combine the items from multiple Iterables into a single Scanner.
static <T> Scanner<T>	concat(Scanner<T>... scanners) Combine the items from multiple Scanners into a single Scanner.
default <R> Scanner<R>	concatIter(Function<? super T,Iterable<R>> mapToIterable) Combine the items from multiple Iterables into a single Scanner.
default long	count() Advance through every item in the Scanner, returning the count of items seen.
T	current()
default Scanner<T>	deduplicateConsecutive() Skips consecutive duplicates.
default Scanner<T>	deduplicateConsecutiveBy(Function<T,?> mapper) Skips items where the mapper outputs the same value as the previous item.
default Scanner<T>	distinct()
default Scanner<T>	distinctBy(Function<T,?> mapper)
default Scanner<T>	each(Consumer<? super T> consumer) Calls Consumer::accept on each item.
static <T> Scanner<T>	empty()
default Scanner<T>	exclude(Predicate<? super T> predicate) Skips items where the Predicate returns true.
default Optional<T>	findFirst() Return the first item encountered in the Scanner, wrapped in an Optional, otherwise Optional.empty() if no items were found.
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.
default Optional<T>	findMax(Comparator<? super T> comparator) Advance through all items, retaining the maximum as computed by the Comparator and returning it.
default Optional<T>	findMin(Comparator<? super T> comparator) Advance through all items, retaining the minimum as computed by the Comparator and returning it.
default Scanner<T>	flush(Consumer<List<T>> consumer)
default void	forEach(Consumer<? super T> action) Perform an operation on each item.
static <T> Scanner<T>	generate(Supplier<T> supplier)
default <K> Map<K,List<T>>	groupBy(Function<T,K> keyFunction)
default <K,V> Map<K,List<V>>	groupBy(Function<T,K> keyFunction, Function<T,V> valueFunction)
default <K,V,M extends Map<K,List<V>>> M	groupBy(Function<T,K> keyFunction, Function<T,V> valueFunction, Supplier<M> mapSupplier)
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)
default boolean	hasAny() Test whether the first advance() returns true.
default Scanner<T>	include(Predicate<? super T> predicate) Skips items where the Predicate returns false.
default boolean	isEmpty() Test whether the first advance() returns false.
default Iterable<T>	iterable()
static <T> Scanner<T>	iterate(T seed, UnaryOperator<T> unaryOperator) Generate a sequence where each item is calculated off the one before it.
default Iterator<T>	iterator()
default Scanner<T>	limit(long limit) Ends the Scanner when the limit has been reached.
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.
default List<T>	list()
default <R> R	listTo(Function<List<T>,R> mapper)
default <R> Scanner<R>	map(Function<? super T,? extends R> mapper) For each input item, outputs the result of Function::apply.
default Scanner<T>	maxN(Comparator<? super T> comparator, int num) Retains the max N items as defined by the comparator and returns a Scanner of them in descending order.
default Scanner<T>	minN(Comparator<? super T> comparator, int num) Retains the min N items as defined by the comparator and returns a Scanner of them in ascending order.
default boolean	noneMatch(Predicate<? super T> predicate) Return false as soon as the Predicate passes, otherwise true if all items fail the Predicate.
static <T> Scanner<T>	of(Iterable<T> iterable) Create a Scanner of items in the Iterable.
static <T> Scanner<T>	of(Iterator<T> iterator) Create a Scanner of items in the Iterator.
static <T> Scanner<T>	of(Stream<T> stream) Create a Scanner of items in the Stream.
static <T> Scanner<T>	of(T... array) Create a Scanner of items in the array.
static <T> Scanner<T>	of(T object) Convert an Object into a Scanner.
static <T> Scanner<T>	ofNullable(T object) Convert an Object into a Scanner if non-null.
default ParallelScanner<T>	parallel(ParallelScannerContext context)
default Scanner<T>	prefetch(ExecutorService exec, int batchSize)
default Optional<T>	reduce(BinaryOperator<T> reducer)
default T	reduce(T seed, BinaryOperator<T> reducer)
default Scanner<RetainingGroup<T>>	retain(int retaining) For retaining a window of N previous items.
default Scanner<T>	reverse() Collect all items into an List and return a Scanner that iterates through them backwards.
default Scanner<T>	sample(long sampleSize, boolean includeLast) Return every Nth item.
default Scanner<T>	shuffle()
default Scanner<T>	skip(long numToSkip) Skip the leading items from the Scanner.
default Scanner<T>	sort()
default Scanner<T>	sort(Comparator<? super T> comparator)
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.
default Stream<T>	stream()
default DoubleStream	streamDoubles(ToDoubleFunction<? super T> mapper)
default IntStream	streamInts(ToIntFunction<? super T> mapper)
default LongStream	streamLongs(ToLongFunction<? super T> mapper)
default List<T>	take(int numToTake) Consume up to N items without closing, only closing the scanner if the last item was consumed.
default void	then(Consumer<Scanner<T>> consumer) Beta: Pass the current Scanner to a method that will Consume this Scanner and return nothing.
default Object[]	toArray()
default Map<T,T>	toMap()
default <K> Map<K,T>	toMap(Function<T,K> keyFunction)
default <K,V> Map<K,V>	toMap(Function<T,K> keyFunction, Function<T,V> valueFunction)
default <K,V> Map<K,V>	toMap(Function<T,K> keyFunction, Function<T,V> valueFunction, BinaryOperator<V> mergeFunction)
default <K,V> Map<K,V>	toMap(Function<T,K> keyFunction, Function<T,V> valueFunction, ScannerToMap.Replace replacePolicy)
default <K,V,M extends Map<K,V>> M	toMapSupplied(Function<T,K> keyFunction, Function<T,V> valueFunction, BinaryOperator<V> mergeFunction, Supplier<M> mapSupplier)
default <K,V,M extends Map<K,V>> M	toMapSupplied(Function<T,K> keyFunction, Function<T,V> valueFunction, ScannerToMap.Replace replacePolicy, Supplier<M> mapSupplier)
default <K,V,M extends Map<K,V>> M	toMapSupplied(Function<T,K> keyFunction, Function<T,V> valueFunction, Supplier<M> mapSupplier)
default <K,M extends Map<K,T>> M	toMapSupplied(Function<T,K> keyFunction, Supplier<M> mapSupplier)

Method Detail

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)

deduplicateConsecutive

default Scanner<T> deduplicateConsecutive()

Skips consecutive duplicates. Lighter weight than distinct() because all elements need not be collected into memory.

deduplicateConsecutiveBy

default Scanner<T> deduplicateConsecutiveBy(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.

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.

findMax

default Optional<T> findMax(Comparator<? super T> comparator)

Advance through all items, retaining the maximum as computed by the Comparator and returning it.

findMin

default Optional<T> findMin(Comparator<? super T> comparator)

Advance through all items, retaining the minimum as computed by the Comparator and returning it.

hasAny

default boolean hasAny()

Test whether the first advance() returns true.

isEmpty

default boolean isEmpty()

Test whether the first advance() returns false.

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)

maxN

default Scanner<T> maxN(Comparator<? super T> comparator,
                        int num)

Retains the max N items as defined by the comparator and returns a Scanner of them in descending order.

minN

default Scanner<T> minN(Comparator<? super T> comparator,
                        int num)

Retains the min N items as defined by the comparator and returns a Scanner of them in ascending order.

reverse

default Scanner<T> reverse()

Collect all items into an List and return a Scanner that iterates through them backwards.

shuffle

default Scanner<T> shuffle()

sort

default Scanner<T> sort()

sort

default Scanner<T> sort(Comparator<? super T> comparator)

toArray

default Object[] toArray()

toMap

default Map<T,T> toMap()

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)