1 /***
2 * Copyright 2003-2010 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.management;
18
19 /***
20 * @author Greg Luck
21 * @version $Id: CacheStatisticsMBean.html 13146 2011-08-01 17:12:39Z oletizi $
22 * @since 1.3
23 */
24 public interface CacheStatisticsMBean {
25
26 /***
27 * Clears the statistic counters to 0 for the associated Cache.
28 */
29 void clearStatistics();
30
31 /***
32 * The number of times a requested item was found in the cache.
33 *
34 * @return the number of times a requested item was found in the cache
35 */
36 long getCacheHits();
37
38 /***
39 * Number of times a requested item was found in the Memory Store.
40 *
41 * @return the number of times a requested item was found in memory
42 */
43 long getInMemoryHits();
44
45 /***
46 * Number of times a requested item was found in the off-heap store.
47 *
48 * @return the number of times a requested item was found off-heap, or 0 if there is no BigMemory storage configured.
49 */
50 long getOffHeapHits();
51
52 /***
53 * Number of times a requested item was found in the Disk Store.
54 *
55 * @return the number of times a requested item was found on Disk, or 0 if there is no disk storage configured.
56 */
57 long getOnDiskHits();
58
59 /***
60 * @return the number of times a requested element was not found in the cache
61 */
62 long getCacheMisses();
63
64 /***
65 * @return the number of times a requested element was not found in the memory cache
66 */
67 long getInMemoryMisses();
68
69 /***
70 * @return the number of times a requested element was not found in the off-heap cache
71 */
72 long getOffHeapMisses();
73
74 /***
75 * @return the number of times a requested element was not found in the disk cache
76 */
77 long getOnDiskMisses();
78
79 /***
80 * Gets the number of elements stored in the cache. Caclulating this can be expensive. Accordingly,
81 * this method will return three different values, depending on the statistics accuracy setting.
82 * <h3>Best Effort Size</h3>
83 * This result is returned when the statistics accuracy setting is {@link net.sf.ehcache.Statistics#STATISTICS_ACCURACY_BEST_EFFORT}.
84 * <p/>
85 * The size is the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
86 * the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.disk.DiskStore}.
87 * <p/>
88 * This number is the actual number of elements, including expired elements that have
89 * not been removed. Any duplicates between stores are accounted for.
90 * <p/>
91 * Expired elements are removed from the the memory store when
92 * getting an expired element, or when attempting to spool an expired element to
93 * disk.
94 * <p/>
95 * Expired elements are removed from the disk store when getting an expired element,
96 * or when the expiry thread runs, which is once every five minutes.
97 * <p/>
98 * <h3>Guaranteed Accuracy Size</h3>
99 * This result is returned when the statistics accuracy setting is {@link net.sf.ehcache.Statistics#STATISTICS_ACCURACY_GUARANTEED}.
100 * <p/>
101 * This method accounts for elements which might be expired or duplicated between stores. It take approximately
102 * 200ms per 1000 elements to execute.
103 * <h3>Fast but non-accurate Size</h3>
104 * This result is returned when the statistics accuracy setting is {@link net.sf.ehcache.Statistics#STATISTICS_ACCURACY_NONE}.
105 * <p/>
106 * The number given may contain expired elements. In addition if the DiskStore is used it may contain some double
107 * counting of elements. It takes 6ms for 1000 elements to execute. Time to execute is O(log n). 50,000 elements take
108 * 36ms.
109 *
110 * @return the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.
111 */
112 long getObjectCount();
113
114
115 /***
116 * Gets the number of objects in the MemoryStore
117 * @return the MemoryStore size which is always a count unadjusted for duplicates or expiries
118 */
119 long getMemoryStoreObjectCount();
120
121 /***
122 * Gets the number of objects in the OffHeapStore
123 * @return the OffHeapStore size which is always a count unadjusted for duplicates or expiries
124 */
125 long getOffHeapStoreObjectCount();
126
127 /***
128 * Gets the number of objects in the DiskStore
129 * @return the DiskStore size which is always a count unadjusted for duplicates or expiries
130 */
131 long getDiskStoreObjectCount();
132
133 /***
134 * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
135 *
136 * @return one of {@link net.sf.ehcache.Statistics#STATISTICS_ACCURACY_BEST_EFFORT},
137 * {@link net.sf.ehcache.Statistics#STATISTICS_ACCURACY_GUARANTEED},
138 * {@link net.sf.ehcache.Statistics#STATISTICS_ACCURACY_NONE}
139 */
140 int getStatisticsAccuracy();
141
142
143 /***
144 * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
145 * @return a human readable description of the accuracy setting. One of "None", "Best Effort" or "Guaranteed".
146 */
147 String getStatisticsAccuracyDescription();
148
149 /***
150 * @return the name of the Ehcache, or null is there no associated cache
151 */
152 String getAssociatedCacheName();
153
154 /***
155 * Returns the percentage of cache accesses that found a requested item in the cache.
156 *
157 * @return the percentage of successful hits
158 */
159 double getCacheHitPercentage();
160
161 /***
162 * Returns the percentage of cache accesses that did not find a requested element in the cache.
163 *
164 * @return the percentage of accesses that failed to find anything
165 */
166 double getCacheMissPercentage();
167
168 /***
169 * Returns the percentage of cache accesses that found a requested item cached in-memory.
170 *
171 * @return the percentage of successful hits from the MemoryStore
172 */
173 double getInMemoryHitPercentage();
174
175 /***
176 * Returns the percentage of cache accesses that found a requested item cached off-heap.
177 *
178 * @return the percentage of successful hits from the OffHeapStore
179 */
180 double getOffHeapHitPercentage();
181
182 /***
183 * Returns the percentage of cache accesses that found a requested item cached on disk.
184 *
185 * @return the percentage of successful hits from the DiskStore.
186 */
187 double getOnDiskHitPercentage();
188
189 /***
190 * Gets the size of the write-behind queue, if any.
191 * The value is for all local buckets
192 * @return Elements waiting to be processed by the write behind writer. -1 if no write-behind
193 */
194 long getWriterQueueLength();
195
196 /***
197 * Gets the maximum size of the write-behind queue, if any.
198 * @return Maximum elements waiting to be processed by the write behind writer. -1 if no write-behind
199 */
200 int getWriterMaxQueueSize();
201 }