## gate.util
Class WeakBumpyStack

    java.lang.Object
      |
      +--java.util.AbstractCollection
            |
            +--java.util.AbstractList
                  |
                  +--gate.util.WeakBumpyStack

All Implemented Interfaces:
  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.

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.
`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, 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
`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.

### get

    public Object get(int index)

  Returns the element at the specified position in this list.
  Overrides:
    `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.
  Overrides:
    `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.
  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).
  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).
  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())`.