1 package com.atlassian.cache;
2
3 import java.util.Collection;
4
5 import com.atlassian.annotations.PublicApi;
6 import com.atlassian.util.concurrent.NotNull;
7
8 @PublicApi
9 public interface Cache<K, V>
10 {
11 /**
12 * The name of the cache, uniquely identifies this cache.
13 *
14 * @return the name of the cache.
15 */
16 String getName();
17
18 /**
19 * Returns whether an entry exists in the cache under the specified key.
20 *
21 * <p>Note that:</p>
22 *
23 * <ul>
24 * <li>If the cache was created with a {@link com.atlassian.cache.CacheLoader},
25 * it will not be called. Obviously, any call to {@link #get(Object)}
26 * will call the corresponding {@link com.atlassian.cache.CacheLoader} (if required).</li>
27 * <li>If the cache was created with {@link CacheSettings#getReplicateViaCopy()}
28 * set to <tt>false</tt> and {@link CacheSettings#getLocal()} set to <tt>false</tt>,
29 * then only the local copy of the cache is checked. A local cache on
30 * another node may contain an entry under the specified key.</li>
31 * </ul>
32 * @param key the key for the entry to check for containment.
33 * @return true iff the cache already contains an entry under the specified key.
34 * @since 2.2.0
35 */
36 boolean containsKey(@NotNull final K key);
37
38 /**
39 * Gets the keys of all objects currently stored in the cache. This will return the keys in a new collection.
40 * @return a collection of {@link Object}s keys.
41 */
42 Collection<K> getKeys();
43
44 /**
45 * Retrieve an object from this cache.
46 *
47 * @param key uniquely identifying the object to be retrieved.
48 * @return the object from the cache, or <code>null</code> if the object is not found.
49 */
50 V get(@NotNull final K key);
51
52 /**
53 * Put an object into the cache. If the specified key already exists within the cache, it will be replaced by the
54 * new object.
55 * <p>
56 * <b>NOTE:</b> Users of caches that wish to be well behaved in a clustered environment should use the
57 * {@link CacheLoader} semantics and supply a {@link CacheLoader} when getting the {@link Cache}.
58 *
59 * @param key uniquely identifying the object to be added into the cache.
60 * @param value to be cached.
61 */
62 void put(@NotNull final K key, final V value);
63
64 /**
65 * Remove the object identified by the key from the cache. If no object can be found associated with this key then
66 * no action is taken.
67 *
68 * @param key uniquely identifying the object to be removed.
69 */
70 void remove(@NotNull final K key);
71
72 /**
73 * Remove all of the objects from this cache.
74 */
75 void removeAll();
76
77 /**
78 * Atomically associates the specified key with the given value if it is not already associated with a value.
79 *
80 * @param key
81 * @param value
82 * @return the previous value associated with the specified key, or
83 * <code>null</code> if there was no mapping for the key.
84 */
85 V putIfAbsent(K key, V value);
86
87 /**
88 * Atomically replaces the entry for a key only if currently mapped to a given value.
89 *
90 * @param key key with which the specified value is associated
91 * @param oldValue value expected to be associated with the specified key
92 * @param newValue value to be associated with the specified key
93 * @return <code>true</code> if the value was replaced, <code>false</code> otherwise
94 */
95 boolean replace(K key, V oldValue, V newValue);
96
97 /**
98 * Atomically removes the entry for a key only if currently mapped to a given value.
99 *
100 * @param key key with which the specified value is associated
101 * @param value value expected to be associated with the specified key
102 * @return <code>true</code> if the value was removed, <code>false</code> otherwise
103 */
104 boolean remove(K key, V value);
105 }