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}