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 */