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>

@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<Collection<K>,Map<K,V>> factory, Iterable<K> keys) Returns the values that are associated with the specified keys.
default Map<K,V>	getBulk(Function<Collection<K>,Map<K,V>> factory, K... keys) Returns the values that are associated with the specified keys.
Map<K,Optional<V>>	getBulk(Iterable<K> keys) Returns the values that are associated with the specified keys.
default Map<K,Optional<V>>	getBulk(K... keys) Returns the values that are associated with the specified keys.
Optional<V>	put(K key, V value) Unconditionally puts the value under the specified key, and returns the previous value associated with the key (if one existed).
Optional<V>	putIfAbsent(K key, V value) Conditionally puts the value under the specified key, if no entry currently exists.
void	remove(Iterable<K> keys) Removes all the entries for the supplied keys.
default void	remove(K... keys) Removes all the entries for the supplied keys.
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

@Nonnull
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

@Nonnull
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.

put

@Nonnull
Optional<V> put(K key,
                         V value)

Unconditionally puts the value under the specified key, and returns the previous value associated with the key (if one existed).

Parameters:

key - the key to put the data under

value - the value to associate with the key.

Returns:

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

putIfAbsent

@Nonnull
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

default void remove(K... keys)

Removes all the entries for the supplied keys. The same as calling remove(Iterable) passing Arrays.asList(keys) as the argument.

Parameters:

keys - specifies the entries to be removed.

remove

void remove(Iterable<K> keys)

Removes all the entries for the supplied keys.

Parameters:

keys - specifies the entries to be removed.

removeAll

void removeAll()

Removes all the entries in the cache.

getBulk

@Nonnull
default Map<K,Optional<V>> getBulk(K... keys)

Returns the values that are associated with the specified keys. It is equivalent to calling getBulk(Iterable) passing Arrays.asList(keys) as the parameter.

Parameters:

keys - the keys to check.

Returns:

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

getBulk

@Nonnull
Map<K,Optional<V>> getBulk(Iterable<K> keys)

Returns the values that are associated with the specified keys.

Parameters:

keys - the keys to check.

Returns:

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

getBulk

@Nonnull
default Map<K,V> getBulk(Function<Collection<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.

Notes:

• If no entry for the specified key exists, then the specified factory is called, sequentially using the current thread, to create an entry in the cache, before it is returned.

Parameters:

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

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.

getBulk

@Nonnull
Map<K,V> getBulk(Function<Collection<K>,Map<K,V>> factory,
                          Iterable<K> keys)

Returns the values that are associated with the specified keys.

Notes:

• If no entry for the specified key exists, then the specified factory is called, sequentially using the current thread, to create an entry in the cache, before it is returned.

Parameters:

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

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.