//    Copyright (C) 2002 -- See your tutor for details
//
//    This library is free software; you can redistribute it and/or
//    modify it under the terms of the GNU Lesser General Public
//    License as published by the Free Software Foundation; either
//    version 2.1 of the License, or (at your option) any later version.
/**
 *  <P>A "first-in first-out" ADT specification.
 *  This interface specifies a common ADT called a Queue. Items are put into
 *  a Queue by "enqueueing" and are removed by "dequeueing". The first item put into the
 *  Queue is always the first to be "dequeued". This is why a Queue is called a
 *  "first-in first-out" (FIFO) data structure.</P>
 *
 *  <P>The precondition on the enqueue method requires that the item given is not null.
 *  It should provide better abstraction to disallow null entries in the Queue. Using
 *  actual Objects as empty tokens in the Queue is better than relying on the implementation
 *  to store null Objects.</P> 
 *
 *  <P>Also, Queue extends adt.util.Collection so that its capacity can be calculated.</P>
 *  
 *  @author Andrew H. Hoefel ahhoefel@student.math.uwaterloo.ca
 *  @version v0.5 -- Jan 5, 2002
 */
public interface Queue
{
  /**
   *  Puts an item into the rear of the queue. When items are "enqueued" they are kept
   *  in order. That is, the most recently "enqueued" item sits at the rear of the queue
   *  while the oldest items are at the front.
   *  @param item The Object to be placed at the rear of the queue.
   *  @pre <CODE>item != null</CODE>.
   *  @post <CODE>item</CODE> is at the rear of the queue with all of the old elements
   *  ahead of it.  
   */
  public void enqueue(Object item);

  /**
   *  Takes the front element out of the queue. When dequeue is called the front element
   *  is removed from the queue and returned to the caller.
   *  @return The Object that was previously at the front of the queue.
   *  @pre The queue is not empty. Ex. this.isEmpty() has the value of false.
   *  @post The queue is the the same as the queue before the method minus the front element.
   *  @post The return value is the front element of the queue before this method call.
   */ 
  public Object dequeue();

  /**
   *  Allows the user to look at the front element of the queue. This operation, 
   *  unlike dequeue, does not remove the front element from the queue. It merely 
   *  returns it.
   *  @return The element that is at the front of the queue.
   *  @pre The queue is not empty. Ex. this.isEmpty() has the value of false.
   *  @post The return value is the front element of the queue.
   */ 
  public Object peek();

  /**
   * Gets the number of elements in this collection.
   *
   * @return Returns the size of this collection
   * @pre None.
   * @post The return value is the number of elements in this collection (&gt;=0).
   */
  public int size();

  /**
   * Determines if this collection contains any elements.
   *
   * @return Returns <CODE>true</CODE> if this is empty and <CODE>false</CODE>
   *      otherwise.
   * @pre None.
   * @post The return value is <CODE>true</CODE> iff this collection contains
   *     no elements.
   */
  public boolean isEmpty();
}