1 package com.atlassian.cache;
2
3 import java.util.Comparator;
4
5 import javax.annotation.Nonnull;
6
7 import static com.atlassian.cache.StatisticsType.COUNTER;
8 import static com.atlassian.cache.StatisticsType.GAUGE;
9 import static java.util.Objects.requireNonNull;
10
11 /**
12 * An immutable representation of a statistics key for a Cache.
13 *
14 * This class is used by {@link ManagedCache#getStatistics()} to dynamically distinguish different cache
15 * statistics available for a {@link com.atlassian.cache.Cache}.
16 *
17 * @since v2.4.0
18 */
19 public enum CacheStatisticsKey
20 {
21 /**
22 * Returns the number of cached objects kept referenced by the {@link Cache} (depends on the cache implementation)
23 */
24 SIZE("size", GAUGE),
25
26 /**
27 * Returns the number of bytes used by the {@link Cache}.
28 * <p>
29 * Note: This is likely to be a very expensive statistic in some implementations, so consumers may want
30 * to discard it when it hasn't been explicitly requested. Even where available, the reported heap size
31 * is almost certain to be only an approximation of the cache's total memory use.
32 * </p>
33 */
34 HEAP_SIZE("heapSize", GAUGE),
35
36 /**
37 * Returns the number of times {@link Cache} lookup methods have returned a cached value.
38 */
39 HIT_COUNT("hitCount", COUNTER),
40
41 /**
42 * Returns the number of times {@link Cache} put methods have added a cached value.
43 */
44 PUT_COUNT("putCount", COUNTER),
45
46 /**
47 * Returns the number of times {@link Cache} remove methods have removed a cached value.
48 */
49 REMOVE_COUNT("removeCount", COUNTER),
50
51 /**
52 * Returns the number of times {@link Cache} lookup methods have returned an uncached (newly
53 * loaded) value, or null. Multiple concurrent calls to {@link Cache} lookup methods on an absent
54 * value can result in multiple misses, all returning the results of a single cache load
55 * operation.
56 */
57 MISS_COUNT("missCount", COUNTER),
58
59 /**
60 * Returns the total number of times that Cache lookup methods attempted to load new values.
61 */
62 LOAD_COUNT("loadCount", COUNTER),
63
64 /**
65 * Returns the number of times Cache lookup methods have successfully loaded a new value.
66 */
67 LOAD_SUCCESS_COUNT("loadSuccessCount", COUNTER),
68
69 /**
70 * Returns the number of times Cache lookup methods threw an exception while loading a new value.
71 */
72 LOAD_EXCEPTION_COUNT("loadExceptionCount", COUNTER),
73
74 /**
75 * Returns the number of nanoseconds spent computing values for cache misses. This
76 * is only relevant for caches using a CacheLoader.
77 */
78 TOTAL_MISS_TIME("totalMissTime", COUNTER),
79
80 /**
81 * Returns the total number of nanoseconds the cache has spent loading new values.
82 */
83 TOTAL_LOAD_TIME("totalLoadTime", COUNTER),
84
85 /**
86 * Returns the number of times an entry has been evicted.
87 */
88 EVICTION_COUNT("evictionCount", COUNTER),
89
90 /**
91 * Returns the number of times Cache lookup methods have returned either a cached or uncached value.
92 */
93 REQUEST_COUNT("requestCount", COUNTER);
94
95
96
97 /** Sorts cache statistics keys by {@link #getLabel() label}. */
98 public static Comparator<CacheStatisticsKey> SORT_BY_LABEL = new Comparator<CacheStatisticsKey>()
99 {
100 @Override
101 public int compare(CacheStatisticsKey key1, CacheStatisticsKey key2)
102 {
103 return key1.getLabel().compareTo(key2.getLabel());
104 }
105 };
106
107 private final String label;
108 private final StatisticsType type;
109
110 private CacheStatisticsKey(String label, StatisticsType type)
111 {
112 this.label = requireNonNull(label, "label");
113 this.type = requireNonNull(type, "type");
114 }
115
116 /**
117 * Returns the label for this cache statistics key.
118 * This is intended to be the same as the {@link #name()}, except written in {@code camelCase}.
119 * @return the label for this cache statistics key.
120 */
121 @Nonnull
122 public String getLabel()
123 {
124 return label;
125 }
126
127 /**
128 * Returns the type of statistic that this is.
129 * Different types of statistics might render differently in a user interface.
130 * @return the type of statistic that this is.
131 */
132 @Nonnull
133 public StatisticsType getType()
134 {
135 return type;
136 }
137 }