package tester;

/**
 * Copyright 2007 Viera K. Proulx
 * This program is distributed under the terms of the 
 * GNU Lesser General Public License (LGPL)
 */

/**
 *  An interface that defines a functional iterator for traversing datasets
 * 
 * @author Viera K. Proulx
 * @since 30 May 2007 
 */
public interface Traversal<T> {

	/** 
	 * Produce true if this <CODE>{@link Traversal Traversal}</CODE> 
	 * represents an empty dataset 
	 * 
	 * @return true if the dataset is empty
	 */
	public boolean isEmpty();

	/** 
	 * <P>Produce the first element in the dataset represented by this 
	 * <CODE>{@link Traversal Traversal}</CODE> </P>
	 * <P>Throws <code>IllegalUseOfTraversalException</code> 
	 * if the dataset is empty.</P>
	 * 
	 * @return the first element if available -- otherwise 
	 * throws <code>IllegalUseOfTraversalException</code>
	 */
	public T getFirst();

	/** 
	 * <P>Produce a <CODE>{@link Traversal Traversal}</CODE> 
	 * for the rest of the dataset </P>
	 * <P>Throws <code>IllegalUseOfTraversalException</code> 
	 * if the dataset is empty.</P>
	 * 
	 * @return the <CODE>{@link Traversal Traversal}</CODE> for
	 * the rest of this dataset if available -- otherwise 
	 * throws <code>IllegalUseOfTraversalException</code>
	 */
	public Traversal<T> getRest();
}