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> Users of caches that wish to be well behaved in a clustered environment should use the
90 * {@link CacheLoader} semantics and supply a {@link CacheLoader} when getting the {@link Cache}.
91 *
92 * @param key the key uniquely identifying the object to be added into the cache
93 * @param value the non-null value to be cached
94 */
95 void put(@Nonnull K key, @Nonnull V value);
96
97 /**
98 * Atomically associates the specified key with the given value if it is not already associated with a value.
99 *
100 * @param key the key with which the specified value is associated
101 * @param value the non-null value to be cached
102 * @return the previous value associated with the specified key, or {@code null} if there was no mapping for the key
103 */
104 @Nullable
105 V putIfAbsent(@Nonnull K key, @Nonnull V value);
106
107 /**
108 * Remove the object identified by the key from the cache. If no object can be found associated with this key then
109 * no action is taken.
110 *
111 * @param key the key that uniquely identifies the object to be removed
112 */
113 void remove(@Nonnull K key);
114
115 /**
116 * Atomically removes the entry for a key only if currently mapped to a given value.
117 *
118 * @param key the key with which the specified value is associated
119 * @param value the value expected to be associated with the specified key
120 * @return {@code true} if the value was removed, {@code false} otherwise
121 */
122 boolean remove(@Nonnull K key, @Nonnull V value);
123
124 /**
125 * Remove all of the objects from this cache.
126 */
127 void removeAll();
128
129 /**
130 * Atomically replaces the entry for a key only if currently mapped to a given value.
131 *
132 * @param key the key with which the specified value is associated
133 * @param oldValue the value expected to be associated with the specified key
134 * @param newValue the value to be associated with the specified key
135 * @return {@code true} if the value was replaced, {@code false} otherwise
136 */
137 boolean replace(@Nonnull K key, @Nonnull V oldValue, @Nonnull V newValue);
138
139 /**
140 * Adds a {@link CacheEntryListener}
141 * @param listener the listener
142 * @param includeValues if the events sent to this listener will include old/new value. This is can be used
143 * in cases when the cost of finding these values is big (network sync) but the listener is not interested in
144 * the concrete values for events its getting. The support for this parameter is optional and implementation dependant
145 *
146 * @throws UnsupportedOperationException if not supported
147 * @since 2.4
148 * @deprecated since 2.9 may not be supported in all implementations and will be removed after June 2016
149 */
150 @Deprecated
151 void addListener(@Nonnull CacheEntryListener<K, V> listener, boolean includeValues);
152
153 /**
154 * Removes a {@link CacheEntryListener}
155 * @param listener the listener
156 *
157 * @throws UnsupportedOperationException if not supported
158 * @since 2.4
159 * @deprecated since 2.9 may not be supported in all implementations and will be removed after June 2016
160 */
161 @Deprecated
162 void removeListener(@Nonnull CacheEntryListener<K, V> listener);
163 }