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 theri plugin (if it has been reloaded) and should refresh the cache when they obtain it, if this is appropriate.

    See Also:
    Cache, CacheManager

    Method Summary
    <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

    <V> CachedReference<V> getCachedReference(@NotNull
                                              String name,
                                              @NotNull
                                              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

    <V> CachedReference<V> getCachedReference(@NotNull
                                              String name,
                                              @NotNull
                                              Supplier<V> supplier,
                                              @NotNull
                                              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

    <V> CachedReference<V> getCachedReference(@NotNull
                                              Class<?> owningClass,
                                              @NotNull
                                              String name,
                                              @NotNull
                                              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

    <V> CachedReference<V> getCachedReference(@NotNull
                                              Class<?> owningClass,
                                              @NotNull
                                              String name,
                                              @NotNull
                                              Supplier<V> supplier,
                                              @NotNull
                                              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

    <K,V> Cache<K,V> getCache(@NotNull
                              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

    <K,V> Cache<K,V> getCache(@NotNull
                              Class<?> owningClass,
                              @NotNull
                              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

    <K,V> Cache<K,V> getCache(@NotNull
                              String name,
                              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

    <K,V> Cache<K,V> getCache(@NotNull
                              String name,
                              CacheLoader<K,V> loader,
                              @NotNull
                              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
    <K,V> Cache<K,V> getCache(@NotNull
                                         String name,
                                         @NotNull
                                         Class<K> keyType,
                                         @NotNull
                                         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 queries, with different types, the call with incorrect type arguments will throw a ClassCastException. For example with:

    Cache firstCache = cacheManager.getCache("myCache", String.class, String.class);
    Cache 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


    Copyright © 2014 Atlassian. All Rights Reserved.