/**
 * A PriorityQueue represents an unbounded queue of items arranged in some 
 * priority order.
 * This queue orders items according to their <i>natural order</i>
 * (see 
 * <a href=http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Comparable.html>
 * Comparable</a>).
 * A priority queue does not permit null elements. A priority queue 
 * also does not permit insertion of non-comparable objects (doing so may 
 * result in ClassCastException).
 * <br>
 * The head of this queue is the <i>greatest</i> element with respect to the 
 * specified ordering. 
 * If multiple elements are tied for greatest value, the head is one of those 
 * elements -- ties are broken arbitrarily. 
 * 
 * The queue retrieval operations dequeue and peek access the element at the 
 * head of the queue.
 * <br>
 * All implementations must include an <code>iterator()</code> method
 * to allow clients to use for-each loop to traverse the elements of the 
 * PriorityQueue in order.
 * @author J. Dalbey
 * @version 09/29/2007
 */
public interface PriorityQueue<Element extends Comparable> extends Iterable<Element>
{
    /**
     * Removes all elements from the priority queue.
     */
    void clear();
    /**
     * Retrieves, but does not remove, the head of this queue.
     * @return the head item in the queue, or null if this queue is empty.
     */
    Element peek();
    
    /**
     * Retrieves and removes the head of this queue.
     * @return the head item in the queue, or null if this queue is empty.
     */
    Element dequeue();
    
    /**
     * Adds the specified element to this priority queue.
     * @param element is an item to be enqueued
     * @pre element is not null 
     **/
    void enqueue(Element element);
    
    /**
     *  Returns the number of elements currently in this queue.
     *  @return int the size of the queue
     */
    int size();
    
    /**
     *  Indicates whether or not the queue is empty.
     *  @return true if the queue size is zero, false otherwise. 
     */
    boolean isEmpty();
}