org.jumpi.impl.util
Class Stack

java.lang.Object
  |
  +--org.jumpi.impl.util.Stack

public class Stack

extends java.lang.Object

A Stack collection class which exhibits unbounded, synchronous first-in-last-out ( FILO ) behaviour.

Elements are placed on the top of the Stack using the pushElement(java.lang.Object) operation. Elements are taken off the top of the Stack using the popElement() operation. The popElement operation blocks until there is an element on the Stack. Use peekElement() or size() to check if there are elements on the Stack to avoid blocking.

Constructor Summary

Stack()
Creates a new Stack object.

Stack(int capacity)
Creates a new Stack object.

Method Summary

void	close() Close the Stack.
java.lang.Object	peekElement() Peek to see if there is an element on the Stack, without removing it.
java.lang.Object	popElement() Pop the top element off the Stack.
java.lang.Object	popElement(long timeout) Pop the top element off the Stack.
void	pushElement(java.lang.Object o) Put an Object on the top of the Stack.
int	size() Return the number of elements on the Stack.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Stack

public Stack()

Creates a new Stack object.

Stack

public Stack(int capacity)

Creates a new Stack object.

Parameters:

capacity - the initial capacity of the stack

Method Detail

pushElement

public void pushElement(java.lang.Object o)

Put an Object on the top of the Stack. The Stack is unbounded, so will eventually cause memory overflow if used inappropriately. The Object may not be null since it would be impossible to differentiate between a null element and when peekElement returns no element. Never blocks.

Parameters:

o - the Object to put on the top of the Stack.

Throws:

java.lang.IllegalArgumentException - if o is null

java.lang.IllegalStateException - if the Stack is closed.

peekElement

public java.lang.Object peekElement()

Peek to see if there is an element on the Stack, without removing it. Never blocks the calling Thread.

Returns:

the top element on the Stack.

Throws:

java.lang.IllegalStateException - if the Stack is closed.

popElement

public java.lang.Object popElement()

Pop the top element off the Stack. Blocks the calling Thread until there is an element to return or the Stack is closed. The element is removed from the Stack.

Returns:

the top element on the Stack.

Throws:

java.lang.IllegalStateException - if the Stack is closed on entry.

popElement

public java.lang.Object popElement(long timeout)

Pop the top element off the Stack. Blocks the calling Thread until either there is an element to return, or a timeout occurs. The element is removed from the Stack.

Parameters:

timeout - maximum time in milliseconds to wait for an element.

Returns:

the top element on the Stack or null in case of timeout.

Throws:

java.lang.IllegalStateException - if the Stack is closed on entry.

size

public int size()

Return the number of elements on the Stack.

Returns:

the number of elements on the Stack.

close

public void close()

Close the Stack. Release any Threads waiting in popElement. Once closed, the Stack is not (re)useable.