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 CacheManager
38 */
39 @PublicApi
40 public interface CacheFactory
41 {
42 /**
43 * Returns a Cached Reference, creating it if necessary.
44 * @param name the name of the Cached Reference
45 * @param supplier the supplier for value to be cached, called if the value needs to be generated
46 * @return the Cached Reference
47 */
48 @Nonnull
49 <V> CachedReference<V> getCachedReference(@Nonnull String name,
50 @Nonnull Supplier<V> supplier);
51
52 /**
53 * Returns a Cached Reference, creating it if necessary.
54 * @param name the name of the Cached Reference
55 * @param supplier the supplier for value to be cached, called if the value needs to be generated
56 * @param required specifies the required cache settings
57 * @return the Cached Reference
58 */
59 @Nonnull
60 <V> CachedReference<V> getCachedReference(@Nonnull String name,
61 @Nonnull Supplier<V> supplier,
62 @Nonnull CacheSettings required);
63
64 /**
65 * Returns a Cached Reference, creating it if necessary.
66 * <p>
67 * It is equivalent to calling {@link #getCachedReference(String, Supplier, CacheSettings)}
68 *
69 * @param owningClass the owning class
70 * @param name the name of the cache spaced within the <tt>owningClass</tt>
71 * @param supplier the supplier for value to be cached, called if the value needs to be generated
72 * @return the Cached Reference
73 */
74 @Nonnull
75 <V> CachedReference<V> getCachedReference(@Nonnull Class<?> owningClass,
76 @Nonnull String name,
77 @Nonnull Supplier<V> supplier);
78
79 /**
80 * Returns a Cached Reference, creating it if necessary.
81 * <p>
82 * It is equivalent to calling {@link #getCachedReference(String, Supplier, CacheSettings)}
83 *
84 * @param owningClass the owning class
85 * @param name the name of the cache spaced within the <tt>owningClass</tt>
86 * @param supplier the supplier for value to be cached, called if the value needs to be generated
87 * @param required specifies the required cache settings
88 * @return the Cached Reference
89 */
90 @Nonnull
91 <V> CachedReference<V> getCachedReference(@Nonnull Class<?> owningClass,
92 @Nonnull String name,
93 @Nonnull Supplier<V> supplier,
94 @Nonnull CacheSettings required);
95
96 /**
97 * Returns the cache with the given name, creates it if necessary.
98 * This is equivalent to calling {@link #getCache(String, CacheLoader)}
99 * with <tt>name</tt> and <tt>null</tt>.
100 *
101 * @param name the name of the cache
102 * @return a Cache
103 */
104 @Nonnull
105 <K, V> Cache<K, V> getCache(@Nonnull String name);
106
107 /**
108 * Returns the cache with the given name, creates it if necessary.
109 * <p>
110 * It is equivalent to calling {@link #getCache(String)} with the computed name.
111 *
112 * @param owningClass the owning class
113 * @param name the name of the cache spaced within the <tt>owningClass</tt>
114 * @return a Cache
115 */
116 @Nonnull
117 <K, V> Cache<K, V> getCache(@Nonnull Class<?> owningClass, @Nonnull String name);
118
119 /**
120 * Returns the cache with the given name and loader, creates it if necessary.
121 * This is equivalent to calling {@link #getCache(String, CacheLoader, CacheSettings)}
122 * with <tt>name</tt>, <tt>null</tt> and <tt>new CacheSettingsBuilder().build()</tt>.
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 * @return a Cache
127 */
128 @Nonnull
129 <K, V> Cache<K, V> getCache(@Nonnull String name, @Nullable CacheLoader<K, V> loader);
130
131 /**
132 * Returns the cache with the given name, loader and required cache settings, creates it if necessary.
133 *
134 * @param name the name of the cache
135 * @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
136 * @param required the cache settings that are required to be set if the cache is created.
137 * @return a Cache
138 */
139 @Nonnull
140 <K, V> Cache<K, V> getCache(@Nonnull String name, @Nullable CacheLoader<K, V> loader, @Nonnull CacheSettings required);
141
142 /**
143 * Returns a cache with the given name, and the types specified. Creates it if necessary. If two caches of the
144 * same name are queried, with different types, the call with incorrect type arguments will throw a
145 * ClassCastException. For example with:<p/>
146 * Cache<String,String> firstCache = cacheManager.getCache("myCache", String.class, String.class); <br/>
147 * Cache<String,Long> secondCache = cacheManager.getCache("myCache", String.class, Long.class);
148 * <p/>
149 * the second call to getCache will result in a ClassCastException.
150 *
151 * @param name the name of the cache
152 * @param keyType the type of keys in the cache. Must extend Serializable
153 * @param valueType the type of values in the cache. Must extend Serializable
154 * @return a Cache
155 * @deprecated since 2.0, use getCache(name) instead
156 */
157 @Deprecated
158 @Nonnull
159 <K, V> Cache<K, V> getCache(@Nonnull String name, @Nonnull Class<K> keyType, @Nonnull Class<V> valueType);
160 }