001/* ---------------------------------------------------------------------------- 002 The Kiwi Toolkit - A Java Class Library 003 Copyright (C) 1998-2004 Mark A. Lindner 004 005 This library is free software; you can redistribute it and/or 006 modify it under the terms of the GNU General Public License as 007 published by the Free Software Foundation; either version 2 of the 008 License, or (at your option) any later version. 009 010 This library is distributed in the hope that it will be useful, 011 but WITHOUT ANY WARRANTY; without even the implied warranty of 012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013 General Public License for more details. 014 015 You should have received a copy of the GNU General Public License 016 along with this library; if not, write to the Free Software 017 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 018 02111-1307, USA. 019 020 The author may be contacted at: mark_a_lindner@yahoo.com 021 ---------------------------------------------------------------------------- 022 $Log: StackModel.java,v $ 023 Revision 1.6 2004/05/13 21:35:34 markl 024 comment block updates 025 026 Revision 1.5 2003/01/19 09:33:06 markl 027 Javadoc & comment header updates. 028 029 Revision 1.4 2001/03/12 07:24:01 markl 030 Javadoc cleanup. 031 032 Revision 1.3 2001/03/12 04:54:32 markl 033 Source code cleanup. 034 035 Revision 1.2 1999/01/10 03:12:19 markl 036 added GPL header & RCS tag 037 ---------------------------------------------------------------------------- 038*/ 039 040package kiwi.ui.model; 041 042import java.util.EmptyStackException; 043import javax.swing.ListModel; 044import javax.swing.event.ListDataListener; 045 046/** An interface describing the data model for a stack. This interface extends 047 * <code>ListModel</code> as a stack is essentially a list with special 048 * semantics. 049 * 050 * @see kiwi.ui.StackView 051 * 052 * @author Mark Lindner 053 */ 054 055public interface StackModel extends ListModel 056 { 057 058 /** Push an object on the stack. The object becomes the topmost item on the 059 * stack. 060 * 061 * @param obj The object to push. 062 */ 063 064 public void push(Object obj); 065 066 /** Pop an object off the stack. Pulls the topmost item off the stack. 067 * 068 * @return The popped object. 069 */ 070 071 public Object pop() throws EmptyStackException; 072 073 /** Drop an item off the stack. Pops and discards the topmost item on the 074 * stack. 075 * 076 * @exception java.util.EmptyStackException If the stack is empty. 077 */ 078 079 public void drop(); 080 081 /** Retrieve the topmost item from the stack (without removing the item from 082 * the stack). 083 * 084 * @return The topmost item on the stack. 085 * 086 * @exception java.util.EmptyStackException If the stack is empty. 087 */ 088 089 public Object peek() throws ArrayIndexOutOfBoundsException; 090 091 /** Get the depth of the stack. 092 * 093 * @return The number of items in the stack. 094 */ 095 096 public int getDepth(); 097 098 /** Swap the topmost items on the stack. If the stack contains only one item, 099 * calling this method has no effect. 100 * 101 * @exception java.util.EmptyStackException If the stack is empty. 102 */ 103 104 public void swap() throws EmptyStackException; 105 106 /** Determine if the stack is empty. 107 * 108 * @return <code>true</code> if there are no items in the stack, and 109 * <code>false</code> otherwise. 110 */ 111 112 public boolean isEmpty(); 113 114 /** Remove an object from the stack. Retrieves (and removes) an object from 115 * the given offset in the stack. 116 * 117 * @param index The offset (from the top of the stack) of the item to remove. 118 * 119 * @return The object that was removed. 120 * 121 * @exception java.util.EmptyStackException If the stack is empty. 122 * @exception java.lang.ArrayIndexOutOfBoundsException If the value of 123 * <code>index</code> is out of range. 124 */ 125 126 public Object pick(int index) throws ArrayIndexOutOfBoundsException, 127 EmptyStackException; 128 129 /** Append an object to the bottom of the stack. 130 * 131 * @param obj The object to append. 132 */ 133 134 public void append(Object obj); 135 136 /** Add a <code>ListDataListener</code> to this model's list of listeners. 137 * Since a stack is essentially a list with some special semantics, 138 * <code>ListDataListeners</code> are used. 139 * 140 * @param listener The listener to add. 141 */ 142 143 public void addStackDataListener(ListDataListener listener); 144 145 /** Remove a <code>ListDataListener</code> from this model's list of 146 * listeners. Since a stack is essentially a list with some special 147 * semantics, <code>ListDataListeners</code> are used. 148 * 149 * @param listener The listener to add. 150 */ 151 152 public void removeStackDataListener(ListDataListener listener); 153 } 154 155/* end of source file */