Package fr.gouv.vitam.storage.offers.tape.cache

# Class LRUCache<T>

java.lang.Object
fr.gouv.vitam.storage.offers.tape.cache.LRUCache<T>

Type Parameters:
  `T` - the type of entry keys maintained by this cache.

@ThreadSafe public class LRUCache<T> extends Object
Cache implementation with Least Recently Used (LRU) eviction policy, weighed entry capacity management, and eviction filtering for in-use/non-deletable entries. Before adding an entry, a reservation is done to ensure enough capacity is available. Once reservation done, entry can be added (by confirming reservation) ou canceled (by canceling reservation). Eviction handling is done asynchronously when reserving new entries in the cache reaches eviction capacity threshold. Reserved entries are not evicted since they are not yet added. If cache capacity exceeds its max capacity threshold, the entry reservation will fail with an exception. The eviction process ends when target eviction capacity threshold is reached, or no more entries to evict. During eviction process, entry eviction can be controlled using a ``, which allows filtering of entries that cannot be evicted (currently locked). After an entry is evicted, a listener is invoked for eviction notification. When created, a cache must be initialized with a list of initial list of entries. Background eviction process may be triggered at the end of initialization is required. This class is Thread-Safe (all public methods are synchronized).

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LRUCache(long maxCapacity, long evictionCapacity, long safeCapacity, Supplier<LRUCacheEvictionJudge<T>> evictionJudgeFactory, Consumer<T> evictionListener, Stream<LRUCacheEntry<T>> initialEntries, Executor evictionExecutor, AlertService alertService)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cancelReservation(T entryKey)`
  Cancels the reservation of a reserved entry and free-up cache capacity accordingly.
  `void`
  `confirmReservation(T entryKey)`
  Confirm the reservation of a reserved entry and adds it to the cache.
  `boolean`
  `containsEntry(T entryKey)`
  Returns `true` if this cache contains the specified entry.
  `long`
  `getCurrentCapacity()`
  `long`
  `getEvictionCapacity()`
  `long`
  `getMaxCapacity()`
  `LRUCacheEntry<T>`
  `getReservedEntry(T entryKey)`
  Returns `true` if specified entry key is reserved in the cache.
  `long`
  `getSafeCapacity()`
  `boolean`
  `isCacheEvictionRunning()`
  `boolean`
  `isReservedEntry(T entryKey)`
  Returns `true` if specified entry key is reserved in the cache.
  `void`
  `reserveEntry(LRUCacheEntry<T> entry)`
  Reserve cache capacity for a new entry to add the cache.
  `boolean`
  `updateEntryAccessTimestamp(T entryKey, Instant updatedLastAccessInstant)`
  Try update an existing (reserved or added) entry last access timestamp.

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### LRUCache

    public LRUCache(long maxCapacity, long evictionCapacity, long safeCapacity, Supplier<LRUCacheEvictionJudge<T>> evictionJudgeFactory, Consumer<T> evictionListener, Stream<LRUCacheEntry<T>> initialEntries, Executor evictionExecutor, AlertService alertService) throws IllegalArgumentException
    Parameters:
      `maxCapacity` - Max cache storage capacity. Once reached, adding new entries fails.
      `evictionCapacity` - Once reached, background eviction process is started to purge cache of old unused entries.
      `safeCapacity` - Safe capacity level. Cache eviction process stops when cache capacity is bellow safe cache threshold.
      `evictionJudgeFactory` - factory that instantiates an eviction judge (`LRUCacheEvictionJudge`) used by background eviction process for entry eviction filtering. A new eviction judge is created before each eviction.
      `evictionListener` - listener invoked (synchronously) when an expired entry as been evicted from cache.
      `initialEntries` - stream of cache entries to add to cache. Entries mush have distinct keys.
      `evictionExecutor` - Executor for running eviction process asynchronously.
      `alertService` - alert service that is used for reporting cache capacity alerts.
    Throws:
      `IllegalArgumentException` - when provided parameters have illegal values.

- ## Method Details

  - ### reserveEntry

    public void reserveEntry(LRUCacheEntry<T> entry) throws IllegalArgumentException, IllegalStateException
    Reserve cache capacity for a new entry to add the cache. An entry reservation can be confirmed using the `confirmReservation()` method, or canceled using the `cancelReservation()` method. If entry already exists in the cache, an `IllegalArgumentException` is thrown.
    Parameters:
      `entry` - the entry to reserve in cache
    Throws:
      `IllegalArgumentException` - when provided parameters have illegal values.
      `IllegalStateException` - when cache max capacity is reached.

  - ### confirmReservation

    public void confirmReservation(T entryKey) throws IllegalArgumentException
    Confirm the reservation of a reserved entry and adds it to the cache.
    Parameters:
      `entryKey` - the entry key whose reservation is to be confirmed.
    Throws:
      `IllegalArgumentException` - when provided parameters have illegal values, or entry is not reserved in cache.

  - ### cancelReservation

    public void cancelReservation(T entryKey)
    Cancels the reservation of a reserved entry and free-up cache capacity accordingly.
    Parameters:
      `entryKey` - the entry key whose reservation is to be canceled.
    Throws:
      `IllegalArgumentException` - when provided parameters have illegal values, or entry is not reserved in cache.

  - ### updateEntryAccessTimestamp

    public boolean updateEntryAccessTimestamp(T entryKey, Instant updatedLastAccessInstant) throws IllegalArgumentException
    Try update an existing (reserved or added) entry last access timestamp. If entry does not already exist (anymore?) in cache, no update occurs.
    Parameters:
      `entryKey` - the key of the entry to update
    Returns:
      `true` if the entry timestamp has been updated, `false` if entry does not exist in cache.
    Throws:
      `IllegalArgumentException` - when provided parameters have illegal values.

  - ### containsEntry

    public boolean containsEntry(T entryKey) throws IllegalArgumentException
    Returns `true` if this cache contains the specified entry. Reserved entries (not yet confirmed) or non-existing entries in the cache return `false`
    Parameters:
      `entryKey` - the entry key whose presence in this cache is to be tested
    Returns:
      `true` if the entry exists in the cache, `false` otherwise.
    Throws:
      `IllegalArgumentException` - when provided parameters have illegal values.

  - ### isReservedEntry

    public boolean isReservedEntry(T entryKey) throws IllegalArgumentException
    Returns `true` if specified entry key is reserved in the cache.
    Parameters:
      `entryKey` - the entry key whose reservation status is to be tested
    Returns:
      `true` if the entry is reserved, otherwise `false`.
    Throws:
      `IllegalArgumentException` - when provided parameters have illegal values.

  - ### getReservedEntry

    public LRUCacheEntry<T> getReservedEntry(T entryKey) throws IllegalArgumentException
    Returns `true` if specified entry key is reserved in the cache.
    Parameters:
      `entryKey` - the entry key whose reservation status is to be tested
    Returns:
      `true` if the entry is reserved, otherwise `false`.
    Throws:
      `IllegalArgumentException` - when provided parameters have illegal values.

  - ### getMaxCapacity

    public long getMaxCapacity()
    Returns:
      Max cache storage capacity of the cache. Once reached, adding new entries fails.

  - ### getEvictionCapacity

    public long getEvictionCapacity()
    Returns:
      eviction capacity threshold. Once reached, background eviction process is started to purge cache of old unused entries.

  - ### getSafeCapacity

    public long getSafeCapacity()
    Returns:
      Safe capacity level threshold. Cache eviction process stops when cache capacity is bellow safe cache threshold.

  - ### getCurrentCapacity

    public long getCurrentCapacity()
    Returns:
      Current cache capacity.

  - ### isCacheEvictionRunning

    public boolean isCacheEvictionRunning()