001: /**
002: * Copyright 2003-2007 Luck Consulting Pty Ltd
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */package net.sf.ehcache;
016:
017: import org.apache.commons.logging.Log;
018: import org.apache.commons.logging.LogFactory;
019:
020: import java.io.Serializable;
021:
022: /**
023: * An immutable Cache statistics implementation}
024: * <p/>
025: * This is like a value object, with the added ability to clear cache statistics on the cache.
026: * That ability does not survive any Serialization of this class. On deserialization the cache
027: * can be considered disconnected.
028: * <p/>
029: * The accuracy of these statistics are determined by the value of {#getStatisticsAccuracy()}
030: * at the time the statistic was computed. This can be changed by setting {@link Cache#setStatisticsAccuracy}.
031: * <p/>
032: * Because this class maintains a reference to an Ehcache, any references held to this class will precent the Ehcache
033: * from getting garbage collected.
034: * <p/>
035: * The {@link #STATISTICS_ACCURACY_BEST_EFFORT}, {@link #STATISTICS_ACCURACY_GUARANTEED} and {@link #STATISTICS_ACCURACY_NONE}
036: * constants have the same values as in JSR107.
037: *
038: * @author Greg Luck
039: * @version $Id: Statistics.java 519 2007-07-27 07:11:45Z gregluck $
040: */
041: public class Statistics implements Serializable {
042:
043: /**
044: * Fast but not accurate setting.
045: */
046: public static final int STATISTICS_ACCURACY_NONE = 0;
047:
048: /**
049: * Best efforts accuracy setting.
050: */
051: public static final int STATISTICS_ACCURACY_BEST_EFFORT = 1;
052:
053: /**
054: * Guaranteed accuracy setting.
055: */
056: public static final int STATISTICS_ACCURACY_GUARANTEED = 2;
057:
058: private static final Log LOG = LogFactory.getLog(Statistics.class
059: .getName());
060:
061: private static final long serialVersionUID = 3606940454221918725L;
062:
063: private transient Ehcache cache;
064:
065: private final int statisticsAccuracy;
066:
067: private final long cacheHits;
068:
069: private final long onDiskHits;
070:
071: private final long inMemoryHits;
072:
073: private final long misses;
074:
075: private final long size;
076:
077: private float averageGetTime;
078:
079: private long evictionCount;
080:
081: /**
082: * Creates a new statistics object, associated with a Cache
083: *
084: * @param cache The cache that {@link #clearStatistics()} will call, if not disconnected
085: * @param statisticsAccuracy
086: * @param cacheHits
087: * @param onDiskHits
088: * @param inMemoryHits
089: * @param misses
090: * @param size
091: */
092: public Statistics(Ehcache cache, int statisticsAccuracy,
093: long cacheHits, long onDiskHits, long inMemoryHits,
094: long misses, long size, float averageGetTime,
095: long evictionCount) {
096: this .statisticsAccuracy = statisticsAccuracy;
097: this .cacheHits = cacheHits;
098: this .onDiskHits = onDiskHits;
099: this .inMemoryHits = inMemoryHits;
100: this .misses = misses;
101: this .cache = cache;
102: this .size = size;
103: this .averageGetTime = averageGetTime;
104: this .evictionCount = evictionCount;
105: }
106:
107: /**
108: * Clears the statistic counters to 0 for the associated Cache.
109: */
110: public void clearStatistics() {
111: if (cache == null) {
112: throw new IllegalStateException(
113: "This statistics object no longer references a Cache.");
114: }
115: try {
116: cache.clearStatistics();
117: } catch (IllegalStateException e) {
118: if (LOG.isDebugEnabled()) {
119: LOG.info("Ignoring call because " + e.getMessage());
120: }
121: }
122: }
123:
124: /**
125: * The number of times a requested item was found in the cache.
126: *
127: * @return the number of times a requested item was found in the cache
128: */
129: public long getCacheHits() {
130: return cacheHits;
131: }
132:
133: /**
134: * Number of times a requested item was found in the Memory Store.
135: *
136: * @return the number of times a requested item was found in memory
137: */
138: public long getInMemoryHits() {
139: return inMemoryHits;
140: }
141:
142: /**
143: * Number of times a requested item was found in the Disk Store.
144: *
145: * @return the number of times a requested item was found on Disk, or 0 if there is no disk storage configured.
146: */
147: public long getOnDiskHits() {
148: return onDiskHits;
149: }
150:
151: /**
152: * @return the number of times a requested element was not found in the cache
153: */
154: public long getCacheMisses() {
155: return misses;
156:
157: }
158:
159: /**
160: * Gets the number of elements stored in the cache. Caclulating this can be expensive. Accordingly,
161: * this method will return three different values, depending on the statistics accuracy setting.
162: * <h3>Best Effort Size</h3>
163: * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}.
164: * <p/>
165: * The size is the number of {@link Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
166: * the number of {@link Element}s in the {@link net.sf.ehcache.store.DiskStore}.
167: * <p/>
168: * This number is the actual number of elements, including expired elements that have
169: * not been removed. Any duplicates between stores are accounted for.
170: * <p/>
171: * Expired elements are removed from the the memory store when
172: * getting an expired element, or when attempting to spool an expired element to
173: * disk.
174: * <p/>
175: * Expired elements are removed from the disk store when getting an expired element,
176: * or when the expiry thread runs, which is once every five minutes.
177: * <p/>
178: * <h3>Guaranteed Accuracy Size</h3>
179: * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}.
180: * <p/>
181: * This method accounts for elements which might be expired or duplicated between stores. It take approximately
182: * 200ms per 1000 elements to execute.
183: * <h3>Fast but non-accurate Size</h3>
184: * This result is returned when the statistics accuracy setting is {@link #STATISTICS_ACCURACY_NONE}.
185: * <p/>
186: * The number given may contain expired elements. In addition if the DiskStore is used it may contain some double
187: * counting of elements. It takes 6ms for 1000 elements to execute. Time to execute is O(log n). 50,000 elements take
188: * 36ms.
189: *
190: * @return the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.
191: */
192: public long getObjectCount() {
193: return size;
194: }
195:
196: /**
197: * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
198: *
199: * @return one of {@link #STATISTICS_ACCURACY_BEST_EFFORT}, {@link #STATISTICS_ACCURACY_GUARANTEED}, {@link #STATISTICS_ACCURACY_NONE}
200: */
201: public int getStatisticsAccuracy() {
202: return statisticsAccuracy;
203: }
204:
205: /**
206: * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
207: * @return a human readable description of the accuracy setting. One of "None", "Best Effort" or "Guaranteed".
208: */
209: public String getStatisticsAccuracyDescription() {
210: if (statisticsAccuracy == 0) {
211: return "None";
212: } else if (statisticsAccuracy == 1) {
213: return "Best Effort";
214: } else {
215: return "Guaranteed";
216: }
217: }
218:
219: /**
220: * @return the name of the Ehcache, or null if a reference is no longer held to the cache,
221: * as, it would be after deserialization.
222: */
223: public String getAssociatedCacheName() {
224: if (cache != null) {
225: return cache.getName();
226: } else {
227: return null;
228: }
229: }
230:
231: /**
232: * @return the name of the Ehcache, or null if a reference is no longer held to the cache,
233: * as, it would be after deserialization.
234: */
235: public Ehcache getAssociatedCache() {
236: if (cache != null) {
237: return cache;
238: } else {
239: return null;
240: }
241: }
242:
243: /**
244: * Returns a {@link String} representation of the {@link Ehcache} statistics.
245: */
246: public final String toString() {
247: StringBuffer dump = new StringBuffer();
248:
249: dump.append("[ ").append(" name = ").append(
250: getAssociatedCacheName()).append(" cacheHits = ")
251: .append(cacheHits).append(" onDiskHits = ").append(
252: onDiskHits).append(" inMemoryHits = ").append(
253: inMemoryHits).append(" misses = ").append(
254: misses).append(" size = ").append(size).append(
255: " averageGetTime = ").append(averageGetTime)
256: .append(" evictionCount = ").append(evictionCount)
257: .append(" ]");
258:
259: return dump.toString();
260: }
261:
262: /**
263: * The average get time. Because ehcache support JDK1.4.2, each get time uses
264: * System.currentTimeMilis, rather than nanoseconds. The accuracy is thus limited.
265: */
266: public float getAverageGetTime() {
267: return averageGetTime;
268: }
269:
270: /**
271: * Gets the number of cache evictions, since the cache was created, or statistics were cleared.
272: */
273: public long getEvictionCount() {
274: return evictionCount;
275: }
276:
277: }
|