001: /* $Id: ArrayStack.java 467222 2006-10-24 03:17:11Z markt $
002: *
003: * Licensed to the Apache Software Foundation (ASF) under one or more
004: * contributor license agreements. See the NOTICE file distributed with
005: * this work for additional information regarding copyright ownership.
006: * The ASF licenses this file to You under the Apache License, Version 2.0
007: * (the "License"); you may not use this file except in compliance with
008: * the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS,
014: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015: * See the License for the specific language governing permissions and
016: * limitations under the License.
017: */
018: package org.apache.tomcat.util.digester;
019:
020: import java.util.ArrayList;
021: import java.util.EmptyStackException;
022:
023: /**
024: * <p>Imported copy of the <code>ArrayStack</code> class from
025: * Commons Collections, which was the only direct dependency from Digester.</p>
026: *
027: * <p><strong>WARNNG</strong> - This class is public solely to allow it to be
028: * used from subpackages of <code>org.apache.commons.digester</code>.
029: * It should not be considered part of the public API of Commons Digester.
030: * If you want to use such a class yourself, you should use the one from
031: * Commons Collections directly.</p>
032: *
033: * <p>An implementation of the {@link java.util.Stack} API that is based on an
034: * <code>ArrayList</code> instead of a <code>Vector</code>, so it is not
035: * synchronized to protect against multi-threaded access. The implementation
036: * is therefore operates faster in environments where you do not need to
037: * worry about multiple thread contention.</p>
038: *
039: * <p>Unlike <code>Stack</code>, <code>ArrayStack</code> accepts null entries.
040: * </p>
041: *
042: * @see java.util.Stack
043: * @since Digester 1.6 (from Commons Collections 1.0)
044: */
045: public class ArrayStack extends ArrayList {
046:
047: /** Ensure serialization compatibility */
048: private static final long serialVersionUID = 2130079159931574599L;
049:
050: /**
051: * Constructs a new empty <code>ArrayStack</code>. The initial size
052: * is controlled by <code>ArrayList</code> and is currently 10.
053: */
054: public ArrayStack() {
055: super ();
056: }
057:
058: /**
059: * Constructs a new empty <code>ArrayStack</code> with an initial size.
060: *
061: * @param initialSize the initial size to use
062: * @throws IllegalArgumentException if the specified initial size
063: * is negative
064: */
065: public ArrayStack(int initialSize) {
066: super (initialSize);
067: }
068:
069: /**
070: * Return <code>true</code> if this stack is currently empty.
071: * <p>
072: * This method exists for compatibility with <code>java.util.Stack</code>.
073: * New users of this class should use <code>isEmpty</code> instead.
074: *
075: * @return true if the stack is currently empty
076: */
077: public boolean empty() {
078: return isEmpty();
079: }
080:
081: /**
082: * Returns the top item off of this stack without removing it.
083: *
084: * @return the top item on the stack
085: * @throws EmptyStackException if the stack is empty
086: */
087: public Object peek() throws EmptyStackException {
088: int n = size();
089: if (n <= 0) {
090: throw new EmptyStackException();
091: } else {
092: return get(n - 1);
093: }
094: }
095:
096: /**
097: * Returns the n'th item down (zero-relative) from the top of this
098: * stack without removing it.
099: *
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 peek(int n) throws EmptyStackException {
106: int m = (size() - n) - 1;
107: if (m < 0) {
108: throw new EmptyStackException();
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 pop() throws EmptyStackException {
121: int n = size();
122: if (n <= 0) {
123: throw new EmptyStackException();
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 push(Object item) {
137: add(item);
138: return item;
139: }
140:
141: /**
142: * Returns the one-based position of the distance from the top that the
143: * specified object exists on this stack, where the top-most element is
144: * considered to be at distance <code>1</code>. If the object is not
145: * present on the stack, return <code>-1</code> instead. The
146: * <code>equals()</code> method is used to compare to the items
147: * in this stack.
148: *
149: * @param object the object to be searched for
150: * @return the 1-based depth into the stack of the object, or -1 if not found
151: */
152: public int search(Object object) {
153: int i = size() - 1; // Current index
154: int n = 1; // Current distance
155: while (i >= 0) {
156: Object current = get(i);
157: if ((object == null && current == null)
158: || (object != null && object.equals(current))) {
159: return n;
160: }
161: i--;
162: n++;
163: }
164: return -1;
165: }
166:
167: }
|