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:
    CacheBuilder.build(String)

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      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 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 Detail

      • 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

      • cleanUp

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