# Class: com.pnfsoftware.jeb.util.collect.ItemHistory

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: ItemHistory

Description: Create a history with a capacity of 100 and `cleanHistoryAfterIndex` set to true.

## Constructor: ItemHistory
- parameter: `capacity`, type: `int`
- parameter: `cleanHistoryAfterIndex`, type: `boolean`

Description: Create a history object with the provided capacity.
parameter: capacity: maximum capacity, must be at least 1
parameter: 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: add
- parameter: `item`, type: `T`

Description: 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()](#getPrevious()) method was called without restoring position\)
parameter: item: non\-null item

## Method: addAll
- parameter: `items`, type: `java.util.Collection<T>`

Description: 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()](#getPrevious()) method was called without restoring position\)
parameter: items: a collection of non\-null items

## Method: capacity
- return type: `int`

Description: Get the history maximum capacity.
return: maximum number of retained history items

## Method: capacity
- parameter: `capacity`, type: `int`

Description: Update the history capacity.
parameter: capacity: maximum number of retained history items

## Method: getCopyOfItems
- return type: `java.util.List<T>`

Description: Retrieve a copy of the history items. The first item in the returned list is the oldest one.
return: copy of the history

## Method: getMostRecent
- return type: `T`

Description: Retrieve the most recently added item.
return: most recent item, or null if the history is empty

## Method: getNext
- return type: `T`

Description: Move to the next history item.
return: next item, or null if none exists

## Method: getNext
- parameter: `updatedItem`, type: `T`
- return type: `T`

Description: Move to the next history item and optionally update it.
parameter: updatedItem: optional replacement for the returned item
return: next item, or null if none exists

## Method: getPrevious
- return type: `T`

Description: Move to the previous history item.
return: previous item, or null if none exists

## Method: getPrevious
- parameter: `updatedItem`, type: `T`
- return type: `T`

Description: Move to the previous history item and optionally update it.
parameter: updatedItem: optional replacement for the returned item
return: previous item, or null if none exists

## Method: getViewOfItems
- return type: `java.util.List<T>`

Description: Retrieve a read\-only view of the history items.
return: read\-only history view, oldest item first

## Method: hasNext
- return type: `boolean`

Description: 
return: true if a next item exists

## Method: hasPrevious
- return type: `boolean`

Description: 
return: true if a previous item exists

## Method: peekNext
- return type: `T`

Description: Peek at the next history item without moving the position.
return: next item, or null if none exists

## Method: peekPrevious
- return type: `T`

Description: Peek at the previous history item without moving the position.
return: previous item, or null if none exists

## Method: position
- return type: `int`

Description: Get the current history index. Navigating the history using getNext\(\), getPrevious\(\), or modifying the history using add\(\),remove\(\), etc. updates this pointer.
return: current history index

## Method: remove
- parameter: `item`, type: `T`
- return type: `boolean`

Description: Remove the most recent item in history equals to the provided item.
parameter: item: item to remove
return: true if an item was removed

## Method: reset

Description: Clear the history and reset the position.

## Method: setIndex
- parameter: `i`, type: `int`
- parameter: `updatedItem`, type: `T`
- return type: `T`

Description: Set the current index. The item is also retrieved and optionally swapped with a non\-null new item.
parameter: i: new index
parameter: updatedItem: optional new item to place at \[i\]
return: the item at \[i\], or null

## Method: size
- return type: `int`

Description: 
return: number of history items

## Method: toString
- return type: `java.lang.String`


