1 package com.atlassian.cache;
2
3 import java.util.SortedMap;
4 import java.util.concurrent.TimeUnit;
5
6 import javax.annotation.Nonnull;
7 import javax.annotation.Nullable;
8
9 import com.atlassian.annotations.Internal;
10 import com.atlassian.util.concurrent.Supplier;
11
12 /**
13 * Interface that managed cache things need to implement
14 *
15 *
16 * @since 2.0
17 */
18 @Internal
19 @SuppressWarnings("UnusedDeclaration")
20 public interface ManagedCache
21 {
22 /**
23 * Clear the cache.
24 */
25 void clear();
26
27 /**
28 * The name of the cache, uniquely identifies this cache.
29 *
30 * @return the name of the cache.
31 */
32 @Nonnull
33 String getName();
34
35 /**
36 * Returns true if this cache can be safely flushed any time.
37 * <p>
38 * This method is used by {@link CacheManager#flushCaches()} to only flush
39 * caches that can be safely flushed. {@link #clear()} ignores this value.
40 *
41 * @return true if this cache can be flushed safely.
42 */
43 boolean isFlushable();
44
45 /**
46 * @return the current hint regarding the maximum number of entries that should be cached at any time.
47 * <tt>null</tt> indicates no current hint
48 */
49 @Nullable
50 Integer currentMaxEntries();
51
52 /**
53 * Attempts to update the hint regarding the maximum number of entries that should be cached at any time.
54 * @param newValue the new hint value
55 * @return <tt>true</tt> iff the hint has been updated to the new value. If a cache does not support changes at
56 * run-time, it must return <tt>false</tt>
57 */
58 boolean updateMaxEntries(int newValue);
59
60 /**
61 * @return the current hint regarding how long entries should be held in the cache, after last access, measured in milliseconds.
62 * <tt>null</tt> indicates no current hint
63 */
64 @Nullable
65 Long currentExpireAfterAccessMillis();
66
67 /**
68 * Attempts to update the hint regarding how long entries that should be held in the cache, after last access.
69 * @param expireAfter Time to retain entries for since their last access.
70 * @param timeUnit The {@link TimeUnit} for the time
71 * @return <tt>true</tt> iff the hint has been updated to the new value. If a cache does not support changes at
72 * run-time, it must return <tt>false</tt>
73 */
74 boolean updateExpireAfterAccess(long expireAfter, @Nonnull TimeUnit timeUnit);
75
76 /**
77 * @return the current hint regarding how long entries should be held in the cache, after last write, measured in milliseconds.
78 * <tt>null</tt> indicates no current hint
79 */
80 @Nullable
81 Long currentExpireAfterWriteMillis();
82
83 /**
84 * Attempts to update the hint regarding how long entries that should be held in the cache, after last write.
85 * @param expireAfter Time to retain entries for since their last write.
86 * @param timeUnit The {@link TimeUnit} for the time
87 * @return <tt>true</tt> iff the hint has been updated to the new value. If a cache does not support changes at
88 * run-time, it must return <tt>false</tt>
89 */
90 boolean updateExpireAfterWrite(long expireAfter, @Nonnull TimeUnit timeUnit);
91
92 /**
93 * @return true if the cache is local, and hence is not replicated in a clustered environment
94 */
95 boolean isLocal();
96
97 /**
98 * @return true if this cache should be replicated asynchronously in a clustered environment.
99 */
100 boolean isReplicateAsynchronously();
101
102 /**
103 * @return true if this cache should, in a clustered environment, replicate put and update operations
104 * by copying the relevant key and value across the wire (as opposed to just the key).
105 */
106 boolean isReplicateViaCopy();
107
108 /**
109 * @return true if this cache gathers statistics.
110 */
111 boolean isStatisticsEnabled();
112
113 /**
114 * Get usage statistics for the cache.
115 *
116 * The statistics are sorted by the cache statistics key {@link CacheStatisticsKey#getLabel() labels}.
117 * Providing statistics is an optional feature and no assumptions should be made by the caller about
118 * which (if any) statistics will be returned.
119 *
120 * @return a map of statistics keys to suppliers for their values, sorted lexically by the statistics key's label
121 * @since v2.4.0
122 */
123 @Nonnull
124 SortedMap<CacheStatisticsKey, Supplier<Long>> getStatistics();
125 }