1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.tomcat.util.digester;
18
19 import java.util.ArrayList;
20 import java.util.EmptyStackException;
21
22 /**
23 * <p>Imported copy of the <code>ArrayStack</code> class from
24 * Commons Collections, which was the only direct dependency from Digester.</p>
25 *
26 * <p><strong>WARNNG</strong> - This class is public solely to allow it to be
27 * used from subpackages of <code>org.apache.commons.digester</code>.
28 * It should not be considered part of the public API of Commons Digester.
29 * If you want to use such a class yourself, you should use the one from
30 * Commons Collections directly.</p>
31 *
32 * <p>An implementation of the {@link java.util.Stack} API that is based on an
33 * <code>ArrayList</code> instead of a <code>Vector</code>, so it is not
34 * synchronized to protect against multi-threaded access. The implementation
35 * is therefore operates faster in environments where you do not need to
36 * worry about multiple thread contention.</p>
37 *
38 * <p>Unlike <code>Stack</code>, <code>ArrayStack</code> accepts null entries.
39 * </p>
40 *
41 * @param <E> Type of object in this stack
42 *
43 * @see java.util.Stack
44 * @since Digester 1.6 (from Commons Collections 1.0)
45 */
46 public class ArrayStack<E> extends ArrayList<E> {
47
48 /** Ensure serialization compatibility */
49 private static final long serialVersionUID = 2130079159931574599L;
50
51 /**
52 * Constructs a new empty <code>ArrayStack</code>. The initial size
53 * is controlled by <code>ArrayList</code> and is currently 10.
54 */
55 public ArrayStack() {
56 super();
57 }
58
59 /**
60 * Constructs a new empty <code>ArrayStack</code> with an initial size.
61 *
62 * @param initialSize the initial size to use
63 * @throws IllegalArgumentException if the specified initial size
64 * is negative
65 */
66 public ArrayStack(int initialSize) {
67 super(initialSize);
68 }
69
70 /**
71 * Return <code>true</code> if this stack is currently empty.
72 * <p>
73 * This method exists for compatibility with <code>java.util.Stack</code>.
74 * New users of this class should use <code>isEmpty</code> instead.
75 *
76 * @return true if the stack is currently empty
77 */
78 public boolean empty() {
79 return isEmpty();
80 }
81
82 /**
83 * Returns the top item off of this stack without removing it.
84 *
85 * @return the top item on the stack
86 * @throws EmptyStackException if the stack is empty
87 */
88 public E peek() throws EmptyStackException {
89 int n = size();
90 if (n <= 0) {
91 throw new EmptyStackException();
92 } else {
93 return get(n - 1);
94 }
95 }
96
97 /**
98 * Returns the n'th item down (zero-relative) from the top of this
99 * stack without removing it.
100 *
101 * @param n the number of items down to go
102 * @return the n'th item on the stack, zero relative
103 * @throws EmptyStackException if there are not enough items on the
104 * stack to satisfy this request
105 */
106 public E peek(int n) throws EmptyStackException {
107 int m = (size() - n) - 1;
108 if (m < 0) {
109 throw new EmptyStackException();
110 } else {
111 return get(m);
112 }
113 }
114
115 /**
116 * Pops the top item off of this stack and return it.
117 *
118 * @return the top item on the stack
119 * @throws EmptyStackException if the stack is empty
120 */
121 public E pop() throws EmptyStackException {
122 int n = size();
123 if (n <= 0) {
124 throw new EmptyStackException();
125 } else {
126 return remove(n - 1);
127 }
128 }
129
130 /**
131 * Pushes a new item onto the top of this stack. The pushed item is also
132 * returned. This is equivalent to calling <code>add</code>.
133 *
134 * @param item the item to be added
135 * @return the item just pushed
136 */
137 public E push(E item) {
138 add(item);
139 return item;
140 }
141 }
142