# Class SearchResultCache

java.lang.Object
com.university.bookstore.search.SearchResultCache

public class SearchResultCache extends Object
LRU (Least Recently Used) cache for search results. Evicts least recently used items when the cache reaches its maximum size.

This implementation provides O(1) average time complexity for get and put operations by using a HashMap for O(1) lookups and a Deque for O(1) access order tracking.

Since:
  2024-09-15
Version:
  3.0
Author:
  Navid Mohaghegh

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `SearchResultCache.CacheStats`
  Statistics class for cache performance monitoring.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SearchResultCache(int maxSize)`
  Creates a new search result cache with the specified maximum size.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Clears all entries from the cache.
  `boolean`
  `containsKey(String key)`
  Checks if the cache contains results for the given key.
  `Optional<List<Material>>`
  `get(String key)`
  Retrieves cached search results for the given key.
  `int`
  `getMaxSize()`
  Gets the maximum number of entries the cache can hold.
  `SearchResultCache.CacheStats`
  `getStats()`
  Gets cache statistics including hit ratio and average age.
  `boolean`
  `isEmpty()`
  Checks if the cache is empty.
  `boolean`
  `isFull()`
  Checks if the cache is full.
  `void`
  `put(String key, List<Material> results)`
  Stores search results in the cache with the given key.
  `boolean`
  `remove(String key)`
  Removes the entry with the given key from the cache.
  `int`
  `size()`
  Gets the current number of entries in the cache.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### SearchResultCache

    public SearchResultCache(int maxSize)
    Creates a new search result cache with the specified maximum size.
    Parameters:
      `maxSize` - the maximum number of entries the cache can hold
    Throws:
      `IllegalArgumentException` - if maxSize is not positive

- ## Method Details

  - ### get

    public Optional<List<Material>> get(String key)
    Retrieves cached search results for the given key. Updates the access order to mark this entry as recently used.
    Parameters:
      `key` - the cache key
    Returns:
      Optional containing the cached results if found

  - ### put

    public void put(String key, List<Material> results)
    Stores search results in the cache with the given key. Evicts the least recently used entry if the cache is full.
    Parameters:
      `key` - the cache key
      `results` - the search results to cache
    Throws:
      `IllegalArgumentException` - if key is null

  - ### containsKey

    public boolean containsKey(String key)
    Checks if the cache contains results for the given key.
    Parameters:
      `key` - the cache key
    Returns:
      true if the key exists in the cache

  - ### remove

    public boolean remove(String key)
    Removes the entry with the given key from the cache.
    Parameters:
      `key` - the cache key to remove
    Returns:
      true if an entry was removed, false if key not found

  - ### clear

    public void clear()
    Clears all entries from the cache.

  - ### size

    public int size()
    Gets the current number of entries in the cache.
    Returns:
      the cache size

  - ### getMaxSize

    public int getMaxSize()
    Gets the maximum number of entries the cache can hold.
    Returns:
      the maximum cache size

  - ### isEmpty

    public boolean isEmpty()
    Checks if the cache is empty.
    Returns:
      true if no entries are cached

  - ### isFull

    public boolean isFull()
    Checks if the cache is full.
    Returns:
      true if the cache has reached its maximum size

  - ### getStats

    public SearchResultCache.CacheStats getStats()
    Gets cache statistics including hit ratio and average age.
    Returns:
      cache statistics

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`