1 package com.atlassian.cache.compat;
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 * A Cache created using a {@link CacheLoader} will never return null.
28 *
29 * @param key uniquely identifying the object to be retrieved.
30 * @return the object from the cache, or <code>null</code> if the object is not found.
31 */
32 V get(@NotNull final K key);
33
34 /**
35 * Put an object into the cache. If the specified key already exists within the cache, it will be replaced by the
36 * new object.
37 * <p>
38 * <b>NOTE:</b> Users of caches that wish to be well behaved in a clustered environment should use the
39 * {@link CacheLoader} semantics and supply a {@link CacheLoader} when getting the {@link Cache}.
40 *
41 * @param key uniquely identifying the object to be added into the cache.
42 * @param value to be cached.
43 */
44 void put(@NotNull final K key, final V value);
45
46 /**
47 * Remove the object identified by the key from the cache. If no object can be found associated with this key then
48 * no action is taken.
49 *
50 * @param key uniquely identifying the object to be removed.
51 */
52 void remove(@NotNull final K key);
53
54 /**
55 * Remove all of the objects from this cache.
56 */
57 void removeAll();
58 }