Package com.sodius.oslc.core.cache

Interface Cache<K,V>

Type Parameters:
K - the type of keys maintained by this cache
V - the type of mapped values
All Known Implementing Classes:
AbstractCache
public interface Cache<K,V>
A semi-persistent mapping from keys to values. Cache entries are manually added using get(Object, Function) or put(Object, Object), and are stored in the cache until either evicted or manually invalidated.

Implementations of this interface are thread-safe and can be safely accessed by multiple concurrent threads.

Since:
3.7.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Map<K,V>
    asMap()
    Returns a view of the entries stored in this cache as an unmodifiable map.
    void
    cleanUp()
    Performs any pending maintenance operations needed by the cache.
    V
    compute(K key, BiFunction<K,V,V> remappingFunction)
    Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).
    V
    get(K key, Function<? super K,? extends V> loader)
    Returns the value associated with the key in this cache, obtaining that value from the loader if necessary.
    V
    getIfPresent(K key)
    Returns the value associated with the key in this cache, or null if there is no cached value for the key.
    void
    invalidate(K key)
    Discards any cached value for the key.
    void
    invalidateAll()
    Discards all entries in the cache.
    void
    put(K key, V value)
    Associates the value with the key in this cache.

  • Method Details

    • getIfPresent

      V getIfPresent(K key)
      Returns the value associated with the key in this cache, or null if there is no cached value for the key.
      Parameters:
      key - the key whose associated value is to be returned
      Returns:
      the value to which the specified key is mapped, or null if this cache does not contain a mapping for the key
      Throws:
      NullPointerException - if the specified key is null

    • get

      V get(K key, Function<? super K,? extends V> loader)
      Returns the value associated with the key in this cache, obtaining that value from the loader if necessary. This method provides a simple substitute for the conventional "if cached, return; otherwise create, cache and return" pattern.

      If the specified key is not already associated with a value, attempts to compute its value using the given mapping function and enters it into this cache. The entire method invocation is performed atomically, so the function is applied at most once per key. Some attempted update operations on this cache by other threads may be blocked while the computation is in progress, so the computation should be short and simple, and must not attempt to update any other mappings of this cache.

      Warning: loader must not attempt to update any other mappings of this cache.

      Warning: loader must not return null; it may either return a non-null value or throw an exception.

      Parameters:
      key - the key whose associated value is to be returned
      loader - the function to compute a value
      Returns:
      the current (existing or computed) value associated with the specified key
      Throws:
      NullPointerException - if the specified key or loader is null
      IllegalStateException - if the computation detectably attempts a recursive update to this cache that would otherwise never complete
      RuntimeException - or Error if the loader does so, in which case the mapping is left unestablished

    • put

      void put(K key, V value)
      Associates the value with the key in this cache. If the cache previously contained a value associated with the key, the old value is replaced by the new value.

      Prefer get(Object, Function) when using the conventional "if cached, return; otherwise create, cache and return" pattern.

      Parameters:
      key - the key with which the specified value is to be associated
      value - value to be associated with the specified key
      Throws:
      NullPointerException - if the specified key or value is null

    • invalidate

      void invalidate(K key)
      Discards any cached value for the key. The behavior of this operation is undefined for an entry that is being loaded (or reloaded) and is otherwise not present.
      Parameters:
      key - the key whose mapping is to be removed from the cache
      Throws:
      NullPointerException - if the specified key is null

    • invalidateAll

      void invalidateAll()
      Discards all entries in the cache. The behavior of this operation is undefined for an entry that is being loaded (or reloaded) and is otherwise not present.

    • asMap

      Map<K,V> asMap()
      Returns a view of the entries stored in this cache as an unmodifiable map.
      Returns:
      an unmodifiable view of this cache

    • compute

      V compute(K key, BiFunction<K,V,V> remappingFunction)
      Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).

      If the remapping function returns null, the mapping is removed (or remains absent if initially absent). If the remapping function returns a non-null value, it is stored in the cache.

      The entire operation is performed atomically with respect to other cache operations on the same key, making it safe for concurrent use and cluster environments.

      This method is aligned with Map.compute(Object, BiFunction).

      Warning: remappingFunction must not attempt to update any other mappings of this cache.

      Parameters:
      key - the key whose associated value is to be computed
      remappingFunction - the function to compute a value. The first argument is the key, the second argument is the current value or null if absent. The result is the new value, or null to remove the mapping.
      Returns:
      the new value associated with the specified key, or null if none
      Throws:
      NullPointerException - if the specified key or remappingFunction is null
      Since:
      3.16.0

    • cleanUp

      void cleanUp()
      Performs any pending maintenance operations needed by the cache. Exactly which activities are performed, if any, is implementation-dependent.