001 /*
002 * Copyright 2008-2015 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2015 UnboundID Corp.
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021 package com.unboundid.ldap.sdk.unboundidds.monitors;
022
023
024
025 import java.util.Collections;
026 import java.util.LinkedHashMap;
027 import java.util.Map;
028
029 import com.unboundid.ldap.sdk.Entry;
030 import com.unboundid.util.NotMutable;
031 import com.unboundid.util.ThreadSafety;
032 import com.unboundid.util.ThreadSafetyLevel;
033
034 import static com.unboundid.ldap.sdk.unboundidds.monitors.MonitorMessages.*;
035
036
037
038 /**
039 * <BLOCKQUOTE>
040 * <B>NOTE:</B> This class is part of the Commercial Edition of the UnboundID
041 * LDAP SDK for Java. It is not available for use in applications that
042 * include only the Standard Edition of the LDAP SDK, and is not supported for
043 * use in conjunction with non-UnboundID products.
044 * </BLOCKQUOTE>
045 * This class defines a monitor entry that provides general information about
046 * the state of the Directory Server entry cache. The information that may be
047 * available in the entry cache monitor entry includes:
048 * <UL>
049 * <LI>The number of cache tries, which are attempts to retrieve entries from
050 * the cache.</LI>
051 * <LI>The number of cache hits, which are successful attempts to retrieve an
052 * entry from the cache.</LI>
053 * <LI>The number of cache misses, which are unsuccessful attempts to retrieve
054 * an entry from the cache.</LI>
055 * <LI>The cache hit ratio, which is the ratio of the time that a cache try is
056 * successful.</LI>
057 * <LI>The number of entries currently held in the cache.</LI>
058 * <LI>The maximum number of entries that may be held in the cache.</LI>
059 * <LI>The approximate current amount of memory consumed by the cache.</LI>
060 * <LI>The maximum amount of memory that may be consumed by the cache.</LI>
061 * </UL>
062 * The server should present at most one client connection monitor entry. It
063 * can be retrieved using the
064 * {@link MonitorManager#getEntryCacheMonitorEntry} method. This entry provides
065 * specific methods for accessing information about the entry cache (e.g., the
066 * {@link EntryCacheMonitorEntry#getCurrentCount} method can be used
067 * to retrieve the number of entries currently in the cache). Alternately, this
068 * information may be accessed using the generic API. See the
069 * {@link MonitorManager} class documentation for an example that demonstrates
070 * the use of the generic API for accessing monitor data.
071 */
072 @NotMutable()
073 @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
074 public final class EntryCacheMonitorEntry
075 extends MonitorEntry
076 {
077 /**
078 * The structural object class used in entry cache monitor entries.
079 */
080 static final String ENTRY_CACHE_MONITOR_OC =
081 "ds-entry-cache-monitor-entry";
082
083
084
085 /**
086 * The name of the attribute that provides the number of entries currently
087 * held in the cache.
088 */
089 private static final String ATTR_CURRENT_COUNT = "currentEntryCacheCount";
090
091
092
093 /**
094 * The name of the attribute that provides the current entry cache size in
095 * bytes.
096 */
097 private static final String ATTR_CURRENT_SIZE = "currentEntryCacheSize";
098
099
100
101 /**
102 * The name of the attribute that provides the entry cache hit ratio.
103 */
104 private static final String ATTR_HIT_RATIO = "entryCacheHitRatio";
105
106
107
108 /**
109 * The name of the attribute that provides the number of cache hits.
110 */
111 private static final String ATTR_HITS = "entryCacheHits";
112
113
114
115 /**
116 * The name of the attribute that provides the maximum number of entries that
117 * may be held in the cache.
118 */
119 private static final String ATTR_MAX_COUNT = "maxEntryCacheCount";
120
121
122
123 /**
124 * The name of the attribute that provides the maximum entry cache size in
125 * bytes.
126 */
127 private static final String ATTR_MAX_SIZE = "maxEntryCacheSize";
128
129
130
131 /**
132 * The name of the attribute that provides the number of cache tries.
133 */
134 private static final String ATTR_TRIES = "entryCacheTries";
135
136
137
138 /**
139 * The serial version UID for this serializable class.
140 */
141 private static final long serialVersionUID = 2468261007112908567L;
142
143
144
145 // The hit ratio.
146 private final Double hitRatio;
147
148 // The number of cache hits.
149 private final Long cacheHits;
150
151 // The number of cache misses.
152 private final Long cacheMisses;
153
154 // The number of cache tries.
155 private final Long cacheTries;
156
157 // The current number of entries in the cache.
158 private final Long currentCount;
159
160 // The current size of the cache.
161 private final Long currentSize;
162
163 // The maximum number of entries in the cache.
164 private final Long maxCount;
165
166 // The maximum size of the cache.
167 private final Long maxSize;
168
169
170
171 /**
172 * Creates a new entry cache monitor entry from the provided entry.
173 *
174 * @param entry The entry to be parsed as an entry cache monitor entry. It
175 * must not be {@code null}.
176 */
177 public EntryCacheMonitorEntry(final Entry entry)
178 {
179 super(entry);
180
181 cacheHits = getLong(ATTR_HITS);
182 cacheTries = getLong(ATTR_TRIES);
183 hitRatio = getDouble(ATTR_HIT_RATIO);
184 currentCount = getLong(ATTR_CURRENT_COUNT);
185 maxCount = getLong(ATTR_MAX_COUNT);
186 currentSize = getLong(ATTR_CURRENT_SIZE);
187 maxSize = getLong(ATTR_MAX_SIZE);
188
189 if ((cacheHits == null) || (cacheTries == null))
190 {
191 cacheMisses = null;
192 }
193 else
194 {
195 cacheMisses = cacheTries - cacheHits;
196 }
197 }
198
199
200
201 /**
202 * Retrieves the number of attempts to find an entry in the cache.
203 *
204 * @return The number of attempts to find an entry in the cache, or
205 * {@code null} if it was not included in the monitor entry.
206 */
207 public Long getCacheTries()
208 {
209 return cacheTries;
210 }
211
212
213
214 /**
215 * Retrieves the number of attempts to find an entry in the cache in which the
216 * entry was found.
217 *
218 * @return The number of attempts to find an entry in the cache in which the
219 * entry was found, or {@code null} if it was not included in the
220 * monitor entry.
221 */
222 public Long getCacheHits()
223 {
224 return cacheHits;
225 }
226
227
228
229 /**
230 * Retrieves the number of attempts to find an entry in the cache in which the
231 * entry was not found.
232 *
233 * @return The number of attempts to find an entry in the cache in which the
234 * entry was not found, or {@code null} if it was not included in the
235 * monitor entry.
236 */
237 public Long getCacheMisses()
238 {
239 return cacheMisses;
240 }
241
242
243
244 /**
245 * Retrieves the ratio of the time a requested entry was found in the cache.
246 *
247 * @return The ratio of the time a requested entry was found in the cache, or
248 * {@code null} if it was not included in the monitor entry.
249 */
250 public Double getCacheHitRatio()
251 {
252 return hitRatio;
253 }
254
255
256
257 /**
258 * Retrieves the number of entries currently held in the entry cache.
259 *
260 * @return The number of entries currently held in the entry cache, or
261 * {@code null} if it was not included in the monitor entry.
262 */
263 public Long getCurrentCount()
264 {
265 return currentCount;
266 }
267
268
269
270 /**
271 * Retrieves the maximum number of entries that may be held in the entry
272 * cache.
273 *
274 * @return The maximum number of entries that may be held in the entry cache,
275 * or {@code null} if it was not included in the monitor entry.
276 */
277 public Long getMaxCount()
278 {
279 return maxCount;
280 }
281
282
283
284 /**
285 * Retrieves the current amount of memory (in bytes) consumed by the entry
286 * cache.
287 *
288 * @return The current amount of memory (in bytes) consumed by the entry
289 * cache, or {@code null} if it was not included in the monitor
290 * entry.
291 */
292 public Long getCurrentCacheSize()
293 {
294 return currentSize;
295 }
296
297
298
299 /**
300 * Retrieves the maximum amount of memory (in bytes) that may be consumed by
301 * the entry cache.
302 *
303 * @return The maximum amount of memory (in bytes) that may be consumed by
304 * the entry cache, or {@code null} if it was not included in the
305 * monitor entry.
306 */
307 public Long getMaxCacheSize()
308 {
309 return maxSize;
310 }
311
312
313
314 /**
315 * {@inheritDoc}
316 */
317 @Override()
318 public String getMonitorDisplayName()
319 {
320 return INFO_ENTRY_CACHE_MONITOR_DISPNAME.get();
321 }
322
323
324
325 /**
326 * {@inheritDoc}
327 */
328 @Override()
329 public String getMonitorDescription()
330 {
331 return INFO_ENTRY_CACHE_MONITOR_DESC.get();
332 }
333
334
335
336 /**
337 * {@inheritDoc}
338 */
339 @Override()
340 public Map<String,MonitorAttribute> getMonitorAttributes()
341 {
342 final LinkedHashMap<String,MonitorAttribute> attrs =
343 new LinkedHashMap<String,MonitorAttribute>();
344
345 if (cacheTries != null)
346 {
347 addMonitorAttribute(attrs,
348 ATTR_TRIES,
349 INFO_ENTRY_CACHE_DISPNAME_TRIES.get(),
350 INFO_ENTRY_CACHE_DESC_TRIES.get(),
351 cacheTries);
352 }
353
354 if (cacheHits != null)
355 {
356 addMonitorAttribute(attrs,
357 ATTR_HITS,
358 INFO_ENTRY_CACHE_DISPNAME_HITS.get(),
359 INFO_ENTRY_CACHE_DESC_HITS.get(),
360 cacheHits);
361 }
362
363 if (cacheMisses != null)
364 {
365 addMonitorAttribute(attrs,
366 "entryCacheMisses",
367 INFO_ENTRY_CACHE_DISPNAME_MISSES.get(),
368 INFO_ENTRY_CACHE_DESC_MISSES.get(),
369 cacheMisses);
370 }
371
372 if (hitRatio != null)
373 {
374 addMonitorAttribute(attrs,
375 ATTR_HIT_RATIO,
376 INFO_ENTRY_CACHE_DISPNAME_HIT_RATIO.get(),
377 INFO_ENTRY_CACHE_DESC_HIT_RATIO.get(),
378 hitRatio);
379 }
380
381 if (currentCount != null)
382 {
383 addMonitorAttribute(attrs,
384 ATTR_CURRENT_COUNT,
385 INFO_ENTRY_CACHE_DISPNAME_CURRENT_COUNT.get(),
386 INFO_ENTRY_CACHE_DESC_CURRENT_COUNT.get(),
387 currentCount);
388 }
389
390 if (maxCount != null)
391 {
392 addMonitorAttribute(attrs,
393 ATTR_MAX_COUNT,
394 INFO_ENTRY_CACHE_DISPNAME_MAX_COUNT.get(),
395 INFO_ENTRY_CACHE_DESC_MAX_COUNT.get(),
396 maxCount);
397 }
398
399 if (currentSize != null)
400 {
401 addMonitorAttribute(attrs,
402 ATTR_CURRENT_SIZE,
403 INFO_ENTRY_CACHE_DISPNAME_CURRENT_SIZE.get(),
404 INFO_ENTRY_CACHE_DESC_CURRENT_SIZE.get(),
405 currentSize);
406 }
407
408 if (maxSize != null)
409 {
410 addMonitorAttribute(attrs,
411 ATTR_MAX_SIZE,
412 INFO_ENTRY_CACHE_DISPNAME_MAX_SIZE.get(),
413 INFO_ENTRY_CACHE_DESC_MAX_SIZE.get(),
414 maxSize);
415 }
416
417 return Collections.unmodifiableMap(attrs);
418 }
419 }