Package 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:

  • Method Details

    • 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

    • getReadThroughCache

      default <K, V> ReadThroughCache<K,V> getReadThroughCache(@Nonnull String name)
      Returns the ReadThroughCache with the given name, creates it if necessary.
      Parameters:
      name - the name of the cache
      Returns:
      a ReadThroughCache
      Since:
      6.1

    • getReadThroughCache

      default <K, V> ReadThroughCache<K,V> getReadThroughCache(@Nonnull String name, @Nonnull CacheSettings required)
      Returns the ReadThroughCache with the given name, creates it if necessary.
      Parameters:
      name - the name of the cache
      Returns:
      a ReadThroughCache
      Since:
      6.1

    • 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