Package com.storedobject.core

Class ObjectIterator<O extends StoredObject>

java.lang.Object

com.storedobject.core.ObjectIterator<O>

Type Parameters:

O - Type of objects of the iterator.

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<O>, Iterator<O>

public abstract class ObjectIterator<O extends StoredObject>
extends Object
implements Iterator<O>, Iterable<O>, Closeable

Helper class that allows you to iterate through objects retrieved from the DB. Several methods of StoredObject returns an instance of this class.

Note: Please make sure that you call the close() method to release DB resources held by this instance once the usage over. However, if you iterate through the whole list or if you use a terminal operation, it will be closed automatically.

Author:

Syam

Method Summary

Modifier and Type	Method	Description
ObjectIterator<O>	add(ObjectIterator<O> iterator)	Concatenate another instance.
final ObjectIterator<O>	add(O object)	Add one object to the tail of this instance.
ObjectIterator<O>	addToHead(ObjectIterator<O> iterator)	Concatenate another instance by adding to the head of it.
final ObjectIterator<O>	addToHead(O object)	Add one object to the head of this instance so that it will be next entry returned.
boolean	allMatch(Predicate<? super O> predicate)	Check whether all objects are matching the given filter or not.
boolean	anyMatch(Predicate<? super O> predicate)	Check whether any object is matching the given filter or not.
double	average(ToDoubleFunction<? super O> function)	Get the average.
void	close()	Close this instance and release all associated resources.
Collection<O>	collectAll()	Deprecated.
Collection<O>	collectAll(Collection<O> collection)	Collect all entries to a given collection.
<T> Collection<T>	collectAll(Collection<T> collection, Function<O,T> convertor)	Collect all entries to a given collection after converting it to another type.
<T> Collection<T>	collectAll(Function<O,T> convertor)	Collect all entries to a collection after converting it to another type.
ObjectIterator<O>	consumeWhile(Predicate<O> predicate, Consumer<O> consumer)	Consume objects while a given predicate is true.
<TO extends StoredObject> ObjectIterator<TO>	convert(ObjectConverter<O,TO> converter)	Convert this iterator to another type.
long	count()	Get the count.
long	count(Predicate<? super O> filter)	Get the count after applying a filter.
static <T extends StoredObject> ObjectIterator<T>	create()	Create an empty iterator.
static <FROM extends StoredObject, TO extends StoredObject> ObjectIterator<TO>	create(ObjectIterator<FROM> iterator, ObjectConverter<FROM,TO> converter)	Create an iterator from the given iterator with conversion.
static <TO extends StoredObject, FROM> ObjectIterator<TO>	create(Iterable<FROM> from, Function<FROM,TO> converter)	Create an iterator from some source.
static <T extends StoredObject> ObjectIterator<T>	create(Collection<T> objects)	Create an iterator from the given objects.
static <TO extends StoredObject, FROM> ObjectIterator<TO>	create(Iterator<FROM> from, Function<FROM,TO> converter)	Create an iterator from some source.
static <T extends StoredObject> ObjectIterator<T>	create(Iterator<T> objects)	Create an iterator from the given objects.
static <T extends StoredObject> ObjectIterator<T>	create(List<T> objects)	Create an iterator from the given objects.
static <TO extends StoredObject, FROM> ObjectIterator<TO>	create(Stream<FROM> from, Function<FROM,TO> converter)	Create an iterator from some source.
static <T extends StoredObject> ObjectIterator<T>	create(T object)	Create an iterator from a single object.
static <T extends StoredObject> ObjectIterator<T>	create(T... objects)	Create an iterator from the given objects.
ObjectIterator<O>	deduplicate()	Convert the iterator to a new one by eliminating duplicate consecutive entries if any from it.
<TO extends StoredObject> ObjectIterator<TO>	expand(Function<O,ObjectIterator<TO>> function)	Expand this iterator using the given function.
ObjectIterator<O>	filter(BiPredicate<? super O,? super O> predicate)	Apply a bi-filter.
ObjectIterator<O>	filter(Predicate<? super O> predicate)	Apply a filter.
O	find(Predicate<? super O> predicate)	Find the object matching the given filter.
O	findFirst()	Find the first object.
void	forEach(Consumer<? super O> consumer)	Consume objects.
boolean	hasNext()
Iterator<O>	iterator()
ObjectIterator<O>	limit(long limit)	Limit the number of entries.
<TO extends StoredObject> ObjectIterator<TO>	map(Function<O,TO> function)	Convert this iterator to another type.
O	max(Comparator<? super O> comparator)	Find the object that satisfies the "max" condition that specified by the given comparator.
O	min(Comparator<? super O> comparator)	Find the object that satisfies the "min" condition that specified by the given comparator.
O	next()
boolean	noneMatch(Predicate<? super O> predicate)	Check whether no object is matching the given filter or not.
ObjectIterator<O>	process(Consumer<? super O> consumer)	Do some processing on each object but the same object is available after processing.
O	random()	Select an object randomly.
final void	remove()
O	select(BiFunction<? super O,? super O,O> function)	Select an object based on the given bi-function (to compare with other entries).
O	single()	Get a single entry from this iterator.
O	single(boolean showError)	Get a single entry from this iterator.
O	single(Predicate<? super O> filter)	Get a single entry from this iterator (after applying the filter).
O	single(Predicate<? super O> filter, boolean showError)	Get a single entry from this iterator (after applying the filter).
ObjectIterator<O>	skip(long count)	Skip a specified number of entries.
ObjectIterator<O>	skipWhile(Predicate<O> predicate)	Skip objects while a given predicate is true.
double	sum(ToDoubleFunction<? super O> function)	Get the sum.
List<O>	toList()	Collect all entries to a list.
<T> List<T>	toList(Function<O,T> convertor)	Collect all entries to a list after converting it to another type.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

spliterator

Methods inherited from interface java.util.Iterator

forEachRemaining

Method Details

add

public ObjectIterator<O> add(ObjectIterator<O> iterator)

Concatenate another instance.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

iterator - Another instance.

Returns:

A new instance that contains objects from this instance followed by objects from the added instance.

addToHead

public ObjectIterator<O> addToHead(ObjectIterator<O> iterator)

Concatenate another instance by adding to the head of it.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

iterator - Another instance.

Returns:

A new instance that contains objects from the added instance followed by objects from this instance.

add

public final ObjectIterator<O> add(O object)

Add one object to the tail of this instance.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

object - Object to add.

Returns:

Resulting instance.

addToHead

public final ObjectIterator<O> addToHead(O object)

Add one object to the head of this instance so that it will be next entry returned.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

object - Object to add.

Returns:

Resulting instance.

close

public void close()

Close this instance and release all associated resources.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

iterator

@Nonnull
public Iterator<O> iterator()

Specified by:

iterator in interface Iterable<O extends StoredObject>

next

public O next()

Specified by:

next in interface Iterator<O extends StoredObject>

hasNext

public boolean hasNext()

Specified by:

hasNext in interface Iterator<O extends StoredObject>

remove

public final void remove()

Specified by:

remove in interface Iterator<O extends StoredObject>

map

public <TO extends StoredObject> ObjectIterator<TO> map(Function<O,TO> function)

Convert this iterator to another type.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Type Parameters:

TO - To type.

Parameters:

function - Function to map.

Returns:

Converted iterator.

convert

public <TO extends StoredObject> ObjectIterator<TO> convert(ObjectConverter<O,TO> converter)

Convert this iterator to another type.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Type Parameters:

TO - To type.

Parameters:

converter - Converter.

Returns:

Converted iterator.

expand

public <TO extends StoredObject> ObjectIterator<TO> expand(Function<O,ObjectIterator<TO>> function)

Expand this iterator using the given function. For each item from this iterator, an iterator is derived via the given function and the resulting iterator is a concatenated version of all those iterators streamed in sequence.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Type Parameters:

TO - To type.

Parameters:

function - Function to map.

Returns:

Converted iterator.

filter

public ObjectIterator<O> filter(Predicate<? super O> predicate)

Apply a filter.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

predicate - Filter to apply.

Returns:

Filtered iterator.

filter

public ObjectIterator<O> filter(BiPredicate<? super O,? super O> predicate)

Apply a bi-filter.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

predicate - Filter to apply.

Returns:

Filtered iterator.

process

public ObjectIterator<O> process(Consumer<? super O> consumer)

Do some processing on each object but the same object is available after processing.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

consumer - Processor that consume the object instance but releases it for further consumption.

Returns:

Filtered iterator that invokes the processor internally. All objects are still available. However, the process may alter the attributes of the object.

deduplicate

public ObjectIterator<O> deduplicate()

Convert the iterator to a new one by eliminating duplicate consecutive entries if any from it.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Returns:

Converted iterator.

find

public O find(Predicate<? super O> predicate)

Find the object matching the given filter.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

predicate - Filter.

Returns:

The object found or null if nothing matches.

findFirst

public O findFirst()

Find the first object.

Note: This is a terminal operation and the iterator is closed after this operation.

Returns:

The object found or null if nothing found.

skip

public ObjectIterator<O> skip(long count)

Skip a specified number of entries.

Parameters:

count - Number of entries to drop.

Returns:

Self.

limit

public ObjectIterator<O> limit(long limit)

Limit the number of entries. (Rest will be dropped). If you pass a non-positive value, no entries will be returned.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

limit - Limit.

Returns:

Modified iterator.

count

public long count()

Get the count.

Note: This is a terminal operation and the iterator is closed after this operation.

Returns:

Count.

count

public long count(Predicate<? super O> filter)

Get the count after applying a filter.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

filter - Filter.

Returns:

Count.

sum

public double sum(ToDoubleFunction<? super O> function)

Get the sum.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

function - Function to extract the value from the object.

Returns:

Sum.

average

public double average(ToDoubleFunction<? super O> function)

Get the average.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

function - Function to extract the value from the object.

Returns:

Average.

allMatch

public boolean allMatch(Predicate<? super O> predicate)

Check whether all objects are matching the given filter or not.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

predicate - Filter.

Returns:

True/false.

anyMatch

public boolean anyMatch(Predicate<? super O> predicate)

Check whether any object is matching the given filter or not.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

predicate - Filter.

Returns:

True/false.

noneMatch

public boolean noneMatch(Predicate<? super O> predicate)

Check whether no object is matching the given filter or not.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

predicate - Filter.

Returns:

True/false.

forEach

public void forEach(Consumer<? super O> consumer)

Consume objects.

Note: This is a terminal operation and the iterator is closed after this operation.

Specified by:

forEach in interface Iterable<O extends StoredObject>

Parameters:

consumer - Consumer.

consumeWhile

public ObjectIterator<O> consumeWhile(Predicate<O> predicate,
 Consumer<O> consumer)

Consume objects while a given predicate is true.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Parameters:

predicate - Predicate to check.

consumer - Consumer.

Returns:

An iterator containing the remaining entries.

skipWhile

public ObjectIterator<O> skipWhile(Predicate<O> predicate)

Skip objects while a given predicate is true.

There is no need to maintain any references to this instance after this operation for the purpose of closing etc. and you need to take care of the resulting instance only.

Returns:

An iterator containing the remaining entries.

max

public O max(Comparator<? super O> comparator)

Find the object that satisfies the "max" condition that specified by the given comparator.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

comparator - Comparator.

Returns:

Object instance if any found (or null).

min

public O min(Comparator<? super O> comparator)

Find the object that satisfies the "min" condition that specified by the given comparator.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

comparator - Comparator.

Returns:

Object instance if any found (or null).

select

public O select(BiFunction<? super O,? super O,O> function)

Select an object based on the given bi-function (to compare with other entries).

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

function - Function to apply.

Returns:

Selected object. Could be null if the iterator is already empty.

random

public O random()

Select an object randomly. An object is guaranteed to be selected without any bias.

Note: This is a terminal operation and the iterator is closed after this operation.

Returns:

Selected object. Could be null if the iterator is already empty.

collectAll

@Deprecated
public Collection<O> collectAll()

Deprecated.

Collect all entries to a collection.

Note: This is a terminal operation and the iterator is closed after this operation.

This method is deprecated, use toList() instead.

Returns:

Collection.

collectAll

public Collection<O> collectAll(Collection<O> collection)

Collect all entries to a given collection.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

collection - Collection to which entries to be added. If null is passed, a new Collection instance is created.

Returns:

Collection.

collectAll

public <T> Collection<T> collectAll(Function<O,T> convertor)

Collect all entries to a collection after converting it to another type.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

convertor - Converter.

Returns:

Collection.

collectAll

public <T> Collection<T> collectAll(Collection<T> collection,
 Function<O,T> convertor)

Collect all entries to a given collection after converting it to another type.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

collection - Collection to which entries to be added.

convertor - Converter.

Returns:

Collection.

toList

public List<O> toList()

Collect all entries to a list.

Note: This is a terminal operation and the iterator is closed after this operation.

Returns:

List.

toList

public <T> List<T> toList(Function<O,T> convertor)

Collect all entries to a list after converting it to another type.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

convertor - Converter.

Returns:

List.

single

public O single(Predicate<? super O> filter)

Get a single entry from this iterator (after applying the filter). Only a single entry is expected and if no entry is found or multiple entries are found, a run-time exception is thrown.

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

filter - Filter to apply.

Returns:

The object.

single

public O single(Predicate<? super O> filter,
 boolean showError)

Get a single entry from this iterator (after applying the filter). Only a single entry is expected and if no entry is found or multiple entries are found, null will be returned (based on the "show error" parameter).

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

filter - Filter to apply.

showError - Whether to throw a run-time exception or not if no entry is found or multiple entries are found.

Returns:

The object.

single

public O single()

Get a single entry from this iterator. Only a single entry is expected and if no entry is found or multiple entries are found, a run-time exception is thrown.

Note: This is a terminal operation and the iterator is closed after this operation.

Returns:

The object.

single

public O single(boolean showError)

Get a single entry from this iterator. Only a single entry is expected and if no entry is found or multiple entries are found, null will be returned (based on the "show error" parameter).

Note: This is a terminal operation and the iterator is closed after this operation.

Parameters:

showError - Whether to throw a run-time exception or not if no entry is found or multiple entries are found.

Returns:

The object.

create

public static <T extends StoredObject>
ObjectIterator<T> create()

Create an empty iterator.

Type Parameters:

T - Type of object of the iterator to create.

Returns:

Iterator created.

create

public static <T extends StoredObject>
ObjectIterator<T> create(T object)

Create an iterator from a single object.

Type Parameters:

T - Type of object of the iterator to create.

Parameters:

object - Object to be included.

Returns:

Iterator created.

create

public static <T extends StoredObject>
ObjectIterator<T> create(List<T> objects)

Create an iterator from the given objects.

Type Parameters:

T - Type of object of the iterator to create.

Parameters:

objects - Objects to be included.

Returns:

Iterator created.

create

public static <T extends StoredObject>
ObjectIterator<T> create(Collection<T> objects)

Create an iterator from the given objects.

Type Parameters:

T - Type of object of the iterator to create.

Parameters:

objects - Objects to be included.

Returns:

Iterator created.

create

public static <T extends StoredObject>
ObjectIterator<T> create(Iterator<T> objects)

Create an iterator from the given objects.

Type Parameters:

T - Type of object of the iterator to create.

Parameters:

objects - Objects to be included.

Returns:

Iterator created.

create

@SafeVarargs
public static <T extends StoredObject>
ObjectIterator<T> create(T... objects)

Create an iterator from the given objects.

Type Parameters:

T - Type of object of the iterator to create.

Parameters:

objects - Objects to be included.

Returns:

Iterator created.

create

public static <FROM extends StoredObject,
TO extends StoredObject>
ObjectIterator<TO> create(ObjectIterator<FROM> iterator,
 ObjectConverter<FROM,TO> converter)

Create an iterator from the given iterator with conversion.

Type Parameters:

FROM - Type if object of the source.

TO - Type of object of the iterator to create.

Parameters:

iterator - Objects from the iterator to be included.

converter - Converter.

Returns:

Iterator created.

create

public static <TO extends StoredObject,
FROM>
ObjectIterator<TO> create(Iterable<FROM> from,
 Function<FROM,TO> converter)

Create an iterator from some source.

Type Parameters:

TO - Type of object of the iterator to create.

FROM - Type of the source.

Parameters:

from - Source.

converter - Converter to convert the source to an instance of TO.

Returns:

Iterator created.

create

public static <TO extends StoredObject,
FROM>
ObjectIterator<TO> create(Stream<FROM> from,
 Function<FROM,TO> converter)

Create an iterator from some source.

Type Parameters:

TO - Type of object of the iterator to create.

FROM - Type of the source.

Parameters:

from - Source.

converter - Converter to convert the source to an instance of TO.

Returns:

Iterator created.

create

public static <TO extends StoredObject,
FROM>
ObjectIterator<TO> create(Iterator<FROM> from,
 Function<FROM,TO> converter)

Create an iterator from some source.

Type Parameters:

TO - Type of object of the iterator to create.

FROM - Type of the source.

Parameters:

from - Source.

converter - Converter to convert the source to an instance of TO.

Returns:

Iterator created.