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.
59 *
60 * @param key the key uniquely identifying the object to be retrieved
61 * @return the object from the cache, or {@code null} if the object is not found
62 */
63 @Nullable
64 V get(@Nonnull K key);
65
66 /**
67 * Retrieve an object from this cache.
68 * <p/>
69 * If no value is present in the cache, the {@code valueSupplier} will be used to populate the entry and be counted
70 * as a cache miss.
71 *
72 * @param key the key uniquely identifying the object to be retrieved
73 * @param valueSupplier the supplier to call if no value is stored in the cache. the value supplied by the supplier
74 * cannot be {@code null}
75 * @return the object from the cache, or the newly created value from the supplier
76 * @since 2.5
77 */
78 @Nonnull
79 V get(@Nonnull K key, @Nonnull Supplier<? extends V> valueSupplier);
80
81 /**
82 * Put an object into the cache. If the specified key already exists within the cache, it will be replaced by the
83 * new object.
84 * <p>
85 * <b>NOTE:</b> Users of caches that wish to be well behaved in a clustered environment should use the
86 * {@link CacheLoader} semantics and supply a {@link CacheLoader} when getting the {@link Cache}.
87 *
88 * @param key the key uniquely identifying the object to be added into the cache
89 * @param value the non-null value to be cached
90 */
91 void put(@Nonnull K key, @Nonnull V value);
92
93 /**
94 * Atomically associates the specified key with the given value if it is not already associated with a value.
95 *
96 * @param key the key with which the specified value is associated
97 * @param value the non-null value to be cached
98 * @return the previous value associated with the specified key, or {@code null} if there was no mapping for the key
99 */
100 @Nullable
101 V putIfAbsent(@Nonnull K key, @Nonnull V value);
102
103 /**
104 * Remove the object identified by the key from the cache. If no object can be found associated with this key then
105 * no action is taken.
106 *
107 * @param key the key that uniquely identifies the object to be removed
108 */
109 void remove(@Nonnull K key);
110
111 /**
112 * Atomically removes the entry for a key only if currently mapped to a given value.
113 *
114 * @param key the key with which the specified value is associated
115 * @param value the value expected to be associated with the specified key
116 * @return {@code true} if the value was removed, {@code false} otherwise
117 */
118 boolean remove(@Nonnull K key, @Nonnull V value);
119
120 /**
121 * Remove all of the objects from this cache.
122 */
123 void removeAll();
124
125 /**
126 * Atomically replaces the entry for a key only if currently mapped to a given value.
127 *
128 * @param key the key with which the specified value is associated
129 * @param oldValue the value expected to be associated with the specified key
130 * @param newValue the value to be associated with the specified key
131 * @return {@code true} if the value was replaced, {@code false} otherwise
132 */
133 boolean replace(@Nonnull K key, @Nonnull V oldValue, @Nonnull V newValue);
134
135 /**
136 * Adds a {@link CacheEntryListener}
137 * @param listener the listener
138 * @param includeValues if the events sent to this listener will include old/new value. This is can be used
139 * in cases when the cost of finding these values is big (network sync) but the listener is not interested in
140 * the concrete values for events its getting. The support for this parameter is optional and implementation dependant
141 * @since 2.4
142 */
143 void addListener(@Nonnull CacheEntryListener<K, V> listener, boolean includeValues);
144
145 /**
146 * Removes a {@link CacheEntryListener}
147 * @param listener the listener
148 * @since 2.4
149 */
150 void removeListener(@Nonnull CacheEntryListener<K, V> listener);
151 }