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