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    }