Cache (Atlassian Cache - API 6.0.2 API)

Type Parameters:

K - the key type

V - the value type
```
@PublicApi
public interface Cache<K,V>
```
Interface that defines the common 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.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addListener(CacheEntryListener<K,V> listener, boolean includeValues)` Deprecated. since 2.9 may not be supported in all implementations and will be removed after June 2016
`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`	`put(K key, V value)` Put an object into the cache.
`V`	`putIfAbsent(K key, V value)` Atomically associates the specified key with the given value if it is not already associated with a value.
`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.
`void`	`removeListener(CacheEntryListener<K,V> listener)` Deprecated. since 2.9 may not be supported in all implementations and will be removed after June 2016
`boolean`	`replace(K key, V oldValue, V newValue)` Atomically replaces the entry for a key only if currently mapped to a given value.

- Method Detail
  - 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:
    - If the cache was created with a CacheLoader, it will not be called. Obviously, any call to get(Object) will call the corresponding CacheLoader (if required).
    - If the cache was created with CacheSettings.getReplicateViaCopy() set to false and CacheSettings.getLocal() set to false, then only the local copy of the cache is checked. A local cache on another node may contain an entry under the specified key.
    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 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
  - put
```
void put(@Nonnull
         K key,
         @Nonnull
         V value)
```
    Put an object into the cache. If the specified key already exists within the cache, it will be replaced by the new object.
    NOTE: This method should not be used on hybrid caches that maintain consistency only by invalidating the key on other cluster nodes. Instead, such hybrid caches should use CacheLoader semantics and supply a CacheLoader when getting the Cache.
    
    Parameters:
    
    key - the key uniquely identifying the object to be added into the cache
    
    value - the non-null value to be cached
  - putIfAbsent
```
@Nullable
V putIfAbsent(@Nonnull
                        K key,
                        @Nonnull
                        V value)
```
    Atomically associates the specified key with the given value if it is not already associated with a value.
    NOTE: This method should not be used on hybrid caches that maintain consistency only by invalidating the key on other cluster nodes. Instead, such hybrid caches should use CacheLoader semantics and supply a CacheLoader when getting the Cache.
    
    Parameters:
    
    key - the key with which the specified value is associated
    
    value - the non-null value to be cached
    
    Returns:
    
    the previous value associated with the specified key, or null if there was no mapping for the key
  - 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.
  - replace
```
boolean replace(@Nonnull
                K key,
                @Nonnull
                V oldValue,
                @Nonnull
                V newValue)
```
    Atomically replaces 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
    
    oldValue - the value expected to be associated with the specified key
    
    newValue - the value to be associated with the specified key
    
    Returns:
    
    true if the value was replaced, false otherwise
  - addListener
```
@Deprecated
void addListener(@Nonnull
                             CacheEntryListener<K,V> listener,
                             boolean includeValues)
```
    Deprecated. since 2.9 may not be supported in all implementations and will be removed after June 2016
    
    Adds a CacheEntryListener
    
    Parameters:
    
    listener - the listener
    
    includeValues - if the events sent to this listener will include old/new value. This is can be used in cases when the cost of finding these values is big (network sync) but the listener is not interested in the concrete values for events its getting. The support for this parameter is optional and implementation dependant
    
    Throws:
    
    UnsupportedOperationException - if not supported
    
    Since:
    
    2.4
  - removeListener
```
@Deprecated
void removeListener(@Nonnull
                                CacheEntryListener<K,V> listener)
```
    Deprecated. since 2.9 may not be supported in all implementations and will be removed after June 2016
    
    Removes a CacheEntryListener
    
    Parameters:
    
    listener - the listener
    
    Throws:
    
    UnsupportedOperationException - if not supported
    
    Since:
    
    2.4

Interface Cache<K,V>

Method Summary

Method Detail

getName

containsKey

getKeys

get

get

getBulk

put

putIfAbsent

remove

remove

removeAll

replace

addListener

removeListener