1 package com.atlassian.cache;
2
3 import java.util.Collection;
4
5 import javax.annotation.Nonnull;
6 import javax.annotation.Nullable;
7
8 import com.atlassian.annotations.PublicApi;
9
10 /**
11 * Interface that defines the common cache operations.
12 * <p>
13 * Note: {@code null} keys and values are NOT supported. Although using {@code null} values may work for some
14 * implementations, it won't work for all implementations and the behaviour may change over time.
15 *
16 * @param <K> the key type
17 * @param <V> the value type
18 */
19 @PublicApi
20 public interface Cache<K, V>
21 {
22 /**
23 * The name of the cache, uniquely identifies this cache.
24 *
25 * @return the name of the cache
26 */
27 @Nonnull
28 String getName();
29
30 /**
31 * Returns whether an entry exists in the cache under the specified key.
32 *
33 * <p>Note that:</p>
34 *
35 * <ul>
36 * <li>If the cache was created with a {@link com.atlassian.cache.CacheLoader},
37 * it will not be called. Obviously, any call to {@link #get(Object)}
38 * will call the corresponding {@link com.atlassian.cache.CacheLoader} (if required).</li>
39 * <li>If the cache was created with {@link CacheSettings#getReplicateViaCopy()}
40 * set to <tt>false</tt> and {@link CacheSettings#getLocal()} set to <tt>false</tt>,
41 * then only the local copy of the cache is checked. A local cache on
42 * another node may contain an entry under the specified key.</li>
43 * </ul>
44 * @param key the key for the entry to check for containment
45 * @return true iff the cache already contains an entry under the specified key
46 * @since 2.2.0
47 */
48 boolean containsKey(@Nonnull K key);
49
50 /**
51 * Gets the keys of all objects currently stored in the cache. This will return the keys in a new collection.
52 * @return a collection of {@link Object}s keys
53 */
54 @Nonnull
55 Collection<K> getKeys();
56
57 /**
58 * Retrieve an object from this cache. Note that a copy of the cached object may be returned. Any changes that are
59 * made to the returned object may not be reflected in the cache. Cached values should be considered effectively
60 * immutable.
61 *
62 * @param key the key uniquely identifying the object to be retrieved
63 * @return the object from the cache, or {@code null} if the object is not found
64 */
65 @Nullable
66 V get(@Nonnull K key);
67
68 /**
69 * Retrieve an object from this cache. Note that a copy of the cached object may be returned. Any changes that are
70 * made to the returned object may not be reflected in the cache. Cached values should be considered effectively
71 * immutable.
72 * <p>
73 * If no value is present in the cache, the {@code valueSupplier} will be used to populate the entry and be counted
74 * as a cache miss.
75 *
76 * @param key the key uniquely identifying the object to be retrieved
77 * @param valueSupplier the supplier to call if no value is stored in the cache. the value supplied by the supplier
78 * cannot be {@code null}
79 * @return the object from the cache, or the newly created value from the supplier
80 * @since 2.5
81 */
82 @Nonnull
83 V get(@Nonnull K key, @Nonnull Supplier<? extends V> valueSupplier);
84
85 /**
86 * Put an object into the cache. If the specified key already exists within the cache, it will be replaced by the
87 * new object.
88 * <p>
89 * <b>NOTE:</b> This method should not be used on {@link CacheSettingsBuilder#replicateViaInvalidation() hybrid}
90 * caches that maintain consistency only by invalidating the key on other cluster nodes. Instead, such hybrid
91 * caches should use {@link CacheLoader} semantics and supply a {@link CacheLoader} when getting the {@link Cache}.
92 *
93 * @param key the key uniquely identifying the object to be added into the cache
94 * @param value the non-null value to be cached
95 */
96 void put(@Nonnull K key, @Nonnull V value);
97
98 /**
99 * Atomically associates the specified key with the given value if it is not already associated with a value.
100 * <p>
101 * <b>NOTE:</b> This method should not be used on {@link CacheSettingsBuilder#replicateViaInvalidation() hybrid}
102 * caches that maintain consistency only by invalidating the key on other cluster nodes. Instead, such hybrid
103 * caches should use {@link CacheLoader} semantics and supply a {@link CacheLoader} when getting the {@link Cache}.
104 *
105 * @param key the key with which the specified value is associated
106 * @param value the non-null value to be cached
107 * @return the previous value associated with the specified key, or {@code null} if there was no mapping for the key
108 */
109 @Nullable
110 V putIfAbsent(@Nonnull K key, @Nonnull V value);
111
112 /**
113 * Remove the object identified by the key from the cache. If no object can be found associated with this key then
114 * no action is taken.
115 *
116 * @param key the key that uniquely identifies the object to be removed
117 */
118 void remove(@Nonnull K key);
119
120 /**
121 * Atomically removes the entry for a key only if currently mapped to a given value.
122 *
123 * @param key the key with which the specified value is associated
124 * @param value the value expected to be associated with the specified key
125 * @return {@code true} if the value was removed, {@code false} otherwise
126 */
127 boolean remove(@Nonnull K key, @Nonnull V value);
128
129 /**
130 * Remove all of the objects from this cache.
131 */
132 void removeAll();
133
134 /**
135 * Atomically replaces the entry for a key only if currently mapped to a given value.
136 *
137 * @param key the key with which the specified value is associated
138 * @param oldValue the value expected to be associated with the specified key
139 * @param newValue the value to be associated with the specified key
140 * @return {@code true} if the value was replaced, {@code false} otherwise
141 */
142 boolean replace(@Nonnull K key, @Nonnull V oldValue, @Nonnull V newValue);
143
144 /**
145 * Adds a {@link CacheEntryListener}
146 * @param listener the listener
147 * @param includeValues if the events sent to this listener will include old/new value. This is can be used
148 * in cases when the cost of finding these values is big (network sync) but the listener is not interested in
149 * the concrete values for events its getting. The support for this parameter is optional and implementation dependant
150 *
151 * @throws UnsupportedOperationException if not supported
152 * @since 2.4
153 * @deprecated since 2.9 may not be supported in all implementations and will be removed after June 2016
154 */
155 @Deprecated
156 void addListener(@Nonnull CacheEntryListener<K, V> listener, boolean includeValues);
157
158 /**
159 * Removes a {@link CacheEntryListener}
160 * @param listener the listener
161 *
162 * @throws UnsupportedOperationException if not supported
163 * @since 2.4
164 * @deprecated since 2.9 may not be supported in all implementations and will be removed after June 2016
165 */
166 @Deprecated
167 void removeListener(@Nonnull CacheEntryListener<K, V> listener);
168 }