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.Date;
027import java.util.LinkedHashMap;
028import java.util.List;
029import java.util.Map;
030
031import com.unboundid.ldap.sdk.Entry;
032import com.unboundid.util.NotMutable;
033import com.unboundid.util.StaticUtils;
034import com.unboundid.util.ThreadSafety;
035import com.unboundid.util.ThreadSafetyLevel;
036
037import static com.unboundid.ldap.sdk.unboundidds.monitors.MonitorMessages.*;
038
039
040
041/**
042 * This class defines a monitor entry that provides general information about
043 * the state of the Directory Server.  The general monitor entry is the
044 * top-level monitor entry that is generated by the monitor backend and is the
045 * parent of all monitor entries generated by the registered monitor providers.
046 * <BR>
047 * <BLOCKQUOTE>
048 *   <B>NOTE:</B>  This class, and other classes within the
049 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
050 *   supported for use against Ping Identity, UnboundID, and
051 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
052 *   for proprietary functionality or for external specifications that are not
053 *   considered stable or mature enough to be guaranteed to work in an
054 *   interoperable way with other types of LDAP servers.
055 * </BLOCKQUOTE>
056 * <BR>
057 * Information that may be included in the general monitor entry includes:
058 * <UL>
059 *   <LI>The number of connections currently established to the server.</LI>
060 *   <LI>The maximum number of connections that have been established at any one
061 *       time.</LI>
062 *   <LI>The total number of connections established to the server since
063 *       startup.</LI>
064 *   <LI>The time that the directory server was started.</LI>
065 *   <LI>The current time on the server.</LI>
066 *   <LI>The length of time in milliseconds that the server has been
067 *       online.</LI>
068 *   <LI>A user-friendly string that describes the length of time that the
069 *       server has been online.</LI>
070 *   <LI>The name of the directory server product.</LI>
071 *   <LI>The name of the vendor that provides the directory server.</LI>
072 *   <LI>The server version string.</LI>
073 *   <LI>The DNs of the configuration entries for any third-party extensions
074 *       loaded in the server.</LI>
075 * </UL>
076 * The server should present at most one general monitor entry.  It can be
077 * retrieved using the {@link MonitorManager#getGeneralMonitorEntry} method.
078 * This entry provides specific methods for accessing information about the
079 * server (e.g., the
080 * {@link GeneralMonitorEntry#getCurrentConnections} method can be used
081 * to retrieve the number of connections currently established).  Alternately,
082 * this information may be accessed using the generic API.  See the
083 * {@link MonitorManager} class documentation for an example that demonstrates
084 * the use of the generic API for accessing monitor data.
085 */
086@NotMutable()
087@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
088public final class GeneralMonitorEntry
089       extends MonitorEntry
090{
091  /**
092   * The structural object class used in general monitor entries.
093   */
094  static final String GENERAL_MONITOR_OC = "ds-general-monitor-entry";
095
096
097
098  /**
099   * The name of the attribute that contains the number of connections currently
100   * established to the server.
101   */
102  private static final String ATTR_CURRENT_CONNECTIONS = "currentConnections";
103
104
105
106  /**
107   * The name of the attribute that contains the Directory Server's current
108   * time.
109   */
110  private static final String ATTR_CURRENT_TIME = "currentTime";
111
112
113
114  /**
115   * The name of the attribute that contains the names of any alert types that
116   * have caused the server to be classified as "degraded".
117   */
118  private static final String ATTR_DEGRADED_ALERT_TYPE =
119       "degraded-alert-type";
120
121
122
123  /**
124   * The name of the attribute that contains the server instance name.
125   */
126  private static final String ATTR_INSTANCE_NAME = "instanceName";
127
128
129
130  /**
131   * The name of the attribute that contains the maximum number of concurrent
132   * client connections established since startup.
133   */
134  private static final String ATTR_MAX_CONNECTIONS = "maxConnections";
135
136
137
138  /**
139   * The name of the attribute that contains the Directory Server product name.
140   */
141  private static final String ATTR_PRODUCT_NAME = "productName";
142
143
144
145  /**
146   * The name of the attribute that contains the Directory Server start time.
147   */
148  private static final String ATTR_START_TIME = "startTime";
149
150
151
152  /**
153   * The name of the attribute that contains the Directory Server startup ID.
154   */
155  private static final String ATTR_STARTUP_ID = "startupID";
156
157
158
159  /**
160   * The name of the attribute that contains the Directory Server startup UUID.
161   */
162  private static final String ATTR_STARTUP_UUID = "startupUUID";
163
164
165
166  /**
167   * The name of the attribute that holds the DNs of the configuration entries
168   * for any third-party extensions loaded in the server.
169   */
170  private static final String ATTR_THIRD_PARTY_EXTENSION_DN =
171       "thirdPartyExtensionDN";
172
173
174
175  /**
176   * The name of the attribute that contains the total number of connections
177   * that have been established since startup.
178   */
179  private static final String ATTR_TOTAL_CONNECTIONS = "totalConnections";
180
181
182
183  /**
184   * The name of the attribute that contains the Directory Server's uptime.
185   */
186  private static final String ATTR_UP_TIME = "upTime";
187
188
189
190  /**
191   * The name of the attribute that contains the Directory Server vendor name.
192   */
193  private static final String ATTR_VENDOR_NAME = "productVendor";
194
195
196
197  /**
198   * The name of the attribute that contains the Directory Server version
199   * string.
200   */
201  private static final String ATTR_VERSION = "productVersion";
202
203
204
205  /**
206   * The name of the attribute that contains the names of any alert types that
207   * have caused the server to be classified as "unavailable".
208   */
209  private static final String ATTR_UNAVAILABLE_ALERT_TYPE =
210       "unavailable-alert-type";
211
212
213
214  /**
215   * The serial version UID for this serializable class.
216   */
217  private static final long serialVersionUID = 4262569940859462743L;
218
219
220
221  // The server's current time.
222  private final Date currentTime;
223
224  // The server's start time.
225  private final Date startTime;
226
227  // The names of the alert types that have caused the server to be classified
228  // as "degraded".
229  private final List<String> degradedAlertTypes;
230
231  // The DNs of the config entries for any third-party extensions loaded in the
232  // server.
233  private final List<String> thirdPartyExtensionDNs;
234
235  // The names of the alert types that have caused the server to be classified
236  // as "unavailable".
237  private final List<String> unavailableAlertTypes;
238
239  // The number connections currently established.
240  private final Long currentConnections;
241
242  // The maximum number connections established at any time since startup.
243  private final Long maxConnections;
244
245  // The total number of connections that have been established since startup.
246  private final Long totalConnections;
247
248  // The Directory Server instance name.
249  private final String instanceName;
250
251  // The Directory Server product name.
252  private final String productName;
253
254  // The Directory Server startup ID.
255  private final String startupID;
256
257  // The Directory Server startup UUID.
258  private final String startupUUID;
259
260  // The string representation of the uptime.
261  private final String uptime;
262
263  // The Directory Server vendor name.
264  private final String vendorName;
265
266  // The Directory Server version string.
267  private final String versionString;
268
269
270
271  /**
272   * Creates a new general monitor entry from the provided entry.
273   *
274   * @param  entry  The entry to be parsed as a general monitor entry.  It must
275   *                not be {@code null}.
276   */
277  public GeneralMonitorEntry(final Entry entry)
278  {
279    super(entry);
280
281    currentConnections     = getLong(ATTR_CURRENT_CONNECTIONS);
282    currentTime            = getDate(ATTR_CURRENT_TIME);
283    maxConnections         = getLong(ATTR_MAX_CONNECTIONS);
284    productName            = getString(ATTR_PRODUCT_NAME);
285    startTime              = getDate(ATTR_START_TIME);
286    instanceName           = getString(ATTR_INSTANCE_NAME);
287    startupID              = getString(ATTR_STARTUP_ID);
288    startupUUID            = getString(ATTR_STARTUP_UUID);
289    totalConnections       = getLong(ATTR_TOTAL_CONNECTIONS);
290    uptime                 = getString(ATTR_UP_TIME);
291    vendorName             = getString(ATTR_VENDOR_NAME);
292    versionString          = getString(ATTR_VERSION);
293    degradedAlertTypes     = getStrings(ATTR_DEGRADED_ALERT_TYPE);
294    unavailableAlertTypes  = getStrings(ATTR_UNAVAILABLE_ALERT_TYPE);
295    thirdPartyExtensionDNs = getStrings(ATTR_THIRD_PARTY_EXTENSION_DN);
296  }
297
298
299
300  /**
301   * Retrieves the number of connections currently established.
302   *
303   * @return  The number of connections currently established, or {@code null}
304   *          if it was not included in the monitor entry.
305   */
306  public Long getCurrentConnections()
307  {
308    return currentConnections;
309  }
310
311
312
313  /**
314   * Retrieves the maximum number of concurrent connections established at any
315   * time since startup.
316   *
317   * @return  The maximum number of concurrent connections established at any
318   *          time since startup, or {@code null} if it was not included in the
319   *          monitor entry.
320   */
321  public Long getMaxConnections()
322  {
323    return maxConnections;
324  }
325
326
327
328  /**
329   * Retrieves the total number of connections established since startup.
330   *
331   * @return  The total number of connections established since startup, or
332   *          {@code null} if it was not included in the monitor entry.
333   */
334  public Long getTotalConnections()
335  {
336    return totalConnections;
337  }
338
339
340
341  /**
342   * Retrieves the current time as reported by the Directory Server.
343   *
344   * @return  The current time as reported by the Directory Server, or
345   *          {@code null} if it was not included in the monitor entry.
346   */
347  public Date getCurrentTime()
348  {
349    return currentTime;
350  }
351
352
353
354  /**
355   * Retrieves the time that the Directory Server was started.
356   *
357   * @return  The time that the Directory Server was started, or {@code null} if
358   *          it was not included in the monitor entry.
359   */
360  public Date getStartTime()
361  {
362    return startTime;
363  }
364
365
366
367  /**
368   * Retrieves the name assigned to the Directory Server instance.
369   *
370   * @return  The name assigned to the Directory Server instance, or
371   *          {@code null} if it was not included in the monitor entry.
372   */
373  public String getInstanceName()
374  {
375    return instanceName;
376  }
377
378
379
380  /**
381   * Retrieves a relatively compact identifier generated at the time the
382   * Directory Server was started.
383   *
384   * @return  A relatively compact identifier generated at the time the
385   *          Directory Server was started, or {@code null} if it was not
386   *          included in the monitor entry.
387   */
388  public String getStartupID()
389  {
390    return startupID;
391  }
392
393
394
395  /**
396   * Retrieves the UUID that was generated when the Directory Server was
397   * started.
398   *
399   * @return  The UUID that was generated when the Directory Server was started,
400   *          or {@code null} if it was not included in the monitor entry.
401   */
402  public String getStartupUUID()
403  {
404    return startupUUID;
405  }
406
407
408
409  /**
410   * Retrieves the Directory Server uptime in milliseconds.
411   *
412   * @return  The Directory Server uptime in milliseconds, or {@code null} if
413   *          either the current time or the start time was not available.
414   */
415  public Long getUptimeMillis()
416  {
417    if ((currentTime == null) || (startTime == null))
418    {
419      return null;
420    }
421
422    return currentTime.getTime() - startTime.getTime();
423  }
424
425
426
427  /**
428   * Retrieves the human-readable string representation of the Directory Server
429   * uptime.
430   *
431   * @return  The human-readable string representation of the Directory Server
432   *          uptime, or {@code null} if it was not included in the monitor
433   *          entry.
434   */
435  public String getUptimeString()
436  {
437    return uptime;
438  }
439
440
441
442  /**
443   * Retrieves the Directory Server product name.
444   *
445   * @return  The Directory Serve product name, or {@code null} if it was not
446   *          included in the monitor entry.
447   */
448  public String getProductName()
449  {
450    return productName;
451  }
452
453
454
455  /**
456   * Retrieves the Directory Server vendor name string.
457   *
458   * @return  The Directory Server vendor name string, or {@code null} if it
459   *          was not included in the monitor entry.
460   */
461  public String getVendorName()
462  {
463    return vendorName;
464  }
465
466
467
468  /**
469   * Retrieves the Directory Server version string.
470   *
471   * @return  The Directory Server version string, or {@code null} if it was not
472   *          included in the monitor entry.
473   */
474  public String getVersionString()
475  {
476    return versionString;
477  }
478
479
480
481  /**
482   * Retrieves the names of any alert types which may have caused the server to
483   * be currently classified as "degraded".
484   *
485   * @return  The names of any alert types which may have caused the server to
486   *          be currently classified as "degraded", or an empty list if it was
487   *          not included in the monitor entry (which likely indicates that the
488   *          server is not classified as "degraded").
489   */
490  public List<String> getDegradedAlertTypes()
491  {
492    return degradedAlertTypes;
493  }
494
495
496
497  /**
498   * Retrieves the names of any alert types which may have caused the server to
499   * be currently classified as "unavailable".
500   *
501   * @return  The names of any alert types which may have caused the server to
502   *          be currently classified as "unavailable", or an empty list if it
503   *          was not included in the monitor entry (which likely indicates that
504   *          the server is not classified as "unavailable").
505   */
506  public List<String> getUnavailableAlertTypes()
507  {
508    return unavailableAlertTypes;
509  }
510
511
512
513  /**
514   * Retrieves the DNs of the configuration entries for any third-party
515   * extensions currently loaded in the server.
516   *
517   * @return  The DNs of the configuration entries for any third-party
518   *          extensions currently loaded in the server, or an empty list if it
519   *          was not included in the monitor entry.
520   */
521  public List<String> getThirdPartyExtensionDNs()
522  {
523    return thirdPartyExtensionDNs;
524  }
525
526
527
528  /**
529   * {@inheritDoc}
530   */
531  @Override()
532  public String getMonitorDisplayName()
533  {
534    return INFO_GENERAL_MONITOR_DISPNAME.get();
535  }
536
537
538
539  /**
540   * {@inheritDoc}
541   */
542  @Override()
543  public String getMonitorDescription()
544  {
545    return INFO_GENERAL_MONITOR_DESC.get();
546  }
547
548
549
550  /**
551   * {@inheritDoc}
552   */
553  @Override()
554  public Map<String,MonitorAttribute> getMonitorAttributes()
555  {
556    final LinkedHashMap<String,MonitorAttribute> attrs =
557         new LinkedHashMap<>(StaticUtils.computeMapCapacity(30));
558
559    if (productName != null)
560    {
561      addMonitorAttribute(attrs,
562           ATTR_PRODUCT_NAME,
563           INFO_GENERAL_DISPNAME_PRODUCT_NAME.get(),
564           INFO_GENERAL_DESC_PRODUCT_NAME.get(),
565           productName);
566    }
567
568    if (vendorName != null)
569    {
570      addMonitorAttribute(attrs,
571           ATTR_VENDOR_NAME,
572           INFO_GENERAL_DISPNAME_VENDOR_NAME.get(),
573           INFO_GENERAL_DESC_VENDOR_NAME.get(),
574           vendorName);
575    }
576
577    if (versionString != null)
578    {
579      addMonitorAttribute(attrs,
580           ATTR_VERSION,
581           INFO_GENERAL_DISPNAME_VERSION.get(),
582           INFO_GENERAL_DESC_VERSION.get(),
583           versionString);
584    }
585
586    if (instanceName != null)
587    {
588      addMonitorAttribute(attrs,
589           ATTR_INSTANCE_NAME,
590           INFO_GENERAL_DISPNAME_INSTANCE_NAME.get(),
591           INFO_GENERAL_DESC_INSTANCE_NAME.get(),
592           instanceName);
593    }
594
595    if (startTime != null)
596    {
597      addMonitorAttribute(attrs,
598           ATTR_START_TIME,
599           INFO_GENERAL_DISPNAME_START_TIME.get(),
600           INFO_GENERAL_DESC_START_TIME.get(),
601           startTime);
602    }
603
604    if (startupID != null)
605    {
606      addMonitorAttribute(attrs,
607           ATTR_STARTUP_ID,
608           INFO_GENERAL_DISPNAME_STARTUP_ID.get(),
609           INFO_GENERAL_DESC_STARTUP_ID.get(),
610           startupID);
611    }
612
613    if (startupUUID != null)
614    {
615      addMonitorAttribute(attrs,
616           ATTR_STARTUP_UUID,
617           INFO_GENERAL_DISPNAME_STARTUP_UUID.get(),
618           INFO_GENERAL_DESC_STARTUP_UUID.get(),
619           startupUUID);
620    }
621
622    if (currentTime != null)
623    {
624      addMonitorAttribute(attrs,
625           ATTR_CURRENT_TIME,
626           INFO_GENERAL_DISPNAME_CURRENT_TIME.get(),
627           INFO_GENERAL_DESC_CURRENT_TIME.get(),
628           currentTime);
629    }
630
631    if (uptime != null)
632    {
633      addMonitorAttribute(attrs,
634           ATTR_UP_TIME,
635           INFO_GENERAL_DISPNAME_UPTIME.get(),
636           INFO_GENERAL_DESC_UPTIME.get(),
637           uptime);
638    }
639
640    if ((startTime != null) && (currentTime != null))
641    {
642      addMonitorAttribute(attrs,
643           "upTimeMillis",
644           INFO_GENERAL_DISPNAME_UPTIME_MILLIS.get(),
645           INFO_GENERAL_DESC_UPTIME_MILLIS.get(),
646           Long.valueOf(currentTime.getTime() - startTime.getTime()));
647    }
648
649    if (currentConnections != null)
650    {
651      addMonitorAttribute(attrs,
652           ATTR_CURRENT_CONNECTIONS,
653           INFO_GENERAL_DISPNAME_CURRENT_CONNECTIONS.get(),
654           INFO_GENERAL_DESC_CURRENT_CONNECTIONS.get(),
655           currentConnections);
656    }
657
658    if (maxConnections != null)
659    {
660      addMonitorAttribute(attrs,
661           ATTR_MAX_CONNECTIONS,
662           INFO_GENERAL_DISPNAME_MAX_CONNECTIONS.get(),
663           INFO_GENERAL_DESC_MAX_CONNECTIONS.get(),
664           maxConnections);
665    }
666
667    if (totalConnections != null)
668    {
669      addMonitorAttribute(attrs,
670           ATTR_TOTAL_CONNECTIONS,
671           INFO_GENERAL_DISPNAME_TOTAL_CONNECTIONS.get(),
672           INFO_GENERAL_DESC_TOTAL_CONNECTIONS.get(),
673           totalConnections);
674    }
675
676    if (! degradedAlertTypes.isEmpty())
677    {
678      addMonitorAttribute(attrs,
679           ATTR_DEGRADED_ALERT_TYPE,
680           INFO_GENERAL_DISPNAME_DEGRADED_ALERT_TYPE.get(),
681           INFO_GENERAL_DESC_DEGRADED_ALERT_TYPE.get(),
682           degradedAlertTypes);
683    }
684
685    if (! unavailableAlertTypes.isEmpty())
686    {
687      addMonitorAttribute(attrs,
688           ATTR_UNAVAILABLE_ALERT_TYPE,
689           INFO_GENERAL_DISPNAME_UNAVAILABLE_ALERT_TYPE.get(),
690           INFO_GENERAL_DESC_UNAVAILABLE_ALERT_TYPE.get(),
691           unavailableAlertTypes);
692    }
693
694    if (! thirdPartyExtensionDNs.isEmpty())
695    {
696      addMonitorAttribute(attrs,
697           ATTR_THIRD_PARTY_EXTENSION_DN,
698           INFO_GENERAL_DISPNAME_THIRD_PARTY_EXTENSION_DN.get(),
699           INFO_GENERAL_DESC_THIRD_PARTY_EXTENSION_DN.get(),
700           thirdPartyExtensionDNs);
701    }
702
703    return Collections.unmodifiableMap(attrs);
704  }
705}