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}