com.atlassian.cache.hazelcast

Class HazelcastHybridCache<K,V>

java.lang.Object

com.atlassian.cache.hazelcast.ManagedHybridCacheSupport

com.atlassian.cache.hazelcast.HazelcastHybridCache<K,V>

All Implemented Interfaces:

Cache<K,V>, ManagedCache

public class HazelcastHybridCache<K,V>
extends ManagedHybridCacheSupport
implements Cache<K,V>

Implementation of ManagedCache and Cache that can be used when the cached values do not implement Serializable but cache invalidation must work cluster-wide.

This implementation tracks versions of entries in Hazelcast IMap, but stores the actual values in a local cache. Caches entries are invalidated when the cache is modified through one of the put, clear, remove or replace methods. Cache entries are never invalidated when get(Object) is called, not even when a value is lazily created and added to the cache.

These semantics mean that hybrid caches should only be used as computing caches (by providing a CacheLoader) and that values should not be manually put(Object, Object) in the cache. Doing so will lead to frequent cache evictions.

Since:

2.4.0

Field Summary

Fields inherited from class com.atlassian.cache.hazelcast.ManagedHybridCacheSupport

cacheManager, name

Constructor Summary

Constructors

Constructor and Description
HazelcastHybridCache(String name, CacheFactory localCacheFactory, com.hazelcast.core.IMap<K,Long> versionMap, CacheLoader<K,V> cacheLoader, HazelcastCacheManager cacheManager)

Method Summary

Modifier and Type	Method and Description
void	addListener(CacheEntryListener<K,V> listener, boolean includeValues) Adds a CacheEntryListener
void	clear() Clear the cache.
boolean	containsKey(K k) Returns whether an entry exists in the cache under the specified key.
V	get(K key) Retrieve an object from this cache.
V	get(K key, Supplier<? extends V> valueSupplier) Retrieve an object from this cache.
Collection<K>	getKeys() Gets the keys of all objects currently stored in the cache.
protected ManagedCache	getLocalCache()
String	getName() The name of the cache, uniquely identifies this cache.
boolean	isFlushable() Returns true if this cache can be safely flushed any time.
boolean	isReplicateAsynchronously()
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	remove(K key) Remove the object identified by the key from the cache.
boolean	remove(K key, V value) Atomically removes the entry for a key only if currently mapped to a given value.
void	removeAll() Remove all of the objects from this cache.
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.
boolean	updateExpireAfterAccess(long expireAfter, TimeUnit timeUnit) Attempts to update the hint regarding how long entries that should be held in the cache, after last access.
boolean	updateExpireAfterWrite(long expireAfter, TimeUnit timeUnit) Attempts to update the hint regarding how long entries that should be held in the cache, after last write.
boolean	updateMaxEntries(int newValue) Attempts to update the hint regarding the maximum number of entries that should be cached at any time.

Methods inherited from class com.atlassian.cache.hazelcast.ManagedHybridCacheSupport

currentExpireAfterAccessMillis, currentExpireAfterWriteMillis, currentMaxEntries, getStatistics, isLocal, isReplicateViaCopy, isStatisticsEnabled, setStatistics

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.atlassian.cache.ManagedCache

getCacheCollector

Constructor Detail

HazelcastHybridCache

public HazelcastHybridCache(String name,
                            CacheFactory localCacheFactory,
                            com.hazelcast.core.IMap<K,Long> versionMap,
                            CacheLoader<K,V> cacheLoader,
                            HazelcastCacheManager cacheManager)

Method Detail

clear

public void clear()

Description copied from interface: ManagedCache

Clear the cache.

Specified by:

clear in interface ManagedCache

containsKey

public boolean containsKey(@Nonnull
                           K k)

Description copied from interface: Cache

Returns whether an entry exists in the cache under the specified key.

Note that:

• If the cache was created with a CacheLoader, it will not be called. Obviously, any call to Cache.get(Object) will call the corresponding CacheLoader (if required).
• If the cache was created with CacheSettings.getReplicateViaCopy() set to false and CacheSettings.getLocal() set to false, then only the local copy of the cache is checked. A local cache on another node may contain an entry under the specified key.

Specified by:

containsKey in interface Cache<K,V>

Parameters:

k - the key for the entry to check for containment

Returns:

true iff the cache already contains an entry under the specified key

get

public V get(@Nonnull
             K key)

Description copied from interface: Cache

Retrieve an object from this cache. Note that a copy of the cached object may be returned. Any changes that are made to the returned object may not be reflected in the cache. Cached values should be considered effectively immutable.

Specified by:

get in interface Cache<K,V>

Parameters:

key - the key uniquely identifying the object to be retrieved

Returns:

the object from the cache, or null if the object is not found

get

@Nonnull
public V get(@Nonnull
                      K key,
                      @Nonnull
                      Supplier<? extends V> valueSupplier)

Description copied from interface: Cache

Retrieve an object from this cache. Note that a copy of the cached object may be returned. Any changes that are made to the returned object may not be reflected in the cache. Cached values should be considered effectively immutable.

If no value is present in the cache, the valueSupplier will be used to populate the entry and be counted as a cache miss.

Specified by:

get in interface Cache<K,V>

Parameters:

key - the key uniquely identifying the object to be retrieved

valueSupplier - the supplier to call if no value is stored in the cache. the value supplied by the supplier cannot be null

Returns:

the object from the cache, or the newly created value from the supplier

getKeys

@Nonnull
public Collection<K> getKeys()

Description copied from interface: Cache

Gets the keys of all objects currently stored in the cache. This will return the keys in a new collection.

Specified by:

getKeys in interface Cache<K,V>

Returns:

a collection of Objects keys

getName

@Nonnull
public String getName()

Description copied from interface: ManagedCache

The name of the cache, uniquely identifies this cache.

Specified by:

getName in interface Cache<K,V>

Specified by:

getName in interface ManagedCache

Overrides:

getName in class ManagedHybridCacheSupport

Returns:

the name of the cache.

isReplicateAsynchronously

public boolean isReplicateAsynchronously()

Specified by:

isReplicateAsynchronously in interface ManagedCache

Returns:

true if this cache should be replicated asynchronously in a clustered environment.

put

public void put(@Nonnull
                K key,
                @Nonnull
                V value)

Description copied from interface: Cache

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.

Specified by:

put in interface Cache<K,V>

Parameters:

key - the key uniquely identifying the object to be added into the cache

value - the non-null value to be cached

putIfAbsent

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

This implementation has a weak spot: When there is an existing value, this method must return it. However, if that value is stored in a remote node, it cannot be returned. null is returned instead, which signals success. In order to not break any contracts, this implementation will invalidate the value on all nodes in this situation.

Specified by:

putIfAbsent in interface Cache<K,V>

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

remove

public void remove(@Nonnull
                   K key)

Description copied from interface: Cache

Remove the object identified by the key from the cache. If no object can be found associated with this key then no action is taken.

Specified by:

remove in interface Cache<K,V>

Parameters:

key - the key that uniquely identifies the object to be removed

remove

public boolean remove(@Nonnull
                      K key,
                      @Nonnull
                      V value)

Description copied from interface: Cache

Atomically removes the entry for a key only if currently mapped to a given value.

Specified by:

remove in interface Cache<K,V>

Parameters:

key - the key with which the specified value is associated

value - the value expected to be associated with the specified key

Returns:

true if the value was removed, false otherwise

removeAll

public void removeAll()

Description copied from interface: Cache

Remove all of the objects from this cache.

Specified by:

removeAll in interface Cache<K,V>

replace

public boolean replace(@Nonnull
                       K key,
                       @Nonnull
                       V oldValue,
                       @Nonnull
                       V newValue)

Description copied from interface: Cache

Atomically replaces the entry for a key only if currently mapped to a given value.

Specified by:

replace in interface Cache<K,V>

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

updateExpireAfterAccess

public boolean updateExpireAfterAccess(long expireAfter,
                                       @Nonnull
                                       TimeUnit timeUnit)

Description copied from interface: ManagedCache

Attempts to update the hint regarding how long entries that should be held in the cache, after last access.

Specified by:

updateExpireAfterAccess in interface ManagedCache

Overrides:

updateExpireAfterAccess in class ManagedHybridCacheSupport

Parameters:

expireAfter - Time to retain entries for since their last access.

timeUnit - The TimeUnit for the time

Returns:

true iff the hint has been updated to the new value. If a cache does not support changes at run-time, it must return false

updateExpireAfterWrite

public boolean updateExpireAfterWrite(long expireAfter,
                                      @Nonnull
                                      TimeUnit timeUnit)

Description copied from interface: ManagedCache

Attempts to update the hint regarding how long entries that should be held in the cache, after last write.

Specified by:

updateExpireAfterWrite in interface ManagedCache

Overrides:

updateExpireAfterWrite in class ManagedHybridCacheSupport

Parameters:

expireAfter - Time to retain entries for since their last write.

timeUnit - The TimeUnit for the time

Returns:

true iff the hint has been updated to the new value. If a cache does not support changes at run-time, it must return false

updateMaxEntries

public boolean updateMaxEntries(int newValue)

Description copied from interface: ManagedCache

Attempts to update the hint regarding the maximum number of entries that should be cached at any time.

Specified by:

updateMaxEntries in interface ManagedCache

Overrides:

updateMaxEntries in class ManagedHybridCacheSupport

Parameters:

newValue - the new hint value

Returns:

true iff the hint has been updated to the new value. If a cache does not support changes at run-time, it must return false

addListener

public void addListener(@Nonnull
                        CacheEntryListener<K,V> listener,
                        boolean includeValues)

Description copied from interface: Cache

Adds a CacheEntryListener

Specified by:

addListener in interface Cache<K,V>

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

removeListener

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

Description copied from interface: Cache

Removes a CacheEntryListener

Specified by:

removeListener in interface Cache<K,V>

Parameters:

listener - the listener

getLocalCache

protected ManagedCache getLocalCache()

Specified by:

getLocalCache in class ManagedHybridCacheSupport

isFlushable

public boolean isFlushable()

Description copied from interface: ManagedCache

Returns true if this cache can be safely flushed any time.

This method is used by CacheManager.flushCaches() to only flush caches that can be safely flushed. ManagedCache.clear() ignores this value.

Specified by:

isFlushable in interface ManagedCache

Returns:

true if this cache can be flushed safely.