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

/** 
 *   Public interface to an Ordered List package.
 *
 *   An Ordered List holds Objects of some type T that implement the
 *   Comparable interface, in the order specified by the
 *   compareTo() method.   (Like SortedSet of JDK)
 *
 *   Multiple objects all of which compareTo() one another as equal 
 *   may appear on the list.  There is no guarantee as to the order
 *   in which they appear. (This is not the most useful specification, 
 *   but it's the easiest to program.)
 *
 *   @see Comparable
 *
 *   @author Ethan Bolker
 *   Copyright 1997 Ethan Bolker
 *
 *   Modified 1999 and 2003 Dennis Wortman
 *   to conform to java 1.2
 *
 *   Modified 2005 Betty O'Neil, for Java 5.0
 */
public interface OrderedList<T extends Comparable<? super T>> 
    extends Collection<T> {

   /**
    *  Add obj to the list at appropriate position to maintain the ordering. 
    *
    *  @param x   the object to add
    *  @return true if the object was added
    */
   public boolean add( T x );

   /**
    *  Retrieve (a ref to) the object at position i, like List.get().
    *
    *  @param i            the position from which to retrieve
    *  @throw NoSuchElementException   when i is out of bounds
    *  @return the object
    */
   public T get( int i )
   throws NoSuchElementException;
   
   /**
    *  Look for listobj on list such that obj.compareTo(listobj)
    *  is true., like List.indexOf()
    *
    *  @param obj   the object to look for
    *  @return position of a match, -1 if no match
    *
    */
    public int indexOf( Object obj );

   /**
    *  Allow the customer to look at the objects on the list
    *  one at a time - in proper order, of course.
    *
    *  @return an Iteration for the list
    */
   public Iterator<T> iterator();
}