Package com.atlassian.cache

Interface Cache<K,V>

Type Parameters:

K - the key type

V - the value type

All Superinterfaces:

ReadThroughCache<K,V>

@PublicApi
public interface Cache<K,V>
extends ReadThroughCache<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

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

Methods inherited from interface com.atlassian.cache.ReadThroughCache

containsKey, get, get, getBulk, getKeys, getName, remove, remove, removeAll

Method Details

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

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

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

Throws:

UnsupportedOperationException - if not supported

Since:

2.4

removeListener

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

Removes a CacheEntryListener

Parameters:

listener - the listener

Throws:

UnsupportedOperationException - if not supported

Since:

2.4