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 * @see Cache
25 * @see CacheManager
26 */
27 @PublicApi
28 public interface CacheFactory
29 {
30 /**
31 * Returns a Cached Reference, creating it if necessary.
32 * @param name the name of the Cached Reference
33 * @param supplier the supplier for value to be cached, called if the value needs to be generated
34 * @return the Cached Reference
35 */
36 <V> CachedReference<V> getCachedReference(@NotNull String name,
37 @NotNull Supplier<V> supplier);
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 * @param required specifies the required cache settings
44 * @return the Cached Reference
45 */
46 <V> CachedReference<V> getCachedReference(@NotNull String name,
47 @NotNull Supplier<V> supplier,
48 @NotNull CacheSettings required);
49
50 /**
51 * Returns a Cached Reference, creating it if necessary.
52 * <p>
53 * It is equivalent to calling {@link #getCachedReference(String, Supplier, CacheSettings)}
54 *
55 * @param owningClass the owning class
56 * @param name the name of the cache spaced within the <tt>owningClass</tt>
57 * @param supplier the supplier for value to be cached, called if the value needs to be generated
58 * @return the Cached Reference
59 */
60 <V> CachedReference<V> getCachedReference(@NotNull Class<?> owningClass,
61 @NotNull String name,
62 @NotNull Supplier<V> supplier);
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 * @param required specifies the required cache settings
73 * @return the Cached Reference
74 */
75 <V> CachedReference<V> getCachedReference(@NotNull Class<?> owningClass,
76 @NotNull String name,
77 @NotNull Supplier<V> supplier,
78 @NotNull CacheSettings required);
79
80 /**
81 * Returns the cache with the given name, creates it if necessary.
82 * This is equivalent to calling {@link #getCache(String, CacheLoader)}
83 * with <tt>name</tt> and <tt>null</tt>.
84 *
85 * @param name the name of the cache
86 * @return a Cache
87 */
88 <K, V> Cache<K, V> getCache(@NotNull String name);
89
90 /**
91 * Returns the cache with the given name, creates it if necessary.
92 * <p>
93 * It is equivalent to calling {@link #getCache(String)} with the computed name.
94 *
95 * @param owningClass the owning class
96 * @param name the name of the cache spaced within the <tt>owningClass</tt>
97 * @return a Cache
98 */
99 <K, V> Cache<K, V> getCache(@NotNull Class<?> owningClass, @NotNull String name);
100
101 /**
102 * Returns the cache with the given name and loader, creates it if necessary.
103 * This is equivalent to calling {@link #getCache(String, CacheLoader, CacheSettings)}
104 * with <tt>name</tt>, <tt>null</tt> and <tt>new CacheSettingsBuilder().build()</tt>.
105 *
106 * @param name the name of the cache
107 * @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
108 * @return a Cache
109 */
110 <K, V> Cache<K, V> getCache(@NotNull String name, CacheLoader<K, V> loader);
111
112 /**
113 * Returns the cache with the given name, loader and required cache settings, creates it if necessary.
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 * @param required the cache settings that are required to be set if the cache is created.
118 * @return a Cache
119 */
120 <K, V> Cache<K, V> getCache(@NotNull String name, CacheLoader<K, V> loader, @NotNull CacheSettings required);
121
122 /**
123 * Returns a cache with the given name, and the types specified. Creates it if necessary. If two caches of the
124 * same name are queries, with different types, the call with incorrect type arguments will throw a
125 * ClassCastException. For example with:<p/>
126 * Cache<String,String> firstCache = cacheManager.getCache("myCache", String.class, String.class); <br/>
127 * Cache<String,Long> secondCache = cacheManager.getCache("myCache", String.class, Long.class);
128 * <p/>
129 * the second call to getCache will result in a ClassCastException.
130 *
131 * @param name the name of the cache
132 * @param keyType the type of keys in the cache. Must extend Serializable
133 * @param valueType the type of values in the cache. Must extend Serializable
134 * @return a Cache
135 * @deprecated since 2.0, use getCache(name) instead
136 */
137 @Deprecated
138 <K, V> Cache<K, V> getCache(@NotNull String name, @NotNull Class<K> keyType, @NotNull Class<V> valueType);
139 }