Class TimedCache<K,V>

java.lang.Object
nl.pim16aap2.animatedarchitecture.core.data.cache.timed.TimedCache<K,V>
Type Parameters:
K - Type of the Key of the map.
V - Type of the value of the map.
public sealed class TimedCache<K,V> extends Object
Represents a timed cached map backed by a ConcurrentHashMap. Entries will expire after a configurable amount of time.

Expired entries cannot be retrieved or used in any way, but they will still show up in the size arguments. If configured, a separate thread may perform regular cleanup.

  • Constructor Details

    • TimedCache

      protected TimedCache(@Nullable Duration timeOut, @Nullable Duration cleanup, boolean softReference, boolean refresh, boolean keepAfterTimeOut)
      Constructor of TimedCache
      Parameters:
      timeOut - The amount of time a cached entry remains valid.

      Note that this value is used for millisecond precision. Anything smaller than that will be ignored.

      Setting this value to 0 means that values will never be evicted from the cache based on their age. This is a valid configuration in combination with the softReference option and a non-zero cleanup timeOut. This will cause all entries to exist in the cache until they are no longer referenced.

      When null, this value defaults to Duration.ZERO.

      cleanup - The timeOut between each cleanup cycle. During cleanup, all expired entries will be removed from the cache. When null (default) or 0, entries are evicted from the cache whenever they are accessed after they have expired. This value also uses millisecond precision.
      softReference - Whether to wrap values in SoftReferences or not. This allows the garbage collector to clear up any values as it sees fit.
      refresh - Whether to refresh entries whenever they are accessed.

      When set to false, entries will expire after the configured amount of time after their insertion time.

      When set to true, entries will expire after the configured amount of time after they were last retrieved.

      keepAfterTimeOut - Whether to keep values after their timeOut value is exceeded.

      This is used when using either soft or weak references and results in values remaining in the cache until they are removed by the garbage collector.

      When this is true, values in the cache

  • Method Details

    • validateState

      protected void validateState()
      Ensures that this cache is still alive.
      Throws:
      IllegalStateException - When this cache is not alive.

    • emptyCache

      public static <K,V> TimedCache<K,V> emptyCache()
      Returns a new 'cache' that does not cache any values.

      Any calls to getter methods will return null or empty optionals and any put methods will not do anything.

      Type Parameters:
      K - The type of the keys of the values.
      V - The type of the values.
      Returns:
      The new not-cache.

    • put

      public V put(K key, V value)
      Puts a new key/value pair in the cache.
      Parameters:
      key - The key of the pair to add to the cache.
      value - The value of the pair to add to the cache.
      Returns:
      The value that was just added to the cache.

    • putIfPresent

      public Optional<V> putIfPresent(K key, V value)
      Updates a value if it currently exists in the cache.
      Parameters:
      key - The key with which the specified value is to be associated.
      value - The value to be associated with the specified key.
      Returns:
      The updated value. If no value was updated, an empty Optional.

    • putIfAbsent

      public Optional<V> putIfAbsent(K key, V value)
      See ConcurrentHashMap.putIfAbsent(Object, Object).
      Returns:
      An empty Optional if no mapping existed for the key. If a mapping did exist, the value that was associated with the key is returned instead.

    • computeIfAbsent

      public @Nullable V computeIfAbsent(K key, Function<K,V> mappingFunction)
      See ConcurrentHashMap.computeIfAbsent(Object, Function).

    • computeIfPresent

      public Optional<V> computeIfPresent(K key, BiFunction<K, @Nullable V, V> remappingFunction)
      See ConcurrentHashMap.computeIfPresent(Object, BiFunction).

    • compute

      public V compute(K key, BiFunction<K, @Nullable V, V> mappingFunction)
      See ConcurrentHashMap.compute(Object, BiFunction).

    • remove

      public Optional<V> remove(K key)
      See ConcurrentHashMap.remove(Object).

    • get

      public Optional<V> get(K key)
      Gets the value associated with the provided key.

      If the value has expired but still exists in the map, it will be evicted and treated as if it did not exist at all.

      Parameters:
      key - The key of the value to look up.
      Returns:
      The value associated with the provided key if it is available.

    • containsKey

      public boolean containsKey(K key)
      Checks if a provided key both exists in the map and is not expired.

      If refresh is enabled, the key will be refreshed.

      Parameters:
      key - The key to check.
      Returns:
      True if the key exists and has not timed out.

    • getSize

      public int getSize()
      Gets the total number cached entries.

      Note that this also includes expired entries.

      Returns:
      The total number of cached entries.

    • clear

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

    • cleanupCache

      protected void cleanupCache()
      Removes any entries that have expired from the map.

      An entry counts as expired if AbstractTimedValue.getValue(boolean) returns null.

    • shutDown

      public void shutDown()
      Shuts this cache down.

      The cache will be cleared and any running processes will be stopped.

      After shutting the cache down, it is not possible to interact with it anymore. Trying to do so will result in exceptions.

    • builder

      public static <K,V> @NonNull TimedCache.TimedCacheBuilder<K,V> builder()