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
18package java.util;
19
20/**
21 * {@code Stack} is a Last-In/First-Out(LIFO) data structure which represents a
22 * stack of objects. It enables users to pop to and push from the stack,
23 * including null objects. There is no limit to the size of the stack.
24 */
25public class Stack<E> extends Vector<E> {
26
27    private static final long serialVersionUID = 1224463164541339165L;
28
29    /**
30     * Constructs a stack with the default size of {@code Vector}.
31     */
32    public Stack() {
33    }
34
35    /**
36     * Returns whether the stack is empty or not.
37     *
38     * @return {@code true} if the stack is empty, {@code false} otherwise.
39     */
40    public boolean empty() {
41        return isEmpty();
42    }
43
44    /**
45     * Returns the element at the top of the stack without removing it.
46     *
47     * @return the element at the top of the stack.
48     * @throws EmptyStackException
49     *             if the stack is empty.
50     * @see #pop
51     */
52    @SuppressWarnings("unchecked")
53    public synchronized E peek() {
54        try {
55            return (E) elementData[elementCount - 1];
56        } catch (IndexOutOfBoundsException e) {
57            throw new EmptyStackException();
58        }
59    }
60
61    /**
62     * Returns the element at the top of the stack and removes it.
63     *
64     * @return the element at the top of the stack.
65     * @throws EmptyStackException
66     *             if the stack is empty.
67     * @see #peek
68     * @see #push
69     */
70    @SuppressWarnings("unchecked")
71    public synchronized E pop() {
72        if (elementCount == 0) {
73            throw new EmptyStackException();
74        }
75        final int index = --elementCount;
76        final E obj = (E) elementData[index];
77        elementData[index] = null;
78        modCount++;
79        return obj;
80    }
81
82    /**
83     * Pushes the specified object onto the top of the stack.
84     *
85     * @param object
86     *            The object to be added on top of the stack.
87     * @return the object argument.
88     * @see #peek
89     * @see #pop
90     */
91    public E push(E object) {
92        addElement(object);
93        return object;
94    }
95
96    /**
97     * Returns the index of the first occurrence of the object, starting from
98     * the top of the stack.
99     *
100     * @return the index of the first occurrence of the object, assuming that
101     *         the topmost object on the stack has a distance of one.
102     * @param o
103     *            the object to be searched.
104     */
105    public synchronized int search(Object o) {
106        final Object[] dumpArray = elementData;
107        final int size = elementCount;
108        if (o != null) {
109            for (int i = size - 1; i >= 0; i--) {
110                if (o.equals(dumpArray[i])) {
111                    return size - i;
112                }
113            }
114        } else {
115            for (int i = size - 1; i >= 0; i--) {
116                if (dumpArray[i] == null) {
117                    return size - i;
118                }
119            }
120        }
121        return -1;
122    }
123}
124