/* * 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.
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 true
if the stack is empty, false
* 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
}