com.atlassian.cache

Interface Cache<K,V>

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

Methods

Modifier and Type	Method and Description
void	addListener(CacheEntryListener<K,V> listener, boolean includeValues) Adds a CacheEntryListener
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.
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) Removes a CacheEntryListener
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

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: Users of caches that wish to be well behaved in a clustered environment should use the 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.

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.

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.

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

void addListener(@Nonnull
               CacheEntryListener<K,V> listener,
               boolean includeValues)

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

Since:

2.4

removeListener

void removeListener(@Nonnull
                  CacheEntryListener<K,V> listener)

Removes a CacheEntryListener

Parameters:

listener - the listener

Since:

2.4