com.atlassian.cache

Interface CacheFactory

All Known Subinterfaces:

CacheManager

@PublicApi
public interface CacheFactory

Interface for creating and/or attaching to caches. Caches are identified by name, and two caches with the same name always refer to the same backing structure.

This factory and its builders hide many of the implementation details of any cache. The only real control you have is whether it is a local (JVM-local) or shared cache. All of the following maybe be different in some execution environments, so you should not assume any of them in your code:

• Size and expiry settings (e.g. maxsize, expire times) may be overridden by admin or deployment settings.
• When you builder.build() a cache for the first time in your code, the cache may already have items in it. For example, you are in a cluster. If your plugin is reloaded, or even if a node is restarted, shared caches will already have data in them.
• For shared caches, when a new version of your code/plugin is deployed, it may already exist with data in it from a previous version of your code/plugin.
• The keys and values in your non-local cache are effectively persistent from the point of view of your code/plugin. Therefore, you should consider backward compatibility of data, or invalidate caches on start/upgrade.

The getCache methods called with a CacheLoader and getCachedReference methods will always return a new cache object that only holds a weak reference to the CacheLoader or Supplier that has been passed in. This is so we can support plugin reloadability. Consumers of this style of cache should get the cache only once and retain the reference to the cache during their complete lifecycle. The getCache methods called without a supplier will return a pre-existing cache of the same name if it already exists. Plugin developers should be aware that this may contain data from a previous instance of their plugin (if it has been reloaded) and should refresh the cache when they obtain it, if this is appropriate.

See Also:

Cache, CachedReference, CacheManager

Method Summary

Modifier and Type	Method and Description
<K,V> Cache<K,V>	getCache(Class<?> owningClass, String name) Returns the cache with the given name, creates it if necessary.
<K,V> Cache<K,V>	getCache(String name) Returns the cache with the given name, creates it if necessary.
<K,V> Cache<K,V>	getCache(String name, CacheLoader<K,V> loader) Returns the cache with the given name and loader, creates it if necessary.
<K,V> Cache<K,V>	getCache(String name, CacheLoader<K,V> loader, CacheSettings required) Returns the cache with the given name, loader and required cache settings, creates it if necessary.
<K,V> Cache<K,V>	getCache(String name, Class<K> keyType, Class<V> valueType) Deprecated. since 2.0, use getCache(name) instead
<V> CachedReference<V>	getCachedReference(Class<?> owningClass, String name, Supplier<V> supplier) Returns a Cached Reference, creating it if necessary.
<V> CachedReference<V>	getCachedReference(Class<?> owningClass, String name, Supplier<V> supplier, CacheSettings required) Returns a Cached Reference, creating it if necessary.
<V> CachedReference<V>	getCachedReference(String name, Supplier<V> supplier) Returns a Cached Reference, creating it if necessary.
<V> CachedReference<V>	getCachedReference(String name, Supplier<V> supplier, CacheSettings required) Returns a Cached Reference, creating it if necessary.

Method Detail

getCachedReference

@Nonnull
<V> CachedReference<V> getCachedReference(@Nonnull
                                                   String name,
                                                   @Nonnull
                                                   Supplier<V> supplier)

Returns a Cached Reference, creating it if necessary.

Parameters:

name - the name of the Cached Reference

supplier - the supplier for value to be cached, called if the value needs to be generated

Returns:

the Cached Reference

getCachedReference

@Nonnull
<V> CachedReference<V> getCachedReference(@Nonnull
                                                   String name,
                                                   @Nonnull
                                                   Supplier<V> supplier,
                                                   @Nonnull
                                                   CacheSettings required)

Returns a Cached Reference, creating it if necessary.

Parameters:

name - the name of the Cached Reference

supplier - the supplier for value to be cached, called if the value needs to be generated

required - specifies the required cache settings

Returns:

the Cached Reference

getCachedReference

@Nonnull
<V> CachedReference<V> getCachedReference(@Nonnull
                                                   Class<?> owningClass,
                                                   @Nonnull
                                                   String name,
                                                   @Nonnull
                                                   Supplier<V> supplier)

Returns a Cached Reference, creating it if necessary.

It is equivalent to calling getCachedReference(String, Supplier, CacheSettings)

Parameters:

owningClass - the owning class

name - the name of the cache spaced within the owningClass

supplier - the supplier for value to be cached, called if the value needs to be generated

Returns:

the Cached Reference

getCachedReference

@Nonnull
<V> CachedReference<V> getCachedReference(@Nonnull
                                                   Class<?> owningClass,
                                                   @Nonnull
                                                   String name,
                                                   @Nonnull
                                                   Supplier<V> supplier,
                                                   @Nonnull
                                                   CacheSettings required)

Returns a Cached Reference, creating it if necessary.

It is equivalent to calling getCachedReference(String, Supplier, CacheSettings)

Parameters:

owningClass - the owning class

name - the name of the cache spaced within the owningClass

supplier - the supplier for value to be cached, called if the value needs to be generated

required - specifies the required cache settings

Returns:

the Cached Reference

getCache

@Nonnull
<K,V> Cache<K,V> getCache(@Nonnull
                                   String name)

Returns the cache with the given name, creates it if necessary. This is equivalent to calling getCache(String, CacheLoader) with name and null.

Parameters:

name - the name of the cache

Returns:

a Cache

getCache

@Nonnull
<K,V> Cache<K,V> getCache(@Nonnull
                                   Class<?> owningClass,
                                   @Nonnull
                                   String name)

Returns the cache with the given name, creates it if necessary.

It is equivalent to calling getCache(String) with the computed name.

Parameters:

owningClass - the owning class

name - the name of the cache spaced within the owningClass

Returns:

a Cache

getCache

@Nonnull
<K,V> Cache<K,V> getCache(@Nonnull
                                   String name,
                                   @Nullable
                                   CacheLoader<K,V> loader)

Returns the cache with the given name and loader, creates it if necessary. This is equivalent to calling getCache(String, CacheLoader, CacheSettings) with name, null and new CacheSettingsBuilder().build().

Parameters:

name - the name of the cache

loader - the loader that will be used to provide values for keys that will be added to the cache. null indicates no loader

Returns:

a Cache

getCache

@Nonnull
<K,V> Cache<K,V> getCache(@Nonnull
                                   String name,
                                   @Nullable
                                   CacheLoader<K,V> loader,
                                   @Nonnull
                                   CacheSettings required)

Returns the cache with the given name, loader and required cache settings, creates it if necessary.

Parameters:

name - the name of the cache

loader - the loader that will be used to provide values for keys that will be added to the cache. null indicates no loader

required - the cache settings that are required to be set if the cache is created.

Returns:

a Cache

getCache

@Deprecated
 @Nonnull
<K,V> Cache<K,V> getCache(@Nonnull
                                                String name,
                                                @Nonnull
                                                Class<K> keyType,
                                                @Nonnull
                                                Class<V> valueType)

Deprecated. since 2.0, use getCache(name) instead

Returns a cache with the given name, and the types specified. Creates it if necessary. If two caches of the same name are queried, with different types, the call with incorrect type arguments will throw a ClassCastException. For example with:

Cache<String,String> firstCache = cacheManager.getCache("myCache", String.class, String.class);
Cache<String,Long> secondCache = cacheManager.getCache("myCache", String.class, Long.class);

the second call to getCache will result in a ClassCastException.

Parameters:

name - the name of the cache

keyType - the type of keys in the cache. Must extend Serializable

valueType - the type of values in the cache. Must extend Serializable

Returns:

a Cache