Interface History

All Superinterfaces:
Iterable<History.Entry>
All Known Implementing Classes:
DefaultHistory
public interface History extends Iterable<History.Entry>
Console command history management interface.

The History interface provides functionality for storing, retrieving, and navigating through previously entered commands. It allows users to recall and reuse commands they've typed before, which is a fundamental feature of interactive command-line interfaces.

History implementations typically support:

  • Adding new entries as commands are executed
  • Navigating backward and forward through history
  • Persisting history to a file for use across sessions
  • Filtering or ignoring certain commands based on patterns

Each history entry contains the command text along with metadata such as the timestamp when it was executed.

The default implementation is DefaultHistory.

Since:
2.3
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    History.Entry
    Represents a single history entry containing a command line and its metadata.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    add(String line)
     
    void
    add(Instant time, String line)
    Adds a new item to the history with the specified timestamp.
    void
    append(Path file, boolean incremental)
    Append history to the file.
    void
    attach(LineReader reader)
    Initialize the history for the given reader.
    String
    current()
    Return the content of the current buffer.
    int
    first()
    Returns the index of the first element in the history.
    String
    get(int index)
    Returns the history item at the specified index.
    int
    index()
    Returns the current index in the history.
    default boolean
    isEmpty()
    Checks if the history is empty.
    default boolean
    isPersistable(History.Entry entry)
    Check if an entry should be persisted or not.
    default ListIterator<History.Entry>
    iterator()
     
    ListIterator<History.Entry>
    iterator(int index)
    Returns a list iterator over the history entries starting at the specified index.
    int
    last()
    Returns the index of the last element in the history.
    void
    load()
    Load history.
    boolean
    moveTo(int index)
    Move to the specified index in the history
    void
    moveToEnd()
    Move to the end of the history buffer.
    boolean
    moveToFirst()
    Moves the history index to the first entry.
    boolean
    moveToLast()
    This moves the history to the last entry.
    boolean
    next()
    Move the pointer to the next element in the buffer.
    boolean
    previous()
    Move the pointer to the previous element in the buffer.
    void
    purge()
    Purge history.
    void
    read(Path file, boolean checkDuplicates)
    Read history from the file.
    void
    resetIndex()
    Reset index after remove
    default Iterator<History.Entry>
    reverseIterator()
     
    default Iterator<History.Entry>
    reverseIterator(int index)
     
    void
    save()
    Save history.
    int
    size()
    Returns the number of items in the history.
    void
    write(Path file, boolean incremental)
    Write history to the file.

    Methods inherited from interface Iterable

    forEach, spliterator

  • Method Details

    • attach

      void attach(LineReader reader)
      Initialize the history for the given reader.
      Parameters:
      reader - the reader to attach to

    • load

      void load() throws IOException
      Load history.
      Throws:
      IOException - if a problem occurs

    • save

      void save() throws IOException
      Save history.
      Throws:
      IOException - if a problem occurs

    • write

      void write(Path file, boolean incremental) throws IOException
      Write history to the file. If incremental only the events that are new since the last incremental operation to the file are added.
      Parameters:
      file - History file
      incremental - If true incremental write operation is performed.
      Throws:
      IOException - if a problem occurs

    • append

      void append(Path file, boolean incremental) throws IOException
      Append history to the file. If incremental only the events that are new since the last incremental operation to the file are added.
      Parameters:
      file - History file
      incremental - If true incremental append operation is performed.
      Throws:
      IOException - if a problem occurs

    • read

      void read(Path file, boolean checkDuplicates) throws IOException
      Read history from the file. If checkDuplicates is true only the events that are not contained within the internal list are added.
      Parameters:
      file - History file
      checkDuplicates - If true, duplicate history entries will be discarded
      Throws:
      IOException - if a problem occurs

    • purge

      void purge() throws IOException
      Purge history.
      Throws:
      IOException - if a problem occurs

    • size

      int size()
      Returns the number of items in the history.
      Returns:
      the number of history items

    • isEmpty

      default boolean isEmpty()
      Checks if the history is empty.
      Returns:
      true if the history contains no items

    • index

      int index()
      Returns the current index in the history.
      Returns:
      the current index

    • first

      int first()
      Returns the index of the first element in the history.
      Returns:
      the index of the first history item

    • last

      int last()
      Returns the index of the last element in the history.
      Returns:
      the index of the last history item

    • get

      String get(int index)
      Returns the history item at the specified index.
      Parameters:
      index - the index of the history item to retrieve
      Returns:
      the history item at the specified index

    • add

      default void add(String line)

    • add

      void add(Instant time, String line)
      Adds a new item to the history with the specified timestamp.
      Parameters:
      time - the timestamp for the history item
      line - the line to add to the history

    • isPersistable

      default boolean isPersistable(History.Entry entry)
      Check if an entry should be persisted or not.
      Parameters:
      entry - the entry to check
      Returns:
      true if the given entry should be persisted, false otherwise

    • iterator

      ListIterator<History.Entry> iterator(int index)
      Returns a list iterator over the history entries starting at the specified index.
      Parameters:
      index - the index to start iterating from
      Returns:
      a list iterator over the history entries

    • iterator

      default ListIterator<History.Entry> iterator()
      Specified by:
      iterator in interface Iterable<History.Entry>

    • reverseIterator

      default Iterator<History.Entry> reverseIterator()

    • reverseIterator

      default Iterator<History.Entry> reverseIterator(int index)

    • current

      String current()
      Return the content of the current buffer.
      Returns:
      the content of the current buffer

    • previous

      boolean previous()
      Move the pointer to the previous element in the buffer.
      Returns:
      true if we successfully went to the previous element

    • next

      boolean next()
      Move the pointer to the next element in the buffer.
      Returns:
      true if we successfully went to the next element

    • moveToFirst

      boolean moveToFirst()
      Moves the history index to the first entry.
      Returns:
      Return false if there are no iterator in the history or if the history is already at the beginning.

    • moveToLast

      boolean moveToLast()
      This moves the history to the last entry. This entry is one position before the moveToEnd() position.
      Returns:
      Returns false if there were no history iterator or the history index was already at the last entry.

    • moveTo

      boolean moveTo(int index)
      Move to the specified index in the history
      Parameters:
      index - The index to move to.
      Returns:
      Returns true if the index was moved.

    • moveToEnd

      void moveToEnd()
      Move to the end of the history buffer. This will be a blank entry, after all of the other iterator.

    • resetIndex

      void resetIndex()
      Reset index after remove