Package com.atlassian.cache

Interface ReadThroughCache<K,V>

Type Parameters:
K - the key type
V - the value type
All Known Subinterfaces:
Cache<K,V>
@PublicApi public interface ReadThroughCache<K,V>
Interface that defines the common read-through cache operations.

Note: null keys and values are NOT supported. Although using null values may work for some implementations, it won't work for all implementations and the behaviour may change over time.

Since:
6.1

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    containsKey(K key)
    Returns whether an entry exists in the cache under the specified key.
    V
    get(K key)
    Retrieve an object from this cache.
    V
    get(K key, Supplier<? extends V> valueSupplier)
    Retrieve an object from this cache.
    default Map<K,V>
    getBulk(Set<K> keys, Function<Set<K>,Map<K,V>> valuesSupplier)
    Retrieve multiple entries from the cache.
    Collection<K>
    getKeys()
    Gets the keys of all objects currently stored in the cache.
    String
    getName()
    The name of the cache, uniquely identifies this cache.
    void
    remove(K key)
    Remove the object identified by the key from the cache.
    boolean
    remove(K key, V value)
    Atomically removes the entry for a key only if currently mapped to a given value.
    void
    removeAll()
    Remove all of the objects from this cache.

  • Method Details

    • getName

      @Nonnull String getName()
      The name of the cache, uniquely identifies this cache.
      Returns:
      the name of the cache

    • containsKey

      boolean containsKey(@Nonnull K key)
      Returns whether an entry exists in the cache under the specified key.

      Note that:

      Parameters:
      key - the key for the entry to check for containment
      Returns:
      true iff the cache already contains an entry under the specified key
      Since:
      2.2.0

    • getKeys

      @Nonnull Collection<K> getKeys()
      Gets the keys of all objects currently stored in the cache. This will return the keys in a new collection.
      Returns:
      a collection of Objects keys

    • get

      @Nullable V get(@Nonnull K key)
      Retrieve an object from this cache. Note that a copy of the cached object may be returned. Any changes that are made to the returned object may not be reflected in the cache. Cached values should be considered effectively immutable.
      Parameters:
      key - the key uniquely identifying the object to be retrieved
      Returns:
      the object from the cache, or null if the object is not found

    • get

      @Nonnull V get(@Nonnull K key, @Nonnull Supplier<? extends V> valueSupplier)
      Retrieve an object from this cache. Note that a copy of the cached object may be returned. Any changes that are made to the returned object may not be reflected in the cache. Cached values should be considered effectively immutable.

      If no value is present in the cache, the valueSupplier will be used to populate the entry and be counted as a cache miss.

      Parameters:
      key - the key uniquely identifying the object to be retrieved
      valueSupplier - the supplier to call if no value is stored in the cache. the value supplied by the supplier cannot be null
      Returns:
      the object from the cache, or the newly created value from the supplier
      Since:
      2.5

    • getBulk

      @Nonnull default Map<K,V> getBulk(@Nonnull Set<K> keys, @Nonnull Function<Set<K>,Map<K,V>> valuesSupplier)
      Retrieve multiple entries from the cache. Any entries not present in the cache will be loaded using the given bulk loader function. By default, this method is implemented rather naively based upon calls to get(Object) and Map.put(Object, Object). This should be fine for the majority of cache implementations, and will still benefit from the bulk value loader. Individual cache implementations, however, may wish to override this method and provide an optimised implementation.
      Parameters:
      keys - the set of keys for the entries to be fetched from the cache
      valuesSupplier - a function that takes the set of keys that were not present in the cache, and returns a map of keys to new values
      Returns:
      a map of keys to values, a combination of entries that were already cached, and entries that had to be loaded
      Since:
      5.3

    • remove

      void remove(@Nonnull K key)
      Remove the object identified by the key from the cache. If no object can be found associated with this key then no action is taken.
      Parameters:
      key - the key that uniquely identifies the object to be removed

    • remove

      boolean remove(@Nonnull K key, @Nonnull V value)
      Atomically removes the entry for a key only if currently mapped to a given value.

      NOTE: Some cache backends (e.g. Ehcache) require this operation to be performed by CAS and will throw an exception when the cache is replicated

      Parameters:
      key - the key with which the specified value is associated
      value - the value expected to be associated with the specified key
      Returns:
      true if the value was removed, false otherwise

    • removeAll

      void removeAll()
      Remove all of the objects from this cache.