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 Alcatel-Lucent 8661 046 * server products. These classes provide support for proprietary 047 * functionality or for external specifications that are not considered stable 048 * or mature enough to be guaranteed to work in an interoperable way with 049 * 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<String,MonitorAttribute>(); 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}