gate.util
Class WeakBumpyStack

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractList
          gate.util.WeakBumpyStack

All Implemented Interfaces:

Iterable, Collection, List

public class WeakBumpyStack
extends AbstractList

Weak stack that allow you to bump an element to the front. Objects that are only referenced by this stack will be candidates for garbage collection and wil be removed from the stack as soon as the garbage collector marks them for collection.

*** WARNING: *** the test for this class, TestBumpyStack.testSelfCleaning is not a proper test; it doesn't fail even when it should, and only prints a warning when DEBUG is true. This is because to test it properly you need to force garbage collection, and that isn't possible. So, if you work on this class you must turn DEBUG on on TestBumpyStack in order to run the tests in a meaningfull way.

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

WeakBumpyStack()
Creates a new empty stack.

Method Summary

void	add(int index, Object element) Inserts the specified element at the specified position in this list.
boolean	bump(Object item) Bump an item to the front of the stack.
boolean	empty() Tests if this stack is empty.
Object	get(int index) Returns the element at the specified position in this list.
Object	peek() Looks at the object at the top of this stack without removing it from the stack.
Object	pop() Removes the object at the top of this stack and returns that object as the value of this function.
protected void	processQueue() Checks the queue for any new weak references that have been cleared and queued and removes them from the underlying stack.
Object	push(Object item) Pushes an item onto the top of this stack.
Object	remove(int index) Removes the element at the specified position in this list.
int	search(Object o) Returns the 1-based position where an object is on this stack.
Object	set(int index, Object element) Replaces the element at the specified position in this list with the specified element.
int	size() Returns the number of elements in this list.

Methods inherited from class java.util.AbstractList

add, addAll, clear, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, removeRange, subList

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray

Constructor Detail

WeakBumpyStack

public WeakBumpyStack()

Creates a new empty stack.

Method Detail

push

public Object push(Object item)

Pushes an item onto the top of this stack. This has exactly the same effect as:

 addElement(item)

Parameters:

item - the item to be pushed onto this stack.

Returns:

the item argument.

pop

public Object pop()

Removes the object at the top of this stack and returns that object as the value of this function.

Returns:

The object at the top of this stack.

Throws:

EmptyStackException - if this stack is empty.

peek

public Object peek()

Looks at the object at the top of this stack without removing it from the stack.

Returns:

the object at the top of this stack.

Throws:

EmptyStackException - if this stack is empty.

empty

public boolean empty()

Tests if this stack is empty.

Returns:

true if and only if this stack contains no items; false otherwise.

bump

public boolean bump(Object item)

Bump an item to the front of the stack.

Parameters:

item - the item to bump

Returns:

true when the item was found, else false

search

public int search(Object o)

Returns the 1-based position where an object is on this stack. If the object o occurs as an item in this stack, this method returns the distance from the top of the stack of the occurrence nearest the top of the stack; the topmost item on the stack is considered to be at distance 1. The equals method is used to compare o to the items in this stack.

Parameters:

o - the desired object.

Returns:

the 1-based position from the top of the stack where the object is located; the return value -1 indicates that the object is not on the stack.

processQueue

protected void processQueue()

Checks the queue for any new weak references that have been cleared and queued and removes them from the underlying stack. This method should be called by every public method before realising its internal logic.

get

public Object get(int index)

Returns the element at the specified position in this list.

Specified by:

get in interface List

Specified by:

get in class AbstractList

Parameters:

index - index of element to return.

Returns:

the element at the specified position in this list.

Throws:

IndexOutOfBoundsException - if index is out of range (index < 0 || index >= size()).

size

public int size()

Returns the number of elements in this list.

Specified by:

size in interface Collection

Specified by:

size in interface List

Specified by:

size in class AbstractCollection

Returns:

the number of elements in this list.

set

public Object set(int index,
                  Object element)

Replaces the element at the specified position in this list with the specified element.

Specified by:

set in interface List

Overrides:

set in class AbstractList

Parameters:

index - index of element to replace.

element - element to be stored at the specified position.

Returns:

the element previously at the specified position.

Throws:

IndexOutOfBoundsException - if index out of range (index < 0 || index >= size()).

add

public void add(int index,
                Object element)

Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Specified by:

add in interface List

Overrides:

add in class AbstractList

Parameters:

index - index at which the specified element is to be inserted.

element - element to be inserted.

Throws:

IndexOutOfBoundsException - if index is out of range (index < 0 || index > size()).

remove

public Object remove(int index)

Removes the element at the specified position in this list. Shifts any subsequent elements to the left (subtracts one from their indices).

Specified by:

remove in interface List

Overrides:

remove in class AbstractList

Parameters:

index - the index of the element to removed.

Returns:

the element that was removed from the list.

Throws:

IndexOutOfBoundsException - if index out of range (index < 0 || index >= size()).