org.jallaby.util.Stack Maven / Gradle / Ivy
Show all versions of jallaby-core Show documentation
/*
* #%L
* Jetro Utilities
* %%
* Copyright (C) 2013 - 2016 The original author or authors.
* %%
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* #L%
*/
package org.jallaby.util;
import java.util.ArrayList;
import java.util.EmptyStackException;
import java.util.List;
/**
* Implements a LIFO stack. This class offers synchronized as well as unsynchronized methods,
* so it's up to the developer to decide whether synchronization is necessary or not. Besides,
* it offers only stack related methods, so there is no chance of accidentally corrupting the stack.
*
* This is in stark contrast to the implementation of the standard Java {@link java.util.Stack Stack}
* class.
*
* @author Matthias Rothe
* @param The type of element held in this instance
*/
public class Stack {
private List store = new ArrayList();
/**
* Pushes a new element onto the stack.
*
* This method is unsynchronized and therefore not thread-safe. If you need thread-safe access to this stack,
* use {@link #pushSynchronized(Object)} instead.
*
* @param element The element to push
*/
public void push(E element) {
store.add(element);
}
/**
* Pushes a new element onto the stack.
*
* This method is synchronized and therefore thread-safe. If you don't need thread-safe access to this stack,
* use {@link #push(Object)} instead to increase performance.
*
* @param element The element to push
*/
public synchronized void pushSynchronized(E element) {
push(element);
}
/**
* Retrieves the topmost element from this stack, without removing it.
*
* This method is unsynchronized and therefore not thread-safe. If you need thread-safe access to this stack,
* use {@link #peekSynchronized()} instead.
*
* @return The topmost element of this stack
*/
public E peek() {
return store.get(getIndex());
}
/**
* Retrieves the topmost element from this stack, without removing it.
*
* This method is synchronized and therefore thread-safe. If you don't need thread-safe access to this stack,
* use {@link #peek()} instead to increase performance.
*
* @return The topmost element of this stack
*/
public synchronized E peekSynchronized() {
return peek();
}
/**
* Retrieves and removes the topmost element from this stack.
*
* This method is unsynchronized and therefore not thread-safe. If you need thread-safe access to this stack,
* use {@link #popSynchronized()} instead.
*
* @return The topmost element of this stack
*/
public E pop() {
return store.remove(getIndex());
}
/**
* Retrieves and removes the topmost element from this stack.
*
* This method is synchronized and therefore thread-safe. If you don't need thread-safe access to this stack,
* use {@link #pop()} instead to increase performance.
*
* @return The topmost element of this stack
*/
public synchronized E popSynchronized() {
return pop();
}
/**
* Checks whether this stack is empty, e.g. has no elements.
*
* This method is unsynchronized and therefore not thread-safe. If you need thread-safe access to this stack,
* use {@link #isEmptySynchronized()} instead.
*
* @return true, if and only if this stack has no elements, false otherwise
*/
public boolean isEmpty() {
return store.isEmpty();
}
/**
* Checks whether this stack is empty, e.g. has no elements.
*
* This method is synchronized and therefore thread-safe. If you don't need thread-safe access to this stack,
* use {@link #isEmpty()} instead to increase performance.
*
* @return true, if and only if this stack has no elements, false otherwise
*/
public synchronized boolean isEmptySynchronized() {
return isEmpty();
}
/**
* Returns the number of elements on this stack. If there are more elements than
* {@link Integer#MAX_VALUE} on this stack, returns {@link Integer#MAX_VALUE}.
*
* This method is unsynchronized and therefore not thread-safe. If you need thread-safe access to this stack,
* use {@link #sizeSynchronized()} instead.
*
* @return the number of elements on this stack.
*/
public int size() {
return store.size();
}
/**
* Returns the number of elements on this stack. If there are more elements than
* {@link Integer#MAX_VALUE} on this stack, returns {@link Integer#MAX_VALUE}.
*
* This method is synchronized and therefore thread-safe. If you don't need thread-safe access to this stack,
* use {@link #size()} instead to increase performance.
*
* @return the number of elements on this stack.
*/
public synchronized int sizeSynchronized() {
return size();
}
private int getIndex() {
int index = store.size() - 1;
if (index == -1) {
throw new EmptyStackException();
}
return index;
}
}