1 /***
2 * Copyright 2003-2009 Terracotta, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package net.sf.ehcache;
18
19 import java.io.Serializable;
20
21 /***
22 * An immutable Cache statistics implementation}
23 * <p/>
24 * This is like a value object, with the added ability to clear cache statistics on the cache.
25 * That ability does not survive any Serialization of this class. On deserialization the cache
26 * can be considered disconnected.
27 * <p/>
28 * The accuracy of these statistics are determined by the value of {#getStatisticsAccuracy()}
29 * at the time the statistic was computed. This can be changed by setting {@link Cache#setStatisticsAccuracy}.
30 * <p/>
31 * Because this class maintains a reference to an Ehcache, any references held to this class will precent the Ehcache
32 * from getting garbage collected.
33 * <p/>
34 * todo Add missCountExpired. Request from user.
35 *
36 * @author Greg Luck
37 * @version $Id: Statistics.java 1480 2009-12-02 14:38:28Z cdennis $
38 */
39 public class Statistics implements Serializable {
40
41 /***
42 * Fast but not accurate setting.
43 */
44 public static final int STATISTICS_ACCURACY_NONE = 0;
45
46 /***
47 * Best efforts accuracy setting.
48 */
49 public static final int STATISTICS_ACCURACY_BEST_EFFORT = 1;
50
51 /***
52 * Guaranteed accuracy setting.
53 */
54 public static final int STATISTICS_ACCURACY_GUARANTEED = 2;
55
56 private static final long serialVersionUID = 3606940454221918725L;
57
58 private transient Ehcache cache;
59
60 private final String cacheName;
61
62 private final int statisticsAccuracy;
63
64 private final long cacheHits;
65
66 private final long onDiskHits;
67
68 private final long inMemoryHits;
69
70 private final long misses;
71
72 private final long size;
73
74 private final long memoryStoreSize;
75
76 private final long diskStoreSize;
77
78 private float averageGetTime;
79
80 private long evictionCount;
81
82
83 /***
84 * Creates a new statistics object, associated with a Cache
85 *
86 * @param cache The cache that {@link #clearStatistics()} will call, if not disconnected
87 * @param statisticsAccuracy
88 * @param cacheHits
89 * @param onDiskHits
90 * @param inMemoryHits
91 * @param misses
92 * @param size
93 */
94 public Statistics(Ehcache cache, int statisticsAccuracy, long cacheHits, long onDiskHits, long inMemoryHits,
95 long misses, long size, float averageGetTime, long evictionCount, long memoryStoreSize,
96 long diskStoreSize) {
97 this.cacheName = cache.getName();
98 this.statisticsAccuracy = statisticsAccuracy;
99 this.cacheHits = cacheHits;
100 this.onDiskHits = onDiskHits;
101 this.inMemoryHits = inMemoryHits;
102 this.misses = misses;
103 this.cache = cache;
104 this.size = size;
105 this.averageGetTime = averageGetTime;
106 this.evictionCount = evictionCount;
107 this.memoryStoreSize = memoryStoreSize;
108 this.diskStoreSize = diskStoreSize;
109 }
110
111 /***
112 * Clears the statistic counters to 0 for the associated Cache.
113 */
114 public void clearStatistics() {
115 if (cache == null) {
116 throw new IllegalStateException("This statistics object no longer references a Cache.");
117 }
118 cache.clearStatistics();
119 }
120
121 /***
122 * The number of times a requested item was found in the cache.
123 *
124 * @return the number of times a requested item was found in the cache
125 */
126 public long getCacheHits() {
127 return cacheHits;
128 }
129
130 /***
131 * Number of times a requested item was found in the Memory Store.
132 *
133 * @return the number of times a requested item was found in memory
134 */
135 public long getInMemoryHits() {
136 return inMemoryHits;
137 }
138
139 /***
140 * Number of times a requested item was found in the Disk Store.
141 *
142 * @return the number of times a requested item was found on Disk, or 0 if there is no disk storage configured.
143 */
144 public long getOnDiskHits() {
145 return onDiskHits;
146 }
147
148 /***
149 * @return the number of times a requested element was not found in the cache
150 */
151 public long getCacheMisses() {
152 return misses;
153
154 }
155
156 /***
157 * Gets the number of elements stored in the cache. Caclulating this can be expensive. Accordingly,
158 * this method will return three different values, depending on the statistics accuracy setting.
159 * <h3>Best Effort Size</h3>
160 * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}.
161 * <p/>
162 * The size is the number of {@link Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
163 * the number of {@link Element}s in the {@link net.sf.ehcache.store.DiskStore}.
164 * <p/>
165 * This number is the actual number of elements, including expired elements that have
166 * not been removed. Any duplicates between stores are accounted for.
167 * <p/>
168 * Expired elements are removed from the the memory store when
169 * getting an expired element, or when attempting to spool an expired element to
170 * disk.
171 * <p/>
172 * Expired elements are removed from the disk store when getting an expired element,
173 * or when the expiry thread runs, which is once every five minutes.
174 * <p/>
175 * <h3>Guaranteed Accuracy Size</h3>
176 * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}.
177 * <p/>
178 * This method accounts for elements which might be expired or duplicated between stores. It take approximately
179 * 200ms per 1000 elements to execute.
180 * <h3>Fast but non-accurate Size</h3>
181 * This result is returned when the statistics accuracy setting is {@link #STATISTICS_ACCURACY_NONE}.
182 * <p/>
183 * The number given may contain expired elements. In addition if the DiskStore is used it may contain some double
184 * counting of elements. It takes 6ms for 1000 elements to execute. Time to execute is O(log n). 50,000 elements take
185 * 36ms.
186 *
187 * @return the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.
188 */
189 public long getObjectCount() {
190 return size;
191 }
192
193 /***
194 *
195 * @return the number of objects in the memory store
196 */
197 public long getMemoryStoreObjectCount() {
198 return memoryStoreSize;
199 }
200
201 /***
202 *
203 * @return the number of objects in the disk store
204 */
205 public long getDiskStoreObjectCount() {
206 return diskStoreSize;
207 }
208
209 /***
210 * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
211 *
212 * @return one of {@link #STATISTICS_ACCURACY_BEST_EFFORT}, {@link #STATISTICS_ACCURACY_GUARANTEED}, {@link #STATISTICS_ACCURACY_NONE}
213 */
214 public int getStatisticsAccuracy() {
215 return statisticsAccuracy;
216 }
217
218 /***
219 * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
220 *
221 * @return a human readable description of the accuracy setting. One of "None", "Best Effort" or "Guaranteed".
222 */
223 public String getStatisticsAccuracyDescription() {
224 if (statisticsAccuracy == 0) {
225 return "None";
226 } else if (statisticsAccuracy == 1) {
227 return "Best Effort";
228 } else {
229 return "Guaranteed";
230 }
231 }
232
233 /***
234 * @return the name of the Ehcache, or null if a reference is no longer held to the cache,
235 * as, it would be after deserialization.
236 */
237 public String getAssociatedCacheName() {
238 if (cache != null) {
239 return cache.getName();
240 } else {
241 return cacheName;
242 }
243 }
244
245 /***
246 * @return the name of the Ehcache, or null if a reference is no longer held to the cache,
247 * as, it would be after deserialization.
248 */
249 public Ehcache getAssociatedCache() {
250 if (cache != null) {
251 return cache;
252 } else {
253 return null;
254 }
255 }
256
257 /***
258 * Returns a {@link String} representation of the {@link Ehcache} statistics.
259 */
260 @Override
261 public final String toString() {
262 StringBuilder dump = new StringBuilder();
263
264 dump.append("[ ")
265 .append(" name = ").append(getAssociatedCacheName())
266 .append(" cacheHits = ").append(cacheHits)
267 .append(" onDiskHits = ").append(onDiskHits)
268 .append(" inMemoryHits = ").append(inMemoryHits)
269 .append(" misses = ").append(misses)
270 .append(" size = ").append(size)
271 .append(" averageGetTime = ").append(averageGetTime)
272 .append(" evictionCount = ").append(evictionCount)
273 .append(" ]");
274
275 return dump.toString();
276 }
277
278 /***
279 * The average get time. Because ehcache support JDK1.4.2, each get time uses
280 * System.currentTimeMilis, rather than nanoseconds. The accuracy is thus limited.
281 */
282 public float getAverageGetTime() {
283 return averageGetTime;
284 }
285
286 /***
287 * Gets the number of cache evictions, since the cache was created, or statistics were cleared.
288 */
289 public long getEvictionCount() {
290 return evictionCount;
291 }
292
293 /***
294 * Utility method to determine if a given value is a valid statistics
295 * accuracy value or not
296 *
297 * @param statisticsAccuracy
298 * @return true if the value is one of
299 * {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT},
300 * {@link Statistics#STATISTICS_ACCURACY_GUARANTEED},
301 * {@link Statistics#STATISTICS_ACCURACY_NONE}
302 */
303 public static boolean isValidStatisticsAccuracy(int statisticsAccuracy) {
304 return statisticsAccuracy == STATISTICS_ACCURACY_NONE
305 || statisticsAccuracy == STATISTICS_ACCURACY_BEST_EFFORT
306 || statisticsAccuracy == STATISTICS_ACCURACY_GUARANTEED;
307 }
308
309 }