KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sosnoski > util > stack > ObjectStack


1 /*
2  * Copyright (c) 2000-2001 Sosnoski Software Solutions, Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to deal
6  * in the Software without restriction, including without limitation the rights
7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8  * copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  */

22
23 package com.sosnoski.util.stack;
24
25 import java.util.Iterator JavaDoc;
26
27 import com.sosnoski.util.ArrayRangeIterator;
28
29 /**
30  * Growable <code>Object</code> stack with type specific access methods. This
31  * implementation is unsynchronized in order to provide the best possible
32  * performance for typical usage scenarios, so explicit synchronization must
33  * be implemented by a wrapper class or directly by the application in cases
34  * where instances are modified in a multithreaded environment. See the base
35  * classes for other details of the implementation.
36  *
37  * @author Dennis M. Sosnoski
38  * @version 1.1
39  */

40
41 public class ObjectStack extends StackBase
42 {
43     /** The underlying array used for storing the data. */
44     protected Object JavaDoc[] m_baseArray;
45
46     /**
47      * Constructor with full specification.
48      *
49      * @param size number of <code>Object</code> values initially allowed in
50      * stack
51      * @param growth maximum size increment for growing stack
52      */

53
54     public ObjectStack(int size, int growth) {
55         super(size, growth, Object JavaDoc.class);
56     }
57
58     /**
59      * Constructor with initial size specified.
60      *
61      * @param size number of <code>Object</code> values initially allowed in
62      * stack
63      */

64
65     public ObjectStack(int size) {
66         super(size, Object JavaDoc.class);
67     }
68
69     /**
70      * Default constructor.
71      */

72
73     public ObjectStack() {
74         this(DEFAULT_SIZE);
75     }
76
77     /**
78      * Copy (clone) constructor.
79      *
80      * @param base instance being copied
81      */

82
83     public ObjectStack(ObjectStack base) {
84         super(base);
85     }
86
87     /**
88      * Get the backing array. This method is used by the type-agnostic base
89      * class code to access the array used for type-specific storage.
90      *
91      * @return backing array object
92      */

93
94     protected Object JavaDoc getArray() {
95         return m_baseArray;
96     }
97
98     /**
99      * Set the backing array. This method is used by the type-agnostic base
100      * class code to set the array used for type-specific storage.
101      *
102      * @param backing array object
103      */

104
105     protected void setArray(Object JavaDoc array) {
106         m_baseArray = (Object JavaDoc[]) array;
107     }
108
109     /**
110      * Push a value on the stack.
111      *
112      * @param value value to be added
113      */

114
115     public void push(Object JavaDoc value) {
116         int index = getAddIndex();
117         m_baseArray[index] = value;
118     }
119
120     /**
121      * Pop a value from the stack.
122      *
123      * @return value from top of stack
124      * @exception ArrayIndexOutOfBoundsException on attempt to pop empty stack
125      */

126
127     public Object JavaDoc pop() {
128         if (m_countPresent > 0) {
129             Object JavaDoc value = m_baseArray[--m_countPresent];
130             m_baseArray[m_countPresent] = null;
131             return value;
132         } else {
133             throw new ArrayIndexOutOfBoundsException JavaDoc
134                 ("Attempt to pop empty stack");
135         }
136     }
137
138     /**
139      * Pop multiple values from the stack. The last value popped is the
140      * one returned.
141      *
142      * @param count number of values to pop from stack (must be strictly
143      * positive)
144      * @return value from top of stack
145      * @exception ArrayIndexOutOfBoundsException on attempt to pop past end of
146      * stack
147      */

148
149     public Object JavaDoc pop(int count) {
150         if (count <= 0) {
151             throw new IllegalArgumentException JavaDoc("Count must be greater than 0");
152         } else if (m_countPresent >= count) {
153             m_countPresent -= count;
154             Object JavaDoc value = m_baseArray[m_countPresent];
155             discardValues(m_countPresent, m_countPresent + count);
156             return value;
157         } else {
158             throw new ArrayIndexOutOfBoundsException JavaDoc
159                 ("Attempt to pop past end of stack");
160         }
161     }
162
163     /**
164      * Copy a value from the stack. This returns a value from within
165      * the stack without modifying the stack.
166      *
167      * @param depth depth of value to be returned
168      * @return value from stack
169      * @exception ArrayIndexOutOfBoundsException on attempt to peek past end of
170      * stack
171      */

172
173     public Object JavaDoc peek(int depth) {
174         if (m_countPresent > depth) {
175             return m_baseArray[m_countPresent - depth - 1];
176         } else {
177             throw new ArrayIndexOutOfBoundsException JavaDoc
178                 ("Attempt to peek past end of stack");
179         }
180     }
181
182     /**
183      * Copy top value from the stack. This returns the top value without
184      * removing it from the stack.
185      *
186      * @return value at top of stack
187      * @exception ArrayIndexOutOfBoundsException on attempt to peek empty stack
188      */

189
190     public Object JavaDoc peek() {
191         return peek(0);
192     }
193
194     /**
195      * Return an iterator for the <code>Object</code>s in this stack. The
196      * iterator returns all values in order the order they were added, but is
197      * not "live". Values added to the stack during iteration will not be
198      * returned by the iteration, and any other changes to the stack while the
199      * iteration is in progress will give indeterminant results.
200      *
201      * @return iterator for values in stack
202      */

203
204     public final Iterator JavaDoc iterator() {
205         return ArrayRangeIterator.buildIterator(m_baseArray, 0, m_countPresent);
206     }
207
208     /**
209      * Constructs and returns a simple array containing the same data as held
210      * in this stack. Note that the items will be in reverse pop order, with
211      * the last item to be popped from the stack as the first item in the
212      * array.
213      *
214      * @return array containing a copy of the data
215      */

216
217     public Object JavaDoc[] toArray() {
218         return (Object JavaDoc[]) buildArray(Object JavaDoc.class);
219     }
220
221     /**
222      * Constructs and returns a type-specific array containing the same data
223      * as held in this growable generic array. All values in this array must
224      * be assignment compatible with the specified type. Note that the items
225      * will be in reverse pop order, with the last item to be popped from the
226      * stack as the first item in the array.
227      *
228      * @param type element type for constructed array
229      * @return array containing a copy of the data
230      */

231
232     public Object JavaDoc[] toArray(Class JavaDoc type) {
233         return (Object JavaDoc[]) buildArray(type);
234     }
235
236     /**
237      * Duplicates the object with the generic call.
238      *
239      * @return a copy of the object
240      */

241
242     public Object JavaDoc clone() {
243         return new ObjectStack(this);
244     }
245 }
246
Popular Tags