com.puresoltechnologies.streaming.StreamIterator Maven / Gradle / Ivy

Go to download
package com.puresoltechnologies.streaming;

import java.util.Iterator;
import java.util.NoSuchElementException;

/**
 * This is the interface for a iterator over a stream. It extends the
 * {@link Iterator} interface by a functionality to peek for the next element
 * without moving forward. But, the main difference is that no null
 * elements can be returned by {@link #next()} and {@link #peek()}. Streams
 * cannot have null (empty) elements, because then they are already
 * at their end. In this case, a {@link NoSuchElementException} is thrown.
 * 
 * @author Rick-Rainer Ludwig
 *
 * @param 
 *            is the element type of the iterator.
 */
public interface StreamIterator extends Iterator {

    /**
     * Converts an {@link Iterator} into a {@link StreamIterator}.
     * 
     * @param iterator
     *            is the iterator to be converter.
     * @return A {@link StreamIterator} object is return containing all
     *         non-null elements in same order.
     */
    public static  StreamIterator of(Iterator iterator) {
	return new AbstractStreamIterator() {
	    @Override
	    protected T findNext() {
		while (iterator.hasNext()) {
		    T next = iterator.next();
		    if (next != null) {
			return next;
		    }
		}
		return null;
	    }
	};
    }

    /**
     * This method overwrites {@link Iterator#next()} with a one change: The
     * resulting element is never null.
     * 
     * @throws NoSuchElementException
     *             is thrown in case the stream has reached its end.
     * @return An object of generic type T is returned. If the stream has reached
     *         its end, a {@link NoSuchElementException} is thrown.
     *         {@link #hasNext()} will returned false in this case and
     *         should be asked for the presence of more elements in advance. The
     *         result is never null.
     */
    @Override
    T next() throws NoSuchElementException;

    /**
     * This method returns the next element which will be returned by next(),
     * without moving forward.
     * 
     * @throws NoSuchElementException
     *             is thrown in case the stream has reached its end.
     * @return An object of generic type T is returned. If the stream has reached
     *         its end, a {@link NoSuchElementException} is thrown.
     *         {@link #hasNext()} will returned false in this case and
     *         should be asked for the presence of more elements in advance. The
     *         result is never null.
     */
    T peek() throws NoSuchElementException;

}