com.atlassian.vcache

Interface ExternalCache<V>

Type Parameters:

V - the value type

All Superinterfaces:

VCache

All Known Subinterfaces:

DirectExternalCache<V>, StableReadExternalCache<V>, TransactionalExternalCache<V>

All Known Implementing Classes:

AbstractExternalCache, AbstractStableReadExternalCache, AbstractTransactionalExternalCache, GuavaDirectExternalCache, GuavaStableReadExternalCache, GuavaTransactionalExternalCache

@PublicApi
public interface ExternalCache<V>
extends VCache

Represents an external cache, where the data is ultimately stored in external cache systems like Memcached or Redis. The values are stored by value and are converted using a MarshallingPair.

The settings provided when creating a ExternalCache are only used within the JVM and are not centrally stored across JVMs.

Failures

Failures are expected to happen when communicating with the external system, and the caller is expected to deal with them. As such, all operations that involve communicating with the external system will return an CompletionStage, which encapsulates that failure may have occurred.

WorkContext Lifecycle

Any returned CompletionStage is guaranteed to complete by the end of the Atlassian WorkContext it was created within. There is no need to explicitly "join" on a CompletionStage, using VCacheUtils.fold(CompletionStage, Function, Function) or similar. This means that any "connected" CompletionStage, via CompletionStage.thenCombine(CompletionStage, BiFunction) etc, will be performed.

Buffering

Buffering of communications to the external cache system may be applied to both read and write operations. The following three specialisations of the ExternalCache are provided to represent the possible buffering modes:

• DirectExternalCache - buffering is not applied for either read or write operations.
• TransactionalExternalCache - buffering is applied for both read and write operations.
• StableReadExternalCache - buffering is applied for only read operations

Buffering of read operations means that the result of every read operation is stored in a private RequestCache. All read operations will first query the private RequestCache to determine whether the operation has been performed before, and if it has, return the buffered result.

Buffering of write operations means that all write operations are stored in a private RequestCache, and at the end of the transaction they are applied to the external cache system.

When buffering is used for write operations, the issue arises as to how to handle when there are conflicts when replaying the buffered operations. The guiding principles are:

• The implementation shall endeavour to detect when the external system state has changed since it was read and deal with it appropriately.
• If the implementation cannot determine a reliable and consistent way to deal with a conflict, it shall invalidate the entries affected, or the entire cache.
• Rather than attempt to return errors (the implementation should log them) to the application code at the end of a request, invalidation is used to recover.

All read operations, even if buffered, may involve failures. As such, all read operations are encapsulated in this interface. However, buffered write operations will not expose failures as they are replayed later. Hence, the write operations are provided through the following two interfaces which are used by the four specialisations of this interface:

• ExternalWriteOperationsBuffered - encapsulates the buffered versions of the write operations.
• ExternalWriteOperationsUnbuffered - encapsulates the unbuffered versions of the write operations.

Supplier/Factory Generation

The operations that may create values using a supplied Supplier or Function make no guarantees about their atomicity. There is a possible race condition between detecting that a value is missing in the external cache system, and the generated value being stored in the external cache system. The implementations are free to override any (new) value that may have been stored in the external cache system. If this behaviour is unacceptable, then the caller is responsible for using a strategy to deal with this (such as global locking).

Time-to-live

• A cache has an associated time-to-live (ttl), which is expressed as Duration. The implementations may round-up the supplied ttl to the nearest second. E.g. 500 milliseconds may be converted to 1 second.
• Implementations should implement ttl based on the time the entry was added or updated. However, do not assume that the associated ttl defines exactly when entries are evicted. The implementations are free to choose how the ttl is interpreted. It may expire entries in a timely manner, or it may be delayed until next interaction with the cache.

Data Considerations

As the data is stored externally to the JVM, the following needs to be considered:

• The data in the external system will persist longer than the JVM. Hence newer versions of the application will need to handle data that could have been written by an earlier version of the application. If the data format used is not compatible between the different versions of the application, problems will arise. It is required that the application deal with potential versioning issues. One approach would be to to use Versioning of Serializable Objects.
• Data is stored in the external system as byte arrays. The cache must be associated with a MarshallingPair instance for marshalling values. By extension, this means that an ExternalCache can only be used for data that can be marshalled to/from byte arrays.

Hints

Each cache is configured with the following hints to allow the implementation the opportunity to optimise performance.

• ExternalCacheSettings.getDataChangeRateHint() - this is a hint on the expected rate of change to the data held in the cache, including updating existing entries. A cache that holds values that are never updated after being populated should use ChangeRate.NONE. A cache that holds data that changed infrequently, like a cache of project details, should use ChangeRate.LOW_CHANGE.
• ExternalCacheSettings.getEntryGrowthRateHint() - this is a hint on the expected rate of change in the number of entries held in the cache. A cache that holds a fixed number of entries should use ChangeRate.NONE.
• ExternalCacheSettings.getEntryCountHint() - this is a hint on the desired number of entries in the cache. The implementation is free to use this as it sees fit.

Since:

1.0

Method Summary

Modifier and Type	Method and Description
CompletionStage<Optional<V>>	get(String key) Returns a value that is associated with a specified key.
CompletionStage<V>	get(String key, Supplier<V> supplier) Returns a value that may be associated with a specified key.
CompletionStage<Map<String,V>>	getBulk(Function<Set<String>,Map<String,V>> factory, Iterable<String> keys) Returns the values that are associated with the specified keys.
default CompletionStage<Map<String,V>>	getBulk(Function<Set<String>,Map<String,V>> factory, String... keys) Returns the values that are associated with the specified keys.
CompletionStage<Map<String,Optional<V>>>	getBulk(Iterable<String> keys) Returns the values that are associated with the specified keys.
default CompletionStage<Map<String,Optional<V>>>	getBulk(String... keys) Returns the values that are associated with the specified keys.

Methods inherited from interface com.atlassian.vcache.VCache

getName

Method Detail

get

CompletionStage<Optional<V>> get(String 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

CompletionStage<V> get(String key,
                       Supplier<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. The value may be used to create an entry in the cache. However, the value returned may be that of the supplier to a concurrent call to this method, or that of the factory in a concurrent call to getBulk(java.lang.String...). When the supplier is called, callers may not assume that the value returned from the supplier is returned by this method.
• 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 CompletionStage<Map<String,Optional<V>>> getBulk(String... 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

CompletionStage<Map<String,Optional<V>>> getBulk(Iterable<String> 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

default CompletionStage<Map<String,V>> getBulk(Function<Set<String>,Map<String,V>> factory,
                                               String... 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 a specified key (or keys) exists, then the specified factory is called. The values may be used to create entries in the cache. However, the values returned may be that of the factory to a concurrent call to this method, or that of the supplier in a concurrent call to get(String, Supplier). When the factory is called, callers may not assume that the values returned from the factory is returned by this method.

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

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

Returns the values that are associated with the specified keys.

Notes:

• If no entry for a specified key (or keys) exists, then the specified factory is called. The values may be used to create entries in the cache. However, the values returned may be that of the factory to a concurrent call to this method, or that of the supplier in a concurrent call to get(String, Supplier). When the factory is called, callers may not assume that the values returned from the factory is returned by this method.

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.