/*
 * Copyright (C) 1998, Center for Geometric Computing, Brown University
 *                 and The Johns Hopkins University
 * 
 * All Rights Reserved
 * 
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose other than its incorporation into a  
 * commercial product is hereby granted without fee, provided that the
 * above copyright notice appear in all copies and that both that   
 * copyright notice and this permission notice appear in supporting 
 * documentation, and that the names of Brown University and of The Johns
 * Hopkins University not be used in advertising or publicity pertaining
 * to distribution of the software without specific, written prior
 * permission.
 * 
 * BROWN UNIVERSITY AND THE JOHNS HOPKINS UNIVERSITY DISCLAIM ALL
 * WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR  
 * PURPOSE. IN NO EVENT SHALL BROWN UNIVERSITY OR THE JOHNS HOPKINS
 * UNIVERSITY BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL 
 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
 * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */


/**

 * Interface for a queue. <p> A queue is a collection of elements that
 * are inserted and removed according to the first-in first-out
 * principle.
 *
 * @author Michael T. Goodrich
 * @author Natasha Gelfand
 * @author Mark Handy
 * @author Roberto Tamassia
 * @version JSDL-Teach release 1.0
 * @see QueueEmptyException
 * @see Stack
 * @see Deque
 */

public interface Queue {
  // accessor methods
  
  /** 
    * Return the number of elements.
    * @return number of elements in the queue.
    */
  public int size(); //# return the number of elements stored in the queue
  
  /** 
    * Return true if and only if the queue is empty.
    * @return true if the queue is empty, false otherwise.
    */
  public boolean isEmpty(); //# test whether the queue is empty
  
  /**
    * Inspect the element at the front, without removing it or
    * otherwise changing the queue.
    *
    * @return element at the front of the queue
    * @exception QueueEmptyException if the queue is empty
    */
  public Object front() //# return the front element of the queue
    throws QueueEmptyException; //# thrown if called on an empty queue
  
  // update methods
  
  /** 
    * Insert an element at the rear.
    *
    * @param element new element to be inserted.
    */
  public void enqueue (Object element); //# insert an element at the rear
  
  /** 
    * Remove the element at the front.
    *
    * @return element removed.
    * @exception QueueEmptyException
    */
  public Object dequeue() //# return and remove the front element
    throws QueueEmptyException; //# thrown if called on an empty queue
  
}