com.atlassian.vcache

Interface LocalCacheOperations<K,V>

Type Parameters:

K - the key type

V - the value type

All Known Subinterfaces:

JvmCache<K,V>, RequestCache<K,V>

All Known Implementing Classes:

GuavaJvmCache

@PublicApi
public interface LocalCacheOperations<K,V>

Represents the common operations that can be performed on a JVM local cache.

Since:

1.0

Method Summary

Modifier and Type	Method and Description
Optional<V>	get(K key) Returns a value that is associated with a specified key.
V	get(K key, Supplier<? extends V> supplier) Returns a value that may be associated with a specified key.
Map<K,V>	getBulk(Function<Set<K>,Map<K,V>> factory, Iterable<K> keys) Returns the values that are associated with the specified keys.
default Map<K,V>	getBulk(Function<Set<K>,Map<K,V>> factory, K... keys) Returns the values that are associated with the specified keys.
void	put(K key, V value) Unconditionally puts the value under the specified key.
Optional<V>	putIfAbsent(K key, V value) Conditionally puts the value under the specified key, if no entry currently exists.
void	remove(K key) Removes the entries for the supplied key.
void	removeAll() Removes all the entries in the cache.
boolean	removeIf(K key, V value) Conditionally removed an entry for a specified key, iff: An entry already exists for the key The current value matches the supplied value using Object.equals(Object)
boolean	replaceIf(K key, V currentValue, V newValue) Conditionally replaces the value associated with a key, iff: An entry already exists for the key The current value matches the supplied currentValue using Object.equals(Object)

Method Detail

get

Optional<V> get(K key)

Returns a value that is associated with a specified key.

Parameters:

key - the key to check.

Returns:

an Optional which may contain the value associated with the key.

get

V get(K key,
      Supplier<? extends V> supplier)

Returns a value that may be associated with a specified key.

Notes:

• If no entry for the specified key exists, then the specified supplier is called to create an entry in the cache, before it is returned.
• The supplier implementation needs to be multi-thread safe as it may be called concurrently if multiple threads call this method.

Parameters:

key - the key uniquely identifying the value to be retrieved

supplier - used to generate the value, if one does not exist already for the key. The supplier may not return null.

Returns:

the value associated with the key.

getBulk

default Map<K,V> getBulk(Function<Set<K>,Map<K,V>> factory,
                         K... keys)

Returns the values that are associated with the specified keys. It is equivalent to calling getBulk(Function, Iterable) passing factory and Arrays.asList(keys) as the parameters.

Parameters:

factory - used to generate the values for the keys that do not have entries. The factory must return a map containing only a non-null value for each supplied key. Extra keys are not allowed.

keys - the keys to retrieve

Returns:

A Map that is keyed on the keys specified. Each entry in the Map will have the value associated with the key.

See Also:

getBulk(Function, Iterable)

getBulk

Map<K,V> getBulk(Function<Set<K>,Map<K,V>> factory,
                 Iterable<K> keys)

Returns the values that are associated with the specified keys.

Notes:

• WARNING: this method is not multi-thread safe in conjunction with any methods that make single key mutations, such as remove(Object) or removeIf(Object, Object). Caller beware.
• If there are any keys for which no entry exists, then the given factory is called exactly once with the argument being a Set containing exactly the keys for which no entry existed. The return value of the factory is used to populate the missing entries in the cache, and then the map of all requested keys to values is returned.
• The call to the factory is made on the thread which calls getBulk.
• Despite the fact that the keys are an Iterable, no guarantees are made about the order in which the cache is populated, nor the order in which the Set passed to the factory is iterated, nor in which the returned Map is iterated.

Parameters:

factory - used to generate the values for the keys that do not have entries. The factory must return a map containing only a non-null value for each supplied key. Extra keys are not allowed.

keys - the keys to retrieve

Returns:

A Map that is keyed on the keys specified. Each entry in the Map will have the value associated with the key.

put

void put(K key,
         V value)

Unconditionally puts the value under the specified key.

Parameters:

key - the key to put the data under

value - the value to associate with the key.

putIfAbsent

Optional<V> putIfAbsent(K key,
                        V value)

Conditionally puts the value under the specified key, if no entry currently exists. Returns the current value associated with the key, if one currently exists.

Parameters:

key - the key to put the data under

value - the value to associate with the key.

Returns:

Optional.EMPTY is no entry previously existed, otherwise the Optional contains the current value.

replaceIf

boolean replaceIf(K key,
                  V currentValue,
                  V newValue)

Conditionally replaces the value associated with a key, iff:

• An entry already exists for the key
• The current value matches the supplied currentValue using Object.equals(Object)

Parameters:

key - the key to replace data under

currentValue - the current value to match

newValue - the replacement value

Returns:

whether the current value are replaced with the supplied newValue

removeIf

boolean removeIf(K key,
                 V value)

Conditionally removed an entry for a specified key, iff:

• An entry already exists for the key
• The current value matches the supplied value using Object.equals(Object)

Parameters:

key - the key of the entry to remove conditionally

value - the current value to match

Returns:

whether an entry was removed

remove

void remove(K key)

Removes the entries for the supplied key.

Parameters:

key - the key of the entry to remove

removeAll

void removeAll()

Removes all the entries in the cache.