001package org.cache2k.jmx;
002
003/*
004 * #%L
005 * cache2k jmx api definitions
006 * %%
007 * Copyright (C) 2000 - 2014 headissue GmbH, Munich
008 * %%
009 * This program is free software: you can redistribute it and/or modify
010 * it under the terms of the GNU General Public License as
011 * published by the Free Software Foundation, either version 3 of the 
012 * License, or (at your option) any later version.
013 * 
014 * This program is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
017 * GNU General Public License for more details.
018 * 
019 * You should have received a copy of the GNU General Public 
020 * License along with this program.  If not, see
021 * <http://www.gnu.org/licenses/gpl-3.0.html>.
022 * #L%
023 */
024
025import java.util.Date;
026
027/**
028 * Exposed statistics via JMX from a cache.
029 *
030 * @author Jens Wilke; created: 2013-07-16
031 */
032@SuppressWarnings("unused")
033public interface CacheInfoMXBean {
034
035  /**
036   * The current number of entries within the cache, starting with 0.
037   */
038  int getSize();
039
040  /**
041   * The configured maximum number of entries in the cache.
042   */
043  int getMaximumSize();
044
045  /**
046   * How often data was requested from the cache. In multi threading scenarios this
047   * counter may be not totally accurate. For performance reason the cache implementation
048   * may choose to only present a best effort value. It is guaranteed that the
049   * usage count is always greater than the miss count.
050   */
051  long getUsageCnt();
052
053  /**
054   * Counter of the event that: a client requested a data which was not
055   * present in the cache or had expired.
056   */
057  long getMissCnt();
058
059  /**
060   * How many new cache entries are created. This counts a cache miss on get()
061   * or a put().
062   */
063  long getNewEntryCnt();
064
065  /**
066   * How many times the data was fetched from the cache source.
067   */
068  long getFetchCnt();
069
070  /**
071   * Counter for the event that the data of a cache entry was refreshed.
072   */
073  long getRefreshCnt();
074
075  /**
076   * Counter how many times a refresh submit failed, meaning that there were
077   * not enough thread resources available.
078   */
079  long getRefreshSubmitFailedCnt();
080
081  /**
082   * How many times we had a hit on a refreshed entry.
083   */
084  long getRefreshHitCnt();
085
086  /**
087   * Counter for the event that data in the cache has expired.
088   *
089   * <p>This can mean that the cache entry is removed or just marked as expired
090   * in case that the keep data option is enabled.
091   *
092   * @see org.cache2k.CacheConfig#setKeepDataAfterExpired(boolean)
093   */
094  long getExpiredCnt();
095
096  /**
097   * An entry was evicted from the cache because of size limits.
098   */
099  long getEvictedCnt();
100
101  /**
102   * Number of calls to put().
103   */
104  long getPutCnt();
105
106  /**
107   * Number of key mutations occurred. This should be always 0, otherwise it is an indicator
108   * that the hash keys objects are modified by the application after usage within a cache
109   * request.
110   */
111  long getKeyMutationCnt();
112
113  /**
114   * Number of exceptions thrown by the {@link org.cache2k.CacheSource}.
115   */
116  long getFetchExceptionCnt();
117
118  /**
119   * Number of exceptions thrown by the CacheSource that were ignored and
120   * the previous data value got returned.
121   */
122  long getSuppressedExceptionCnt();
123
124  /**
125   * The percentage of cache accesses the cache delivered data directly instead of fetching it.
126   */
127  double getHitRate();
128
129  /**
130   * Value between 100 and 0 to help evaluate the quality of the hashing function. 100 means perfect.
131   * This metric takes into account the collision to size ratio, the longest collision size
132   * and the collision to slot ratio. The value reads 0 if the longest collision size gets more
133   * then 20.
134   */
135  int getHashQuality();
136
137  /**
138   * Number of hashcode collisions within the cache. E.g. the hashCode: 2, 3, 3, 4, 4, 4 will
139   * mean three collisions.
140   */
141  int getHashCollisionCnt();
142
143  /**
144   * Number of collision slots within the cache. E.g. the hashCode: 2, 3, 3, 4, 4, 4 will mean two
145   * collision slots.
146   */
147  int getHashCollisionsSlotCnt();
148
149  /**
150   * The number of entries of the collision slot with the most collisions. Either 0, 2 or more.
151   */
152  int getHashLongestCollisionSize();
153
154  /**
155   * Milliseconds per fetch.
156   */
157  double getMillisPerFetch();
158
159  /**
160   * Total number of time spent fetching entries from the cache source.
161   */
162  long getFetchMillis();
163
164  /**
165   * Amount of memory the cache
166   */
167  int getMemoryUsage();
168
169  /**
170   * Implementation class of the cache which controls the eviction strategy.
171   */
172  String getImplementation();
173
174  /**
175   * The cache checks some internal values for correctness. If this does not start with
176   * "0.", then please raise a bug.
177   */
178  String getIntegrityDescriptor();
179
180  /**
181   * Time of last meaningful cache operation. This is when the cache changed its
182   * structure or data was modified. Basically this means everything except a
183   * straight cache hit, that puts no effort on the cache.
184   */
185  Date getLastOperationTime();
186
187  /**
188   * Time when cache object was created.
189   */
190  Date getCreatedTime();
191
192  /**
193   * Time when cache object was cleared.
194   */
195  Date getClearedTime();
196
197  /**
198   * Time when the cache information was created for JMX. Some of the values may
199   * take processing time. The cache does not always return the latest values
200   * if the object is requested very often.
201   */
202  Date getInfoCreatedTime();
203
204  /**
205   * Milliseconds needed to provide the data.
206   */
207  int getInfoCreatedDetlaMillis();
208
209  /**
210   * Single health value from 0 meaning good, 1 meaning warning, and 2 meaning failure.
211   * Some operations may cause a warning alert level and then, after a few seconds,
212   * when everything is back to normal, reset it. A monitoring trigger, should
213   * have a delay (e.g. 30 seconds) before escalating to the operations team.
214   */
215  int getAlert();
216
217  /**
218   * String with additional statistics from the cache implementation.
219   */
220  String getExtraStatistics();
221
222}