Package io.pravega.common.util

Class SimpleCache<KeyT,​ValueT>

  • Type Parameters:
    KeyT - Key Type.
    ValueT - Value Type.
    @ThreadSafe
public class SimpleCache<KeyT,​ValueT>
extends java.lang.Object
    Lightweight, thread-safe, key-value pair cache built on top of Java HashMap that supports eviction based on a maximum size or last-access-time. Eviction of items is triggered by one of the following: - Invoking cleanUp(). - Invoking putIfAbsent(KeyT, ValueT), put(KeyT, ValueT) or get(KeyT) for a Key that has expired or if the size() of the cache has exceeded getMaxSize(). Every item access (upon insertion, updating or retrieval) will update the "last-access-time" of that item to the current time. Upon eviction, items will be evicted beginning with the least-accessed one (i.e, the ones that have not been used recently), in order of access time (oldest items first). Every eviction event will remove all expired items and any unexpired items as needed if size() exceeds getMaxSize().

    • Constructor Summary

      Constructors 
      Constructor Description
      SimpleCache​(int maxSize, @NonNull java.time.Duration expirationTime, java.util.function.BiConsumer<KeyT,​ValueT> onExpiration)
      Creates a new instance of the SimpleCache class.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void cleanUp()
      Performs a cleanup of this class.
      ValueT get​(KeyT key)
      Gets a value associated with the given key.
      int getMaxSize()  
      ValueT put​(KeyT key, ValueT value)
      Inserts a new Key-Value pair into the cache.
      ValueT putIfAbsent​(KeyT key, ValueT value)
      Inserts a Key-Value pair into the cache, but only if the Key is not already present.
      ValueT remove​(KeyT key)
      Removes any value that is associated with the given key.
      int size()
      Gets a value representing the number of entries in the cache.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • SimpleCache

        public SimpleCache​(int maxSize,
                   @NonNull
                   @NonNull java.time.Duration expirationTime,
                   @Nullable
                   java.util.function.BiConsumer<KeyT,​ValueT> onExpiration)
        Creates a new instance of the SimpleCache class.
        Parameters:
        maxSize - Maximum number of elements in the cache. If size() exceeds this value as a result of an insertion, the oldest entries will be evicted, in order, until size() falls below this value.
        expirationTime - Maximum amount of time, since the last access of an entry, until such an entry is "expired" and will be evicted. Entries will not be evicted exactly when they expire, rather upon calls to cleanUp() or any other accessor or mutator invocations.
        onExpiration - (Optional) A Consumer that will be invoked when an Entry is evicted. This will not be invoked when the entry is replaced (i.e., via put(KeyT, ValueT) or removed (via remove(KeyT).

    • Method Detail

      • size

        public int size()
        Gets a value representing the number of entries in the cache. This may include expired entries as well (expired entries will be removed upon invoking cleanUp(), which will also update this value).
        Returns:
        The number of entries in the cache.

      • put

        public ValueT put​(KeyT key,
                  ValueT value)
        Inserts a new Key-Value pair into the cache.
        Parameters:
        key - The key to insert.
        value - The value to insert.
        Returns:
        The previous value associated with this key, or null if no such value exists or if it is expired.

      • putIfAbsent

        public ValueT putIfAbsent​(KeyT key,
                          ValueT value)
        Inserts a Key-Value pair into the cache, but only if the Key is not already present.
        Parameters:
        key - The key to insert.
        value - The value to insert.
        Returns:
        The value that was already associated with this key. If no such value, or if the value is expired, then null will be returned. If null is returned, then the insertion can be considered successful.

      • remove

        public ValueT remove​(KeyT key)
        Removes any value that is associated with the given key.
        Parameters:
        key - The key to remove.
        Returns:
        The value associated with the given key, or null if no such value exists or if the value is expired.

      • get

        public ValueT get​(KeyT key)
        Gets a value associated with the given key.
        Parameters:
        key - The key to lookup.
        Returns:
        The value associated with the given key, or null if no such value exists or if the value is expired. If the value is expired, it will be automatically removed from the cache.

      • cleanUp

        public void cleanUp()
        Performs a cleanup of this class. After this method completes, the following will be true: - size() will be less than or equal to getMaxSize(). - All expired entries will be removed.

      • getMaxSize

        public int getMaxSize()