package Queue;

import java.lang.*;
import java.util.*;

/**
 * A queue is a container that stores a list of items.  Items can
 * be inserted and removed from the two ends of the queue only.
 * For flexibility, the queue interface supports both FIFO behavior
 * and LIFO behavior.
 *
 * The Stack class from java.util only supports LIFO behavior.
 * @see java.util.Stack
 * @author Thomas Wang
 * @version 0.55
 */
public abstract interface Queue
  extends Cloneable
{
  /**
   * Returns the last element of the queue without removing the
   * element.
   * @return the last element
   */
  public Object lastElement()
    throws NoSuchElementException;

  /**
   * Returns the first element of the queue without removing the
   * element.
   * @return the first element
   */
  public Object firstElement()
    throws NoSuchElementException;

  /**
   * Insert the specified element into the front of the queue.
   * @param elem element to be inserted
   */
  public void insertFirst(Object elem);

  /**
   * Insert the specified element into the back of the queue.
   * @param elem element to be inserted
   */
  public void insertLast(Object elem);

  /**
   * Remove and return an element from the front of the queue.
   * @return the element at the front of the queue
   * @exception NoSuchElementException thrown when there are no
   * elements in the queue
   */
  public Object removeFirst()
    throws NoSuchElementException;

  /**
   * Remove and return an element from the back of the queue.
   * @return the element at the back of the queue
   * @exception NoSuchElementException thrown when there are no
   * elements in the queue
   */
  public Object removeLast()
    throws NoSuchElementException;

  /**
   * Returns the number of elements in the queue.
   */
  public int size();

  /**
   * Returns an enumeration of the elements in the queue.
   * @see java.util.Enumeration
   * @return the enumeration
   */
  public Enumeration elements();

  /**
   * Returns a shallow copy of the queue.
   * @see java.lang.Object#clone
   */
  public Object clone();
}