Package com.sap.cloud.mobile.foundation.cache

Interface Cache

  • All Implemented Interfaces:
    
public interface Cache<K, V>

    In general, a cache is a key/value store that has a maximum storage capacity and exposes methods to support CRUD operations to provide temporary storage which maintains a single copy of items that are expensive to create or load, for example via remote network calls.

    Because the cache has limited storage capacity, any new item added to a full cache requires an item be removed first. The Cache Replacement Policy of the cache implementation specifies which item to remove.

    Each entry in the cache contains a key and its associated value using generics. In addition, a cost value may be specified. Cost is an arbitrary value (can be the size factor of the value, for example). How the cost is handled is implementation dependent.

    The Cache interface declares the basic CRUD operations an implementation must support. A typical Cache implementation usually follows similar usage patterns/stages:

    • Creation-- provides constructor(s) to create an instance of the cache.
    • Configuration-- configures features/options and enables the CRUD operations.
    • CRUD operations:

    The Creation and Configuration methods are implementation dependent, the CRUD operations are common but may have additional implementation specific semantics.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Field Summary

      Fields 
      Modifier and Type Field Description

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Method Summary

      Modifier and Type Method Description
      abstract V put(@NonNull() K key, @NonNull() V value, double cost) Adds the value and the associated cost to the cache for the key.
      abstract V put(@NonNull() K key, @NonNull() V value) Adds or updates a value associated with a key.
      abstract V get(@NonNull() K key) Returns the value associated with a key.
      abstract CacheEntry getEntry(@NonNull() K key) Retrieves the value associated with a key, then returns a CacheEntry object that embeds the key and value.
      abstract double getCostOfEntries() Returns the aggregated value of the cost of the entries in the cache.
      abstract int getEntryCount() Returns the number of entries (key-value pairs) in the cache.
      abstract List<K> keys() Returns a list of keys of all entries in the cache or a non-null empty list.
      abstract void remove(@NonNull() K key) Removes a cache entry.
      abstract void removeAll() Removes all entries from the cache.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

    • Method Detail

      • put

        @Nullable() abstract V put(@NonNull() K key, @NonNull() V value, double cost)

        Adds the value and the associated cost to the cache for the key. The behavior when the aggregate of costs exceeds the maximum cost during the execution of this method is implementation dependent.

        Parameters:
        key - a non-null key of a cache entry
        value - a non-null value to add
        cost - the cost associated with this entry.
        Returns:

        The previous value associated with the existed key, nullif the entry did exist.

      • put

        @Nullable() abstract V put(@NonNull() K key, @NonNull() V value)

        Adds or updates a value associated with a key.

        Parameters:
        key - a non-null key of a cache entry
        value - a non-null value to add
        Returns:

        The original value of an existing cache entry, or null if this is a new entry.

      • get

        @Nullable() abstract V get(@NonNull() K key)

        Returns the value associated with a key.

        Parameters:
        key - a non-null key of a cache entry
        Returns:

        The value associated with a key or null if the key is not found.

      • getEntry

        @Nullable() abstract CacheEntry getEntry(@NonNull() K key)

        Retrieves the value associated with a key, then returns a CacheEntry object that embeds the key and value.

        Parameters:
        key - a non-null key of a cache entry
        Returns:

        A CacheEntry or null if the key is not found.

      • getCostOfEntries

         abstract double getCostOfEntries()

        Returns the aggregated value of the cost of the entries in the cache. The concrete behavior is implementation dependent.

        Returns:

        The aggregated value of the cost of the entries in the cache.

      • getEntryCount

         abstract int getEntryCount()

        Returns the number of entries (key-value pairs) in the cache.

        Returns:

        The number of entries.

      • keys

        @NonNull() abstract List<K> keys()

        Returns a list of keys of all entries in the cache or a non-null empty list. The order of the entries in the list is implementation dependent.

        Returns:

        A list of keys of all entries in the cache or a non-null empty list (use isEmpty to check).

      • remove

         abstract void remove(@NonNull() K key)

        Removes a cache entry.

        Parameters:
        key - a non-null key of the entry to remove

      • removeAll

         abstract void removeAll()

        Removes all entries from the cache.