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.instrumentation.caches.CacheCollector;
11 import java.util.function.Supplier;
12
13 /**
14 * Interface that managed cache things need to implement
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 caches that can be safely flushed. {@link
39 * #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. <tt>null</tt>
47 * 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 *
55 * @param newValue the new hint value
56 * @return <tt>true</tt> iff the hint has been updated to the new value. If a cache does not support changes at
57 * run-time, it must return <tt>false</tt>
58 */
59 boolean updateMaxEntries(int newValue);
60
61 /**
62 * @return the current hint regarding how long entries should be held in the cache, after last access, measured in
63 * milliseconds. <tt>null</tt> indicates no current hint
64 */
65 @Nullable
66 Long currentExpireAfterAccessMillis();
67
68 /**
69 * Attempts to update the hint regarding how long entries that should be held in the cache, after last access.
70 *
71 * @param expireAfter Time to retain entries for since their last access.
72 * @param timeUnit The {@link TimeUnit} for the time
73 * @return <tt>true</tt> iff the hint has been updated to the new value. If a cache does not support changes at
74 * run-time, it must return <tt>false</tt>
75 */
76 boolean updateExpireAfterAccess(long expireAfter, @Nonnull TimeUnit timeUnit);
77
78 /**
79 * @return the current hint regarding how long entries should be held in the cache, after last write, measured in
80 * milliseconds. <tt>null</tt> indicates no current hint
81 */
82 @Nullable
83 Long currentExpireAfterWriteMillis();
84
85 /**
86 * Attempts to update the hint regarding how long entries that should be held in the cache, after last write.
87 *
88 * @param expireAfter Time to retain entries for since their last write.
89 * @param timeUnit The {@link TimeUnit} for the time
90 * @return <tt>true</tt> iff the hint has been updated to the new value. If a cache does not support changes at
91 * run-time, it must return <tt>false</tt>
92 */
93 boolean updateExpireAfterWrite(long expireAfter, @Nonnull TimeUnit timeUnit);
94
95 /**
96 * @return true if the cache is local, and hence is not replicated in a clustered environment
97 */
98 boolean isLocal();
99
100 /**
101 * @return true if this cache should be replicated asynchronously in a clustered environment.
102 */
103 boolean isReplicateAsynchronously();
104
105 /**
106 * @return true if this cache should, in a clustered environment, replicate put and update operations by copying the
107 * relevant key and value across the wire (as opposed to just the key).
108 */
109 boolean isReplicateViaCopy();
110
111 /**
112 * @return true if this cache gathers statistics.
113 */
114 boolean isStatisticsEnabled();
115
116 /**
117 * Changes the state of statistics gathering.
118 *
119 * @param enabled The stats collection is enabled if true - disabled otherwise.
120 * @since 2.8.4
121 * @deprecated Use {@link com.atlassian.instrumentation.caches.CacheCollector#setEnabled(boolean)} instead for
122 * memory caches. This method was never implemented for other cache types.
123 */
124 @Deprecated
125 void setStatistics(boolean enabled);
126
127 /**
128 * Get usage statistics for the cache.
129 * <p>
130 * The statistics are sorted by the cache statistics key {@link CacheStatisticsKey#getLabel() labels}. Providing
131 * statistics is an optional feature and no assumptions should be made by the caller about which (if any) statistics
132 * will be returned.
133 *
134 * @return a map of statistics keys to suppliers for their values, sorted lexically by the statistics key's label
135 * @since v2.4.0
136 */
137 @Nonnull
138 SortedMap<CacheStatisticsKey, Supplier<Long>> getStatistics();
139
140 /**
141 * Returns the collector for this cache.
142 *
143 * @return The {@link CacheCollector} for this cache.
144 * @since 2.8.4
145 */
146 @Nullable
147 default CacheCollector getCacheCollector() {
148 return null;
149 }
150 }