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