1 package com.atlassian.cache;
2
3 import com.atlassian.annotations.PublicApi;
4 import com.atlassian.util.concurrent.NotNull;
5
6 import java.util.Collection;
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 * Gets the keys of all objects currently stored in the cache. This will return the keys in a new collection.
20 * @return a collection of {@link Object}s keys.
21 */
22 Collection<K> getKeys();
23
24 /**
25 * Retrieve an object from this cache.
26 *
27 * @param key uniquely identifying the object to be retrieved.
28 * @return the object from the cache, or <code>null</code> if the object is not found.
29 */
30 V get(@NotNull final K key);
31
32 /**
33 * Put an object into the cache. If the specified key already exists within the cache, it will be replaced by the
34 * new object.
35 * <p>
36 * <b>NOTE:</b> Users of caches that wish to be well behaved in a clustered environment should use the
37 * {@link CacheLoader} semantics and supply a {@link CacheLoader} when getting the {@link Cache}.
38 *
39 * @param key uniquely identifying the object to be added into the cache.
40 * @param value to be cached.
41 */
42 void put(@NotNull final K key, final V value);
43
44 /**
45 * Remove the object identified by the key from the cache. If no object can be found associated with this key then
46 * no action is taken.
47 *
48 * @param key uniquely identifying the object to be removed.
49 */
50 void remove(@NotNull final K key);
51
52 /**
53 * Remove all of the objects from this cache.
54 */
55 void removeAll();
56
57 /**
58 * Atomically associates the specified key with the given value if it is not already associated with a value.
59 *
60 * @param key
61 * @param value
62 * @return the previous value associated with the specified key, or
63 * <code>null</code> if there was no mapping for the key.
64 */
65 V putIfAbsent(K key, V value);
66
67 /**
68 * Atomically replaces the entry for a key only if currently mapped to a given value.
69 *
70 * @param key key with which the specified value is associated
71 * @param oldValue value expected to be associated with the specified key
72 * @param newValue value to be associated with the specified key
73 * @return <code>true</code> if the value was replaced, <code>false</code> otherwise
74 */
75 boolean replace(K key, V oldValue, V newValue);
76
77 /**
78 * Atomically removes the entry for a key only if currently mapped to a given value.
79 *
80 * @param key key with which the specified value is associated
81 * @param value value expected to be associated with the specified key
82 * @return <code>true</code> if the value was removed, <code>false</code> otherwise
83 */
84 boolean remove(K key, V value);
85 }