View Javadoc

1   /*
2    *  Copyright 2001-2004 The Apache Software Foundation
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.apache.commons.collections;
17  
18  import java.util.ArrayList;
19  import java.util.EmptyStackException;
20  
21  /**
22   * An implementation of the {@link java.util.Stack} API that is based on an
23   * <code>ArrayList</code> instead of a <code>Vector</code>, so it is not
24   * synchronized to protect against multi-threaded access.  The implementation
25   * is therefore operates faster in environments where you do not need to
26   * worry about multiple thread contention.
27   * <p>
28   * The removal order of an <code>ArrayStack</code> is based on insertion 
29   * order: The most recently added element is removed first.  The iteration
30   * order is <i>not</i> the same as the removal order.  The iterator returns
31   * elements from the bottom up, whereas the {@link #remove()} method removes
32   * them from the top down.
33   * <p>
34   * Unlike <code>Stack</code>, <code>ArrayStack</code> accepts null entries.
35   * <p>
36   * <strong>Note:</strong> this class should be bytecode-identical to the 
37   * version in commons collections. This is required to allow backwards 
38   * compability with both previous versions of BeanUtils and also allow 
39   * coexistance with both collections 2.1 and 3.0.
40   *
41   * @see java.util.Stack
42   * @since Commons Collections 1.0
43   * @version $Revision: 1.1 $ $Date: 2004/05/10 19:50:13 $
44   * 
45   * @author Craig R. McClanahan
46   * @author Paul Jack
47   * @author Stephen Colebourne
48   */
49  public class ArrayStack extends ArrayList implements Buffer {
50  
51      /** Ensure serialization compatibility */    
52      private static final long serialVersionUID = 2130079159931574599L;
53  
54      /**
55       * Constructs a new empty <code>ArrayStack</code>. The initial size
56       * is controlled by <code>ArrayList</code> and is currently 10.
57       */
58      public ArrayStack() {
59          super();
60      }
61  
62      /**
63       * Constructs a new empty <code>ArrayStack</code> with an initial size.
64       * 
65       * @param initialSize  the initial size to use
66       * @throws IllegalArgumentException  if the specified initial size
67       *  is negative
68       */
69      public ArrayStack(int initialSize) {
70          super(initialSize);
71      }
72  
73      /**
74       * Return <code>true</code> if this stack is currently empty.
75       * <p>
76       * This method exists for compatibility with <code>java.util.Stack</code>.
77       * New users of this class should use <code>isEmpty</code> instead.
78       * 
79       * @return true if the stack is currently empty
80       */
81      public boolean empty() {
82          return isEmpty();
83      }
84  
85      /**
86       * Returns the top item off of this stack without removing it.
87       *
88       * @return the top item on the stack
89       * @throws EmptyStackException  if the stack is empty
90       */
91      public Object peek() throws EmptyStackException {
92          int n = size();
93          if (n <= 0) {
94              throw new EmptyStackException();
95          } else {
96              return get(n - 1);
97          }
98      }
99  
100     /**
101      * Returns the n'th item down (zero-relative) from the top of this
102      * stack without removing it.
103      *
104      * @param n  the number of items down to go
105      * @return the n'th item on the stack, zero relative
106      * @throws EmptyStackException  if there are not enough items on the
107      *  stack to satisfy this request
108      */
109     public Object peek(int n) throws EmptyStackException {
110         int m = (size() - n) - 1;
111         if (m < 0) {
112             throw new EmptyStackException();
113         } else {
114             return get(m);
115         }
116     }
117 
118     /**
119      * Pops the top item off of this stack and return it.
120      *
121      * @return the top item on the stack
122      * @throws EmptyStackException  if the stack is empty
123      */
124     public Object pop() throws EmptyStackException {
125         int n = size();
126         if (n <= 0) {
127             throw new EmptyStackException();
128         } else {
129             return remove(n - 1);
130         }
131     }
132 
133     /**
134      * Pushes a new item onto the top of this stack. The pushed item is also
135      * returned. This is equivalent to calling <code>add</code>.
136      *
137      * @param item  the item to be added
138      * @return the item just pushed
139      */
140     public Object push(Object item) {
141         add(item);
142         return item;
143     }
144 
145     /**
146      * Returns the one-based position of the distance from the top that the
147      * specified object exists on this stack, where the top-most element is
148      * considered to be at distance <code>1</code>.  If the object is not
149      * present on the stack, return <code>-1</code> instead.  The
150      * <code>equals()</code> method is used to compare to the items
151      * in this stack.
152      *
153      * @param object  the object to be searched for
154      * @return the 1-based depth into the stack of the object, or -1 if not found
155      */
156     public int search(Object object) {
157         int i = size() - 1;        // Current index
158         int n = 1;                 // Current distance
159         while (i >= 0) {
160             Object current = get(i);
161             if ((object == null && current == null) ||
162                 (object != null && object.equals(current))) {
163                 return n;
164             }
165             i--;
166             n++;
167         }
168         return -1;
169     }
170 
171     /**
172      * Returns the element on the top of the stack.
173      *
174      * @return the element on the top of the stack
175      * @throws BufferUnderflowException  if the stack is empty
176      */
177     public Object get() {
178         int size = size();
179         if (size == 0) {
180             throw new BufferUnderflowException();
181         }
182         return get(size - 1);
183     }
184 
185     /**
186      * Removes the element on the top of the stack.
187      *
188      * @return the removed element 
189      * @throws BufferUnderflowException  if the stack is empty
190      */
191     public Object remove() {
192         int size = size();
193         if (size == 0) {
194             throw new BufferUnderflowException();
195         }
196         return remove(size - 1);
197     }
198 
199 }