1 package com.atlassian.cache;
2
3 import com.atlassian.annotations.PublicApi;
4 import com.atlassian.util.concurrent.NotNull;
5
6 /**
7 * Interface for creating and/or attaching to caches. Caches are identified by name,
8 * and two caches with the same name always refer to the same backing structure.
9 * <p>
10 * This factory and its builders hide many of the implementation details of any cache.
11 * The only real control you have is whether it is a local (JVM-local) or shared cache.
12 * All of the following maybe be different in some execution environments, so you should
13 * not assume any of them in your code:
14 * <li>Size and expiry settings (e.g. maxsize, expire times) may be overridden by admin or deployment settings.
15 * <li>When you builder.build() a cache for the first time in your code, the cache may already have items in it.
16 * For example, you are in a cluster. If your plugin is reloaded, or even if a node is restarted,
17 * shared caches will already have data in them.
18 * <li>For shared caches, when a new version of your code/plugin is deployed, it may already exist with data in it
19 * from a previous version of your code/plugin.
20 * <li>The keys and values in your non-local cache are effectively persistent from the point of view of
21 * your code/plugin. Therefore, you should consider backward compatibility of data, or invalidate
22 * caches on start/upgrade.
23 *
24 * The getCache methods called with a CacheLoader and getCachedReference methods will always return a new cache object that
25 * only holds a weak reference to the CacheLoader or Supplier that has been passed in. This is so we can support
26 * plugin reloadability. Consumers of this style of cache should get the cache only once and retain the reference to the
27 * cache during their complete lifecycle.
28 *
29 * The getCache methods called without a supplier will return a pre-existing cache of the same name if it already exists.
30 * Plugin developers should be aware that this may contain data from a previous instance of theri plugin (if it has been
31 * reloaded) and should refresh the cache when they obtain it, if this is appropriate.
32 *
33 * @see Cache
34 * @see CacheManager
35 */
36 @PublicApi
37 public interface CacheFactory
38 {
39 /**
40 * Returns a Cached Reference, creating it if necessary.
41 * @param name the name of the Cached Reference
42 * @param supplier the supplier for value to be cached, called if the value needs to be generated
43 * @return the Cached Reference
44 */
45 <V> CachedReference<V> getCachedReference(@NotNull String name,
46 @NotNull Supplier<V> supplier);
47
48 /**
49 * Returns a Cached Reference, creating it if necessary.
50 * @param name the name of the Cached Reference
51 * @param supplier the supplier for value to be cached, called if the value needs to be generated
52 * @param required specifies the required cache settings
53 * @return the Cached Reference
54 */
55 <V> CachedReference<V> getCachedReference(@NotNull String name,
56 @NotNull Supplier<V> supplier,
57 @NotNull CacheSettings required);
58
59 /**
60 * Returns a Cached Reference, creating it if necessary.
61 * <p>
62 * It is equivalent to calling {@link #getCachedReference(String, Supplier, CacheSettings)}
63 *
64 * @param owningClass the owning class
65 * @param name the name of the cache spaced within the <tt>owningClass</tt>
66 * @param supplier the supplier for value to be cached, called if the value needs to be generated
67 * @return the Cached Reference
68 */
69 <V> CachedReference<V> getCachedReference(@NotNull Class<?> owningClass,
70 @NotNull String name,
71 @NotNull Supplier<V> supplier);
72
73 /**
74 * Returns a Cached Reference, creating it if necessary.
75 * <p>
76 * It is equivalent to calling {@link #getCachedReference(String, Supplier, CacheSettings)}
77 *
78 * @param owningClass the owning class
79 * @param name the name of the cache spaced within the <tt>owningClass</tt>
80 * @param supplier the supplier for value to be cached, called if the value needs to be generated
81 * @param required specifies the required cache settings
82 * @return the Cached Reference
83 */
84 <V> CachedReference<V> getCachedReference(@NotNull Class<?> owningClass,
85 @NotNull String name,
86 @NotNull Supplier<V> supplier,
87 @NotNull CacheSettings required);
88
89 /**
90 * Returns the cache with the given name, creates it if necessary.
91 * This is equivalent to calling {@link #getCache(String, CacheLoader)}
92 * with <tt>name</tt> and <tt>null</tt>.
93 *
94 * @param name the name of the cache
95 * @return a Cache
96 */
97 <K, V> Cache<K, V> getCache(@NotNull String name);
98
99 /**
100 * Returns the cache with the given name, creates it if necessary.
101 * <p>
102 * It is equivalent to calling {@link #getCache(String)} with the computed name.
103 *
104 * @param owningClass the owning class
105 * @param name the name of the cache spaced within the <tt>owningClass</tt>
106 * @return a Cache
107 */
108 <K, V> Cache<K, V> getCache(@NotNull Class<?> owningClass, @NotNull String name);
109
110 /**
111 * Returns the cache with the given name and loader, creates it if necessary.
112 * This is equivalent to calling {@link #getCache(String, CacheLoader, CacheSettings)}
113 * with <tt>name</tt>, <tt>null</tt> and <tt>new CacheSettingsBuilder().build()</tt>.
114 *
115 * @param name the name of the cache
116 * @param loader the loader that will be used to provide values for keys that will be added to the cache. <tt>null</tt> indicates no loader
117 * @return a Cache
118 */
119 <K, V> Cache<K, V> getCache(@NotNull String name, CacheLoader<K, V> loader);
120
121 /**
122 * Returns the cache with the given name, loader and required cache settings, creates it if necessary.
123 *
124 * @param name the name of the cache
125 * @param loader the loader that will be used to provide values for keys that will be added to the cache. <tt>null</tt> indicates no loader
126 * @param required the cache settings that are required to be set if the cache is created.
127 * @return a Cache
128 */
129 <K, V> Cache<K, V> getCache(@NotNull String name, CacheLoader<K, V> loader, @NotNull CacheSettings required);
130
131 /**
132 * Returns a cache with the given name, and the types specified. Creates it if necessary. If two caches of the
133 * same name are queries, with different types, the call with incorrect type arguments will throw a
134 * ClassCastException. For example with:<p/>
135 * Cache<String,String> firstCache = cacheManager.getCache("myCache", String.class, String.class); <br/>
136 * Cache<String,Long> secondCache = cacheManager.getCache("myCache", String.class, Long.class);
137 * <p/>
138 * the second call to getCache will result in a ClassCastException.
139 *
140 * @param name the name of the cache
141 * @param keyType the type of keys in the cache. Must extend Serializable
142 * @param valueType the type of values in the cache. Must extend Serializable
143 * @return a Cache
144 * @deprecated since 2.0, use getCache(name) instead
145 */
146 @Deprecated
147 <K, V> Cache<K, V> getCache(@NotNull String name, @NotNull Class<K> keyType, @NotNull Class<V> valueType);
148 }