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