Source code: jbreport/util/Stack.java
1 /*
2 * $Id: Stack.java,v 1.1.1.1 2000/08/31 13:14:47 grantfin Exp $
3 *
4 * jbReport - A reporting library for Java
5 * Copyright (C) 2000 Grant Finnemore <grantfin@users.sourceforge.net>
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 */
21 package jbreport.util;
22
23 import java.util.ArrayList;
24 import java.util.EmptyStackException;
25 import java.util.Iterator;
26 import java.util.List;
27
28 /**
29 * This provides for the semantics of a stack. By default it uses a
30 * java.util.ArrayList for management, but this can be changed by passing the
31 * appropriate java.util.List instance to the alternate constructor.
32 *
33 * <p> This is otherwise known as a FILO (First in, last out) list.
34 *
35 * <p> The existing stack from the java.util.* package was not used, as it is
36 * extended from the Vector class, which is fully synchronized. This is not a
37 * behaviour that is needed by default. IMHO. We do provide for all of the
38 * methods in the java.util.Stack class tho'.
39 *
40 * @version $Revision: 1.1.1.1 $
41 */
42 public
43 class Stack {
44
45 /** The list instance that is used to store and manage the stack. */
46 private List backingList;
47
48 //
49 // Constructors
50 //
51
52 public Stack() {
53 this(new ArrayList());
54 }
55
56 public Stack(List backingList) {
57 if(backingList == null) {
58 throw new IllegalArgumentException("The backing list cannot be null");
59 }
60 this.backingList = backingList;
61 }
62
63 //
64 // Public interface
65 //
66
67 /**
68 * Removes all of the elements from this stack (optional operation). This
69 * stack will be empty after this call returns (unless it throws an
70 * exception).
71 *
72 * @throws UnsupportedOperationException if the clear method is not
73 * supported by the backing list.
74 */
75 public void clear() {
76 backingList.clear();
77 }
78
79 /**
80 * Pushes an item onto the top of this stack.
81 *
82 * @param item the item to be pushed onto this stack.
83 * @return the item argument.
84 */
85 public Object push(Object item) {
86 if(item == null) {
87 throw new IllegalArgumentException("The pushed item cannot be null");
88 }
89 backingList.add(0, item);
90 return item;
91 }
92
93 /**
94 * Removes the object at the top of this stack and returns that object as
95 * the value of this function.
96 *
97 * @return The object at the top of this stack (the last item of the List
98 * object).
99 *
100 * @throws EmptyStackException if this stack is empty.
101 */
102 public Object pop() {
103 if(empty()) {
104 throw new EmptyStackException();
105 }
106 return backingList.remove(0);
107 }
108
109 /**
110 * Looks at the object at the top of this stack without removing it from
111 * the stack.
112 *
113 * @return the object at the top of this stack (the last item of the List
114 * object).
115 * @throws EmptyStackException if this stack is empty.
116 */
117 public Object peek() {
118 if(empty()) {
119 throw new EmptyStackException();
120 }
121 return backingList.get(0);
122 }
123
124 /**
125 * Looks at the object at the position relative to the top of the stack.
126 *
127 * @throws EmptyStackException if this stack is empty.
128 * @throws IndexOutOfBoundsException if the index is out of range (index <
129 * 0 || index >= size()).
130 */
131 public Object peek(int index) {
132 if(empty()) {
133 throw new EmptyStackException();
134 }
135 if(index < 0 || index >= backingList.size()) {
136 throw new IndexOutOfBoundsException("invalid index - " + index);
137 }
138 return backingList.get(index);
139 }
140
141 /**
142 * Tests if this stack is empty.
143 *
144 * @return true if and only if this stack contains no items; false
145 * otherwise.
146 */
147 public boolean empty() {
148 return backingList.size() <= 0;
149 }
150
151 /**
152 * Returns the 1-based position where an object is on this stack. If the
153 * object o occurs as an item in this stack, this method returns the
154 * distance from the top of the stack of the occurrence nearest the top of
155 * the stack; the topmost item on the stack is considered to be at distance
156 * 1. The equals method is used to compare o to the items in this stack.
157 *
158 * @param o the desired object.
159 * @return the 1-based position from the top of the stack where the object
160 * is located; the return value -1 indicates that the object is not on the
161 * stack.
162 */
163 public int search(Object o) {
164 int result = -1, i = 1;
165 for(Iterator it = backingList.iterator(); it.hasNext(); i++) {
166 if(it.next().equals(o)) {
167 result = i;
168 break;
169 }
170 }
171 return result;
172 }
173
174 //
175 // Overridden methods from java.lang.Object
176 //
177
178 public int hashCode() {
179 return backingList.hashCode();
180 }
181
182 public boolean equals(Object obj) {
183 if(this == obj) return true;
184 if(obj == null) return false;
185 if(obj.getClass() != getClass()) return false;
186 Stack other = (Stack)obj;
187 return backingList.equals(other.backingList);
188 }
189
190 }
191
192
193