KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tomcat > util > digester > ArrayStack


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