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 18 package 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 */ 25 public 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 */ Stack()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 */ empty()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") peek()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") pop()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 */ push(E object)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 */ search(Object o)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