001/*
002 * Copyright 2014-2024 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2014-2024 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) 2014-2024 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.NotNull;
047import com.unboundid.util.Nullable;
048import com.unboundid.util.StaticUtils;
049import com.unboundid.util.ThreadSafety;
050import com.unboundid.util.ThreadSafetyLevel;
051
052import static com.unboundid.ldap.sdk.unboundidds.monitors.MonitorMessages.*;
053
054
055
056/**
057 * This class defines a monitor entry that provides information about the group
058 * cache and the number and types of groups available in the server.
059 * <BR>
060 * <BLOCKQUOTE>
061 *   <B>NOTE:</B>  This class, and other classes within the
062 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
063 *   supported for use against Ping Identity, UnboundID, and
064 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
065 *   for proprietary functionality or for external specifications that are not
066 *   considered stable or mature enough to be guaranteed to work in an
067 *   interoperable way with other types of LDAP servers.
068 * </BLOCKQUOTE>
069 */
070@NotMutable()
071@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
072public final class GroupCacheMonitorEntry
073       extends MonitorEntry
074{
075  /**
076   * The structural object class used in group cache monitor entries.
077   */
078  @NotNull static final String GROUP_CACHE_MONITOR_OC =
079       "ds-group-cache-monitor-entry";
080
081
082
083  /**
084   * The name of the attribute that contains information about the amount of
085   * memory required by the group cache, in bytes.
086   */
087  @NotNull private static final String ATTR_CURRENT_CACHE_USED_BYTES =
088       "current-cache-used-bytes";
089
090
091
092  /**
093   * The name of the attribute that contains information about the amount of
094   * memory required by the group cache, as a percentage of the total JVM heap
095   * size.
096   */
097  @NotNull private static final String ATTR_CURRENT_CACHE_USED_PERCENT =
098       "current-cache-used-as-percentage-of-max-heap";
099
100
101
102  /**
103   * The name of the attribute that contains information about the length of
104   * time required to determine group cache memory usage.
105   */
106  @NotNull private static final String ATTR_CURRENT_CACHE_USED_UPDATE_MILLIS =
107       "current-cache-used-update-ms";
108
109
110
111  /**
112   * The name of the attribute that contains information about the number of
113   * dynamic group entries defined in the server.
114   */
115  @NotNull private static final String ATTR_DYNAMIC_GROUP_ENTRIES =
116       "dynamic-group-entries";
117
118
119
120  /**
121   * The name of the attribute that contains information about the number of
122   * static group entries defined in the server.
123   */
124  @NotNull private static final String ATTR_STATIC_GROUP_ENTRIES =
125       "static-group-entries";
126
127
128
129  /**
130   * The name of the attribute that contains information about the total number
131   * of static group members defined in the server.
132   */
133  @NotNull private static final String ATTR_TOTAL_STATIC_GROUP_MEMBERS =
134       "static-group-members";
135
136
137
138  /**
139   * The name of the attribute that contains information about the number of
140   * unique static group members defined in the server.
141   */
142  @NotNull private static final String ATTR_UNIQUE_STATIC_GROUP_MEMBERS =
143       "static-group-unique-members";
144
145
146
147  /**
148   * The name of the attribute that contains information about the number of
149   * virtual static group entries defined in the server.
150   */
151  @NotNull private static final String ATTR_VIRTUAL_STATIC_GROUP_ENTRIES =
152       "virtual-static-group-entries";
153
154
155
156  /**
157   * The serial version UID for this serializable class.
158   */
159  private static final long serialVersionUID = -5665905374595185773L;
160
161
162
163  // The length of time in milliseconds required to determine the current cache
164  // usage.
165  @Nullable private final Double currentCacheUsedUpdateMillis;
166
167  // The percentage of the JVM heap used by the group cache.
168  @Nullable private final Integer currentCacheUsedPercent;
169
170  // The amount of memory (in bytes) currently in use by the group cache.
171  @Nullable private final Long currentCacheUsedBytes;
172
173  // The number of dynamic group entries defined in the server.
174  @Nullable private final Long dynamicGroupEntries;
175
176  // The number of static group entries defined in the server.
177  @Nullable private final Long staticGroupEntries;
178
179  // The number of total static group members defined in the server.
180  @Nullable private final Long staticGroupMembers;
181
182  // The number of unique static group members defined in the server.
183  @Nullable private final Long staticGroupUniqueMembers;
184
185  // The number of virtual static group entries defined in the server.
186  @Nullable private final Long virtualStaticGroupEntries;
187
188
189
190  /**
191   * Creates a new group cache monitor entry from the provided entry.
192   *
193   * @param  entry  The entry to be parsed as a group cache monitor entry.  It
194   *                must not be {@code null}.
195   */
196  public GroupCacheMonitorEntry(@NotNull final Entry entry)
197  {
198    super(entry);
199
200    staticGroupEntries = getLong(ATTR_STATIC_GROUP_ENTRIES);
201    staticGroupMembers = getLong(ATTR_TOTAL_STATIC_GROUP_MEMBERS);
202    staticGroupUniqueMembers = getLong(ATTR_UNIQUE_STATIC_GROUP_MEMBERS);
203    dynamicGroupEntries = getLong(ATTR_DYNAMIC_GROUP_ENTRIES);
204    virtualStaticGroupEntries = getLong(ATTR_VIRTUAL_STATIC_GROUP_ENTRIES);
205    currentCacheUsedBytes = getLong(ATTR_CURRENT_CACHE_USED_BYTES);
206    currentCacheUsedPercent = getInteger(ATTR_CURRENT_CACHE_USED_PERCENT);
207    currentCacheUsedUpdateMillis =
208         getDouble(ATTR_CURRENT_CACHE_USED_UPDATE_MILLIS);
209  }
210
211
212
213  /**
214   * Retrieves the number of static group entries defined in the server, if
215   * available.
216   *
217   * @return  The number of static group entries defined in the server, or
218   *          {@code null} if it was not included in the monitor entry.
219   */
220  @Nullable()
221  public Long getStaticGroupEntries()
222  {
223    return staticGroupEntries;
224  }
225
226
227
228  /**
229   * Retrieves the total number of static group members defined in the server,
230   * if available.  Users that are members of multiple static groups will be
231   * counted multiple times.
232   *
233   * @return  The total number of static group members defined in the server, or
234   *          {@code null} if it was not included in the monitor entry.
235   */
236  @Nullable()
237  public Long getTotalStaticGroupMembers()
238  {
239    return staticGroupMembers;
240  }
241
242
243
244  /**
245   * Retrieves the number of unique static group members defined in the server,
246   * if available.  Users that are members of multiple static groups will only
247   * be counted once.
248   *
249   * @return  The number of unique static group members defined in the server,
250   *          or {@code null} if it was not included in the monitor entry.
251   */
252  @Nullable()
253  public Long getUniqueStaticGroupMembers()
254  {
255    return staticGroupUniqueMembers;
256  }
257
258
259
260  /**
261   * Retrieves the number of dynamic group entries defined in the server, if
262   * available.
263   *
264   * @return  The number of dynamic group entries defined in the server, or
265   *          {@code null} if it was not included in the monitor entry.
266   */
267  @Nullable()
268  public Long getDynamicGroupEntries()
269  {
270    return dynamicGroupEntries;
271  }
272
273
274
275  /**
276   * Retrieves the number of virtual static group entries defined in the server,
277   * if available.
278   *
279   * @return  The number of virtual static group entries defined in the server,
280   *          or {@code null} if it was not included in the monitor entry.
281   */
282  @Nullable()
283  public Long getVirtualStaticGroupEntries()
284  {
285    return virtualStaticGroupEntries;
286  }
287
288
289
290  /**
291   * Retrieves the amount of memory in bytes used by the group cache, if
292   * available.
293   *
294   * @return  The amount of memory in bytes used by the group cache, or
295   *          {@code null} if it was not included in the monitor entry.
296   */
297  @Nullable()
298  public Long getCurrentCacheUsedBytes()
299  {
300    return currentCacheUsedBytes;
301  }
302
303
304
305  /**
306   * Retrieves the amount of memory used by the group cache as a percentage of
307   * the maximum heap size, if available.
308   *
309   * @return  The amount of memory in bytes used by the group cache, or
310   *          {@code null} if it was not included in the monitor entry.
311   */
312  @Nullable()
313  public Integer getCurrentCacheUsedAsPercentOfMaxHeap()
314  {
315    return currentCacheUsedPercent;
316  }
317
318
319
320  /**
321   * Retrieves the length of time in milliseconds required to compute the group
322   * cache size, if available.
323   *
324   * @return  The length of time in milliseconds required to compute the group
325   *          cache size, or {@code null} if it was not included in the monitor
326   *          entry.
327   */
328  @Nullable()
329  public Double getCurrentCacheUsedUpdateDurationMillis()
330  {
331    return currentCacheUsedUpdateMillis;
332  }
333
334
335
336  /**
337   * {@inheritDoc}
338   */
339  @Override()
340  @NotNull()
341  public String getMonitorDisplayName()
342  {
343    return INFO_GROUP_CACHE_MONITOR_DISPNAME.get();
344  }
345
346
347
348  /**
349   * {@inheritDoc}
350   */
351  @Override()
352  @NotNull()
353  public String getMonitorDescription()
354  {
355    return INFO_GROUP_CACHE_MONITOR_DESC.get();
356  }
357
358
359
360  /**
361   * {@inheritDoc}
362   */
363  @Override()
364  @NotNull()
365  public Map<String,MonitorAttribute> getMonitorAttributes()
366  {
367    final LinkedHashMap<String,MonitorAttribute> attrs =
368         new LinkedHashMap<>(StaticUtils.computeMapCapacity(8));
369
370    if (staticGroupEntries != null)
371    {
372      addMonitorAttribute(attrs,
373           ATTR_STATIC_GROUP_ENTRIES,
374           INFO_GROUP_CACHE_DISPNAME_STATIC_GROUP_ENTRIES.get(),
375           INFO_GROUP_CACHE_DESC_STATIC_GROUP_ENTRIES.get(),
376           staticGroupEntries);
377    }
378
379    if (staticGroupMembers != null)
380    {
381      addMonitorAttribute(attrs,
382           ATTR_TOTAL_STATIC_GROUP_MEMBERS,
383           INFO_GROUP_CACHE_DISPNAME_STATIC_GROUP_MEMBERS.get(),
384           INFO_GROUP_CACHE_DESC_STATIC_GROUP_MEMBERS.get(),
385           staticGroupMembers);
386    }
387
388    if (staticGroupUniqueMembers != null)
389    {
390      addMonitorAttribute(attrs,
391           ATTR_UNIQUE_STATIC_GROUP_MEMBERS,
392           INFO_GROUP_CACHE_DISPNAME_STATIC_GROUP_UNIQUE_MEMBERS.get(),
393           INFO_GROUP_CACHE_DESC_STATIC_GROUP_UNIQUE_MEMBERS.get(),
394           staticGroupUniqueMembers);
395    }
396
397    if (dynamicGroupEntries != null)
398    {
399      addMonitorAttribute(attrs,
400           ATTR_DYNAMIC_GROUP_ENTRIES,
401           INFO_GROUP_CACHE_DISPNAME_DYNAMIC_GROUP_ENTRIES.get(),
402           INFO_GROUP_CACHE_DESC_DYNAMIC_GROUP_ENTRIES.get(),
403           dynamicGroupEntries);
404    }
405
406    if (virtualStaticGroupEntries != null)
407    {
408      addMonitorAttribute(attrs,
409           ATTR_VIRTUAL_STATIC_GROUP_ENTRIES,
410           INFO_GROUP_CACHE_DISPNAME_VIRTUAL_STATIC_GROUP_ENTRIES.get(),
411           INFO_GROUP_CACHE_DESC_VIRTUAL_STATIC_GROUP_ENTRIES.get(),
412           virtualStaticGroupEntries);
413    }
414
415    if (currentCacheUsedBytes != null)
416    {
417      addMonitorAttribute(attrs,
418           ATTR_CURRENT_CACHE_USED_BYTES,
419           INFO_GROUP_CACHE_DISPNAME_CACHE_SIZE_BYTES.get(),
420           INFO_GROUP_CACHE_DESC_CACHE_SIZE_BYTES.get(),
421           currentCacheUsedBytes);
422    }
423
424    if (currentCacheUsedPercent != null)
425    {
426      addMonitorAttribute(attrs,
427           ATTR_CURRENT_CACHE_USED_PERCENT,
428           INFO_GROUP_CACHE_DISPNAME_CACHE_SIZE_PERCENT.get(),
429           INFO_GROUP_CACHE_DESC_CACHE_SIZE_PERCENT.get(),
430           currentCacheUsedPercent);
431    }
432
433    if (currentCacheUsedUpdateMillis != null)
434    {
435      addMonitorAttribute(attrs,
436           ATTR_CURRENT_CACHE_USED_UPDATE_MILLIS,
437           INFO_GROUP_CACHE_DISPNAME_CACHE_SIZE_UPDATE_MILLIS.get(),
438           INFO_GROUP_CACHE_DESC_CACHE_SIZE_UPDATE_MILLIS.get(),
439           currentCacheUsedUpdateMillis);
440    }
441
442    return Collections.unmodifiableMap(attrs);
443  }
444}