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