Class SearchHistory

java.lang.Object
ca.phon.util.SearchHistory
public final class SearchHistory extends Object

Search history manager that stores comprehensive search entries in user preferences using context-based prefixes. This class provides static methods for managing search history entries with support for adding, updating, deleting, and retrieving search history entries across different contexts using prefix-based organization.

The search history is stored using the Java Preferences API and persists across application sessions. Different search contexts can maintain separate histories by using unique prefixes (e.g., "query.phonex", "search.participant").

Each search history entry includes:

  • Date and time of the search
  • Query text that was searched
  • Query type (e.g., "phonex", "regex", "plain")
  • Case sensitivity setting
  • Optional parameters/filter options

Features:

  • Static utility methods with context prefixes for multiple independent histories
  • Configurable maximum history size with automatic cleanup
  • Most recently used ordering - new entries are added to the front
  • Duplicate detection - existing entries are moved to front when re-added
  • Persistence using Java Preferences API
  • Thread-safe operations

Usage example: 

 String prefix = "query.phonex";
 SearchHistoryEntry entry = SearchHistoryEntry.builder()
         .queryText("phoneme transcription")
         .queryType("phonex")
         .caseSensitive(false)
         .parameter("target", "IPA Target")
         .build();
 SearchHistory.addSearchEntry(prefix, entry);
 List<SearchHistoryEntry> recent = SearchHistory.getSearchEntries(prefix);

  • Field Details

    • DEFAULT_MAX_ENTRIES

      public static final int DEFAULT_MAX_ENTRIES
      Default maximum number of search entries to maintain
      See Also:

  • Method Details

    • addSearchEntry

      public static void addSearchEntry(String prefix, SearchHistoryEntry entry)
      Adds a new search entry to the history for the given prefix. If an entry with the same query text and parameters already exists, it is removed before adding the new entry to the front of the list. If the history exceeds the maximum size, the oldest entries are removed.
      Parameters:
      prefix - the prefix for the search history context
      entry - the search entry to add (cannot be null)
      Throws:
      IllegalArgumentException - if prefix or entry is null

    • addSearchEntry

      public static void addSearchEntry(String prefix, SearchHistoryEntry entry, int maxEntries)
      Adds a new search entry to the history for the given prefix with a specific maximum size. If an entry with the same query text and parameters already exists, it is removed before adding the new entry to the front of the list. If the history exceeds the maximum size, the oldest entries are removed.
      Parameters:
      prefix - the prefix for the search history context
      entry - the search entry to add (cannot be null)
      maxEntries - maximum number of entries to maintain (must be > 0)
      Throws:
      IllegalArgumentException - if prefix or entry is null, or maxEntries invalid input: '<'= 0

    • updateSearchEntry

      public static void updateSearchEntry(String prefix, SearchHistoryEntry oldEntry, SearchHistoryEntry newEntry)
      Updates an existing search entry in the history for the given prefix. If the old entry exists, it is replaced with the new entry at the same position. If the old entry doesn't exist, the new entry is added to the front.
      Parameters:
      prefix - the prefix for the search history context
      oldEntry - the entry to replace
      newEntry - the replacement entry (cannot be null)
      Throws:
      IllegalArgumentException - if prefix or newEntry is null

    • updateSearchEntry

      public static void updateSearchEntry(String prefix, SearchHistoryEntry oldEntry, SearchHistoryEntry newEntry, int maxEntries)
      Updates an existing search entry in the history for the given prefix with a specific maximum size. If the old entry exists, it is replaced with the new entry at the same position. If the old entry doesn't exist, the new entry is added to the front.
      Parameters:
      prefix - the prefix for the search history context
      oldEntry - the entry to replace
      newEntry - the replacement entry (cannot be null)
      maxEntries - maximum number of entries to maintain (must be > 0)
      Throws:
      IllegalArgumentException - if prefix or newEntry is null, or maxEntries invalid input: '<'= 0

    • deleteSearchEntry

      public static boolean deleteSearchEntry(String prefix, SearchHistoryEntry entry)
      Removes a search entry from the history for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      entry - the entry to remove
      Returns:
      true if the entry was found and removed, false otherwise
      Throws:
      IllegalArgumentException - if prefix is null

    • deleteSearchEntry

      public static SearchHistoryEntry deleteSearchEntry(String prefix, int index)
      Removes a search entry at the specified index for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      index - the index of the entry to remove
      Returns:
      the removed entry
      Throws:
      IllegalArgumentException - if prefix is null
      IndexOutOfBoundsException - if index is out of range

    • getSearchEntries

      public static List<SearchHistoryEntry> getSearchEntries(String prefix)
      Retrieves all search entries for the given prefix in most-recently-used order. The returned list is a copy and modifications will not affect the stored history.
      Parameters:
      prefix - the prefix for the search history context
      Returns:
      a new list containing all search entries (never null)
      Throws:
      IllegalArgumentException - if prefix is null

    • getSearchEntries

      public static List<SearchHistoryEntry> getSearchEntries(String prefix, int limit)
      Retrieves up to the specified number of most recent search entries for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      limit - maximum number of entries to return
      Returns:
      a new list containing the most recent entries (never null)
      Throws:
      IllegalArgumentException - if prefix is null or limit invalid input: '<' 0

    • getMostRecentEntry

      public static SearchHistoryEntry getMostRecentEntry(String prefix)
      Gets the most recent search entry for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      Returns:
      the most recent entry, or null if history is empty
      Throws:
      IllegalArgumentException - if prefix is null

    • containsEntry

      public static boolean containsEntry(String prefix, SearchHistoryEntry entry)
      Checks if the history for the given prefix contains the specified entry.
      Parameters:
      prefix - the prefix for the search history context
      entry - the entry to check for
      Returns:
      true if the entry exists in the history
      Throws:
      IllegalArgumentException - if prefix is null

    • findEntriesByQueryText

      public static List<SearchHistoryEntry> findEntriesByQueryText(String prefix, String queryText)
      Finds entries that match the given query text for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      queryText - the query text to search for
      Returns:
      a list of matching entries (never null)
      Throws:
      IllegalArgumentException - if prefix is null

    • findEntriesByQueryType

      public static List<SearchHistoryEntry> findEntriesByQueryType(String prefix, SearchType queryType)
      Finds entries that match the given query type for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      queryType - the query type to search for
      Returns:
      a list of matching entries (never null)
      Throws:
      IllegalArgumentException - if prefix is null

    • findEntriesByParameter

      public static List<SearchHistoryEntry> findEntriesByParameter(String prefix, String parameterKey)
      Finds entries that contain the specified parameter for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      parameterKey - the parameter key to search for
      Returns:
      a list of matching entries (never null)
      Throws:
      IllegalArgumentException - if prefix is null

    • findEntriesByParameterValue

      public static List<SearchHistoryEntry> findEntriesByParameterValue(String prefix, String parameterKey, String parameterValue)
      Finds entries that have a specific parameter value for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      parameterKey - the parameter key
      parameterValue - the parameter value to search for
      Returns:
      a list of matching entries (never null)
      Throws:
      IllegalArgumentException - if prefix is null

    • addSimpleSearchEntry

      public static SearchHistoryEntry addSimpleSearchEntry(String prefix, String queryText, SearchType queryType)
      Adds a simple search entry with just query text and type for the given prefix. This is a convenience method for basic search entries.
      Parameters:
      prefix - the prefix for the search history context
      queryText - the query text
      queryType - the query type
      Returns:
      the created entry that was added
      Throws:
      IllegalArgumentException - if prefix, queryText or queryType is null or empty

    • addSimpleSearchEntry

      public static SearchHistoryEntry addSimpleSearchEntry(String prefix, String queryText, SearchType queryType, boolean caseSensitive)
      Adds a simple search entry with query text, type, and case sensitivity for the given prefix. This is a convenience method for basic search entries.
      Parameters:
      prefix - the prefix for the search history context
      queryText - the query text
      queryType - the query type
      caseSensitive - whether the search is case sensitive
      Returns:
      the created entry that was added
      Throws:
      IllegalArgumentException - if prefix, queryText or queryType is null or empty

    • size

      public static int size(String prefix)
      Gets the current number of entries in the history for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      Returns:
      the number of entries
      Throws:
      IllegalArgumentException - if prefix is null

    • isEmpty

      public static boolean isEmpty(String prefix)
      Checks if the history for the given prefix is empty.
      Parameters:
      prefix - the prefix for the search history context
      Returns:
      true if the history contains no entries
      Throws:
      IllegalArgumentException - if prefix is null

    • clear

      public static void clear(String prefix)
      Removes all entries from the search history for the given prefix.
      Parameters:
      prefix - the prefix for the search history context
      Throws:
      IllegalArgumentException - if prefix is null

    • getHistoryPrefixesWithPattern

      public static List<String> getHistoryPrefixesWithPattern(String prefixPattern)
      Retrieves all search history prefixes that match the given prefix pattern. This is useful for finding related search histories or implementing wildcard-based searches.
      Parameters:
      prefixPattern - the prefix pattern to match against history prefixes
      Returns:
      a list of history prefixes that start with the given pattern (never null)
      Throws:
      IllegalArgumentException - if prefixPattern is null

    • getAllHistoryPrefixes

      public static List<String> getAllHistoryPrefixes()
      Retrieves all search history prefixes stored in user preferences. This returns all SearchHistory prefixes that have been created and have data.
      Returns:
      a list of all history prefixes (never null)

    • deleteHistoriesWithPattern

      public static int deleteHistoriesWithPattern(String prefixPattern)
      Deletes all search histories that match the given prefix pattern. This is useful for bulk cleanup operations.
      Parameters:
      prefixPattern - the prefix pattern to match against history prefixes
      Returns:
      the number of histories that were deleted
      Throws:
      IllegalArgumentException - if prefixPattern is null

    • existsHistoryWithPattern

      public static boolean existsHistoryWithPattern(String prefixPattern)
      Checks if any search histories exist with the given prefix pattern.
      Parameters:
      prefixPattern - the prefix pattern to match against history prefixes
      Returns:
      true if at least one history exists with the given pattern
      Throws:
      IllegalArgumentException - if prefixPattern is null

    • getHistoryCountWithPattern

      public static int getHistoryCountWithPattern(String prefixPattern)
      Gets the total number of search histories that match the given prefix pattern.
      Parameters:
      prefixPattern - the prefix pattern to match against history prefixes
      Returns:
      the count of matching histories
      Throws:
      IllegalArgumentException - if prefixPattern is null