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