Package com.pnfsoftware.jeb.util.collect

Class ItemHistory<T>

java.lang.Object
com.pnfsoftware.jeb.util.events.EventSource
com.pnfsoftware.jeb.util.collect.ItemHistory<T>
Type Parameters:
T - item type
All Implemented Interfaces:
IEventSource
public class ItemHistory<T> extends EventSource
Generic tracker of items, based on a simple history queue (get last, get next) model.

Typically, such objects are long-lived; internally, references to items are strong. Therefore, it is up to the user to make sure that referenced objects are not prevented from being garbage collected, should they be.

  • Constructor Details

    • ItemHistory

      public ItemHistory()
      Create a history with a capacity of 100 and cleanHistoryAfterIndex set to true.

    • ItemHistory

      public ItemHistory(int capacity, boolean cleanHistoryAfterIndex)
      Create a history object with the provided capacity.
      Parameters:
      capacity - maximum capacity, must be at least 1
      cleanHistoryAfterIndex - if true, recording an element into the history when the history index is not at the top will erase all elements after the index and add the new item at the top; if false, the item is inserted at the top regardless of where the history index was

  • Method Details

    • reset

      public void reset()
      Clear the history and reset the position.

    • size

      public int size()
      Returns:
      number of history items

    • capacity

      public int capacity()
      Get the history maximum capacity.
      Returns:
      maximum number of retained history items

    • capacity

      public void capacity(int capacity)
      Update the history capacity.
      Parameters:
      capacity - maximum number of retained history items

    • position

      public int position()
      Get the current history index. Navigating the history using getNext(), getPrevious(), or modifying the history using add(),remove(), etc. updates this pointer.
      Returns:
      current history index

    • add

      public void add(T item)
      Add a non-null item to the history. The index is subsequently updated to point to the top of the history.

      Note that any next item may be removed (based on cleanHistoryAfterIndex constructor parameter, in particular, if getPrevious() method was called without restoring position)

      Parameters:
      item - non-null item

    • addAll

      public void addAll(Collection<T> items)
      Add non-null items to the history. The index is subsequently updated to point to the top of the history.

      Note that any next item may be removed (based on cleanHistoryAfterIndex constructor parameter, in particular, if getPrevious() method was called without restoring position)

      Parameters:
      items - a collection of non-null items

    • remove

      public boolean remove(T item)
      Remove the most recent item in history equals to the provided item.
      Parameters:
      item - item to remove
      Returns:
      true if an item was removed

    • getMostRecent

      public T getMostRecent()
      Retrieve the most recently added item.
      Returns:
      most recent item, or null if the history is empty

    • getCopyOfItems

      public List<T> getCopyOfItems()
      Retrieve a copy of the history items. The first item in the returned list is the oldest one.
      Returns:
      copy of the history

    • getViewOfItems

      public List<T> getViewOfItems()
      Retrieve a read-only view of the history items.
      Returns:
      read-only history view, oldest item first

    • peekPrevious

      public T peekPrevious()
      Peek at the previous history item without moving the position.
      Returns:
      previous item, or null if none exists

    • peekNext

      public T peekNext()
      Peek at the next history item without moving the position.
      Returns:
      next item, or null if none exists

    • getPrevious

      public T getPrevious()
      Move to the previous history item.
      Returns:
      previous item, or null if none exists

    • getPrevious

      public T getPrevious(T updatedItem)
      Move to the previous history item and optionally update it.
      Parameters:
      updatedItem - optional replacement for the returned item
      Returns:
      previous item, or null if none exists

    • getNext

      public T getNext()
      Move to the next history item.
      Returns:
      next item, or null if none exists

    • getNext

      public T getNext(T updatedItem)
      Move to the next history item and optionally update it.
      Parameters:
      updatedItem - optional replacement for the returned item
      Returns:
      next item, or null if none exists

    • hasPrevious

      public boolean hasPrevious()
      Returns:
      true if a previous item exists

    • hasNext

      public boolean hasNext()
      Returns:
      true if a next item exists

    • setIndex

      public T setIndex(int i, T updatedItem)
      Set the current index. The item is also retrieved and optionally swapped with a non-null new item.
      Parameters:
      i - new index
      updatedItem - optional new item to place at [i]
      Returns:
      the item at [i], or null

    • toString

      public String toString()
      Overrides:
      toString in class Object