/*
 * 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 stack. <p> A stack is a collection of objects
 * elements that are inserted and removed according to the last-in
 * first-out principle.
 *
 * @author Michael T. Goodrich
 * @author Mark Handy
 * @author Roberto Tamassia
 * @version JSDL-Teach release 1.0
 * @see StackEmptyException
 * @see Queue
 * @see Deque
 */

public interface Stack {
    // accessor methods

/** 
 * Return the number of elements.
 *
 * @return number of elements in the stack.
 */
  public int size(); //# return the number of elements stored in the stack

/** 
 * Tests if the stack is empty
 * @return <code>true</code> if the stack is empty, <code>false</code>
 * otherwise.
 */
  public boolean isEmpty(); //# test whether the stack is empty

/**
 * Inspect the top element, without removing it or otherwise
 * modifying the stack.
 *
 * @return top element in the stack.  
 * @exception StackEmptyException If this stack is empty.
 */
    public Object top() //# return the top elemet
        throws StackEmptyException; //# thrown if called on an empty stack
   
   // update methods
   
/** 
 * Insert an element at the top.
 *
 * @param element new element to be inserted.
 */
    public void push (Object element); //# insert an element onto the stack
   
/** 
 * Remove the top element.
 *
 * @return element removed.
 * @exception StackEmptyException if this stack is empty
 */
    public Object pop() //# return and remove the top element of the stack
        throws StackEmptyException; //# thrown if called on an empty stack
   
}