com.atlassian.vcache.internal.core.service

Class AbstractStableReadExternalCache<V>

java.lang.Object

com.atlassian.vcache.internal.core.service.AbstractExternalCache<V>

com.atlassian.vcache.internal.core.service.AbstractStableReadExternalCache<V>

Type Parameters:

V - the value type

All Implemented Interfaces:

ExternalCache<V>, ExternalWriteOperationsUnbuffered<V>, StableReadExternalCache<V>, VCache

Direct Known Subclasses:

GuavaStableReadExternalCache

public abstract class AbstractStableReadExternalCache<V>
extends AbstractExternalCache<V>
implements StableReadExternalCache<V>

Provides operations common to StableReadExternalCache instances.

Locking is provided to synchronise the local and remote caches. There are two locking strategies - a cache wide read-write lock and a per-key lock. The cache wide lock provides exclusion for multi-key operations such as removeAll and getBulk. The key lock provides locking for single key get and put whilst honouring the cache lock.

Since:

1.0.0

Field Summary

Fields

Modifier and Type	Field and Description
protected MetricsRecorder	metricsRecorder

Fields inherited from class com.atlassian.vcache.internal.core.service.AbstractExternalCache

lockTimeout, name

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractStableReadExternalCache(String name, MetricsRecorder metricsRecorder, Duration lockTimeout, ExternalCacheExceptionListener externalCacheExceptionListener)

Method Summary

Modifier and Type	Method and Description
protected abstract Optional<V>	directGet(String externalKey) Performs a direct get operation against the external cache using the supplied external key.
protected abstract Map<String,Optional<V>>	directGetBulk(Set<String> externalKeys) Performs a direct bulk get operation against the external cache using the supplied external keys.
CompletionStage<Optional<V>>	get(String internalKey) Returns a value that is associated with a specified key.
CompletionStage<V>	get(String internalKey, 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> internalKeys) Returns the values that are associated with the specified keys.
CompletionStage<Map<String,Optional<V>>>	getBulk(Iterable<String> internalKeys) Returns the values that are associated with the specified keys.
protected abstract V	handleCreation(String internalKey, V candidateValue) Handles the creation of an entry, if required.
protected abstract boolean	internalPut(String internalKey, V value, PutPolicy policy)
protected abstract void	internalRemove(Iterable<String> keys)
protected abstract void	internalRemoveAll()
CompletionStage<Boolean>	put(String internalKey, V value, PutPolicy policy) Puts the value under the specified key using the specified policy.
CompletionStage<Void>	remove(Iterable<String> keys) Remove the entries with the specified keys.
CompletionStage<Void>	removeAll() Remove all entries in the cache.

Methods inherited from class com.atlassian.vcache.internal.core.service.AbstractExternalCache

ensureCacheContext, getLogger, getName, mapException, perform, perform

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.atlassian.vcache.ExternalCache

getBulk, getBulk

Methods inherited from interface com.atlassian.vcache.VCache

getName

Methods inherited from interface com.atlassian.vcache.ExternalWriteOperationsUnbuffered

remove

Field Detail

metricsRecorder

protected final MetricsRecorder metricsRecorder

Constructor Detail

AbstractStableReadExternalCache

protected AbstractStableReadExternalCache(String name,
                                          MetricsRecorder metricsRecorder,
                                          Duration lockTimeout,
                                          ExternalCacheExceptionListener externalCacheExceptionListener)

Method Detail

internalPut

protected abstract boolean internalPut(String internalKey,
                                       V value,
                                       PutPolicy policy)

internalRemoveAll

protected abstract void internalRemoveAll()

internalRemove

protected abstract void internalRemove(Iterable<String> keys)

handleCreation

protected abstract V handleCreation(String internalKey,
                                    V candidateValue)
                             throws ExecutionException,
                                    InterruptedException

Handles the creation of an entry, if required.

Parameters:

internalKey - the internal key for the entry.

candidateValue - the candidate value to add, if required

Returns:

the value associated with the key.

Throws:

ExecutionException

InterruptedException

directGet

protected abstract Optional<V> directGet(String externalKey)

Performs a direct get operation against the external cache using the supplied external key.

directGetBulk

protected abstract Map<String,Optional<V>> directGetBulk(Set<String> externalKeys)

Performs a direct bulk get operation against the external cache using the supplied external keys.

get

public final CompletionStage<Optional<V>> get(String internalKey)

Description copied from interface: ExternalCache

Returns a value that is associated with a specified key.

Specified by:

get in interface ExternalCache<V>

Parameters:

internalKey - the key to check.

Returns:

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

get

public final CompletionStage<V> get(String internalKey,
                                    Supplier<V> supplier)

Description copied from interface: ExternalCache

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 ExternalCache.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.

Specified by:

get in interface ExternalCache<V>

Parameters:

internalKey - 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

public final CompletionStage<Map<String,Optional<V>>> getBulk(Iterable<String> internalKeys)

Description copied from interface: ExternalCache

Returns the values that are associated with the specified keys.

Specified by:

getBulk in interface ExternalCache<V>

Parameters:

internalKeys - 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

public final CompletionStage<Map<String,V>> getBulk(Function<Set<String>,Map<String,V>> factory,
                                                    Iterable<String> internalKeys)

Description copied from interface: ExternalCache

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 ExternalCache.get(String, Supplier). When the factory is called, callers may not assume that the values returned from the factory is returned by this method.

Specified by:

getBulk in interface ExternalCache<V>

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.

internalKeys - 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

public final CompletionStage<Boolean> put(String internalKey,
                                          V value,
                                          PutPolicy policy)

Description copied from interface: ExternalWriteOperationsUnbuffered

Puts the value under the specified key using the specified policy.

Specified by:

put in interface ExternalWriteOperationsUnbuffered<V>

Parameters:

internalKey - the key to put the data under

value - the value to associate with the key.

policy - the policy to apply

Returns:

whether the entry was put into the cache.

remove

public final CompletionStage<Void> remove(Iterable<String> keys)

Description copied from interface: ExternalWriteOperationsUnbuffered

Remove the entries with the specified keys.

Specified by:

remove in interface ExternalWriteOperationsUnbuffered<V>

Parameters:

keys - the keys of the entries to remove.

Returns:

no indication is given as to whether the entries existed before they were deleted

removeAll

public final CompletionStage<Void> removeAll()

Description copied from interface: ExternalWriteOperationsUnbuffered

Remove all entries in the cache.

Specified by:

removeAll in interface ExternalWriteOperationsUnbuffered<V>

Returns:

no indication is given as to whether entries existed before they were deleted