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 information about the state
041 * of the traditional work queue.  For all practical purposes, the traditional
042 * work queue has been replaced by the UnboundID Work Queue, which is the
043 * default work queue implementation (which exposes its own monitor information
044 * that can be accessed using the {@link UnboundIDWorkQueueMonitorEntry}).
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 * In the event that the traditional work queue is configured for use instead of
057 * the UnboundID work queue, then this monitor entry may be used to access the
058 * information that it provides, which may include:
059 * <UL>
060 *   <LI>The total number of requests submitted to the work queue.</LI>
061 *   <LI>The number of requests that were rejected because the work queue was
062 *       already at its maximum capacity.</LI>
063 *   <LI>The number of operations currently held in the work queue waiting to be
064 *       picked for processing by a worker thread.</LI>
065 *   <LI>The average number of operations held in the work queue since startup
066 *       as observed from periodic polling.</LI>
067 *   <LI>The maximum number of operations held in the work queue at any time
068 *       since startup as observed from periodic polling.</LI>
069 * </UL>
070 * The server should present at most one traditional work queue monitor entry.
071 * It can be retrieved using the
072 * {@link MonitorManager#getTraditionalWorkQueueMonitorEntry} method.  This
073 * entry provides specific methods for accessing information about the state of
074 * the work queue (e.g., the
075 * {@link TraditionalWorkQueueMonitorEntry#getCurrentBacklog} method may be used
076 * to retrieve the number of operations currently held in the work queue).
077 * Alternately, this information may be accessed using the generic API.  See the
078 * {@link MonitorManager} class documentation for an example that demonstrates
079 * the use of the generic API for accessing monitor data.
080 */
081@NotMutable()
082@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
083public final class TraditionalWorkQueueMonitorEntry
084       extends MonitorEntry
085{
086  /**
087   * The structural object class used in LDAP statistics monitor entries.
088   */
089  static final String TRADITIONAL_WORK_QUEUE_MONITOR_OC =
090       "ds-traditional-work-queue-monitor-entry";
091
092
093
094  /**
095   * The name of the attribute that contains the average observed work queue
096   * request backlog.
097   */
098  private static final String ATTR_AVERAGE_BACKLOG = "averageRequestBacklog";
099
100
101
102  /**
103   * The name of the attribute that contains the current work queue request
104   * backlog.
105   */
106  private static final String ATTR_CURRENT_BACKLOG = "currentRequestBacklog";
107
108
109
110  /**
111   * The name of the attribute that contains the maximum observed work queue
112   * request backlog.
113   */
114  private static final String ATTR_MAX_BACKLOG = "maxRequestBacklog";
115
116
117
118  /**
119   * The name of the attribute that contains the total number of requests that
120   * have been rejected because the work queue was full.
121   */
122  private static final String ATTR_REQUESTS_REJECTED =
123       "requestsRejectedDueToQueueFull";
124
125
126
127  /**
128   * The name of the attribute that contains the total number of requests
129   * submitted.
130   */
131  private static final String ATTR_REQUESTS_SUBMITTED = "requestsSubmitted";
132
133
134
135  /**
136   * The serial version UID for this serializable class.
137   */
138  private static final long serialVersionUID = 5254676890679281070L;
139
140
141
142  // The average work queue backlog.
143  private final Long averageBacklog;
144
145  // The current work queue backlog.
146  private final Long currentBacklog;
147
148  // The maximum work queue backlog.
149  private final Long maxBacklog;
150
151  // The total number of requests rejected due to a full work queue.
152  private final Long requestsRejected;
153
154  // The total number of requests submitted.
155  private final Long requestsSubmitted;
156
157
158
159  /**
160   * Creates a new traditional work queue monitor entry from the provided entry.
161   *
162   * @param  entry  The entry to be parsed as a traditional work queue monitor
163   *                entry.  It must not be {@code null}.
164   */
165  public TraditionalWorkQueueMonitorEntry(final Entry entry)
166  {
167    super(entry);
168
169    averageBacklog    = getLong(ATTR_AVERAGE_BACKLOG);
170    currentBacklog    = getLong(ATTR_CURRENT_BACKLOG);
171    maxBacklog        = getLong(ATTR_MAX_BACKLOG);
172    requestsRejected  = getLong(ATTR_REQUESTS_REJECTED);
173    requestsSubmitted = getLong(ATTR_REQUESTS_SUBMITTED);
174  }
175
176
177
178  /**
179   * Retrieves the average number of operations observed in the work queue.
180   *
181   * @return  The average number of operations observed in the work queue, or
182   *          {@code null} if that information was not included in the monitor
183   *          entry.
184   */
185  public Long getAverageBacklog()
186  {
187    return averageBacklog;
188  }
189
190
191
192  /**
193   * Retrieves the number of operations that are currently in the work queue
194   * waiting to be processed.
195   *
196   * @return  The number of operations that are currently in the work queue
197   *          waiting to be processed, or {@code null} if that information was
198   *          not included in the monitor entry.
199   */
200  public Long getCurrentBacklog()
201  {
202    return currentBacklog;
203  }
204
205
206
207  /**
208   * Retrieves the maximum number of operations observed in the work queue at
209   * any given time.
210   *
211   * @return  The total number of operations observed in the work queue at any
212   *          given time, or {@code null} if that information was not included
213   *          in the monitor entry.
214   */
215  public Long getMaxBacklog()
216  {
217    return maxBacklog;
218  }
219
220
221
222  /**
223   * Retrieves the total number of operation requests that were rejected because
224   * the work queue was at its maximum capacity.
225   *
226   * @return  The total number of operation requests rejected because the work
227   *          queue was at its maximum capacity, or {@code null} if that
228   *          information was not included in the monitor entry.
229   */
230  public Long getRequestsRejectedDueToQueueFull()
231  {
232    return requestsRejected;
233  }
234
235
236
237  /**
238   * Retrieves the total number of operation requests submitted to the work
239   * queue.
240   *
241   * @return  The total number of operation requests submitted to the work
242   *          queue, or {@code null} if that information was not included in the
243   *          monitor entry.
244   */
245  public Long getRequestsSubmitted()
246  {
247    return requestsSubmitted;
248  }
249
250
251
252  /**
253   * {@inheritDoc}
254   */
255  @Override()
256  public String getMonitorDisplayName()
257  {
258    return INFO_TRADITIONAL_WORK_QUEUE_MONITOR_DISPNAME.get();
259  }
260
261
262
263  /**
264   * {@inheritDoc}
265   */
266  @Override()
267  public String getMonitorDescription()
268  {
269    return INFO_TRADITIONAL_WORK_QUEUE_MONITOR_DESC.get();
270  }
271
272
273
274  /**
275   * {@inheritDoc}
276   */
277  @Override()
278  public Map<String,MonitorAttribute> getMonitorAttributes()
279  {
280    final LinkedHashMap<String,MonitorAttribute> attrs =
281         new LinkedHashMap<>(StaticUtils.computeMapCapacity(10));
282
283    if (requestsSubmitted != null)
284    {
285      addMonitorAttribute(attrs,
286           ATTR_REQUESTS_SUBMITTED,
287           INFO_TRADITIONAL_WORK_QUEUE_DISPNAME_REQUESTS_SUBMITTED.get(),
288           INFO_TRADITIONAL_WORK_QUEUE_DESC_REQUESTS_SUBMITTED.get(),
289           requestsSubmitted);
290    }
291
292    if (requestsRejected != null)
293    {
294      addMonitorAttribute(attrs,
295           ATTR_REQUESTS_REJECTED,
296           INFO_TRADITIONAL_WORK_QUEUE_DISPNAME_REQUESTS_REJECTED.get(),
297           INFO_TRADITIONAL_WORK_QUEUE_DESC_REQUESTS_REJECTED.get(),
298           requestsRejected);
299    }
300
301    if (currentBacklog != null)
302    {
303      addMonitorAttribute(attrs,
304           ATTR_CURRENT_BACKLOG,
305           INFO_TRADITIONAL_WORK_QUEUE_DISPNAME_CURRENT_BACKLOG.get(),
306           INFO_TRADITIONAL_WORK_QUEUE_DESC_CURRENT_BACKLOG.get(),
307           currentBacklog);
308    }
309
310    if (averageBacklog != null)
311    {
312      addMonitorAttribute(attrs,
313           ATTR_AVERAGE_BACKLOG,
314           INFO_TRADITIONAL_WORK_QUEUE_DISPNAME_AVERAGE_BACKLOG.get(),
315           INFO_TRADITIONAL_WORK_QUEUE_DESC_AVERAGE_BACKLOG.get(),
316           averageBacklog);
317    }
318
319    if (maxBacklog != null)
320    {
321      addMonitorAttribute(attrs,
322           ATTR_MAX_BACKLOG,
323           INFO_TRADITIONAL_WORK_QUEUE_DISPNAME_MAX_BACKLOG.get(),
324           INFO_TRADITIONAL_WORK_QUEUE_DESC_MAX_BACKLOG.get(),
325           maxBacklog);
326    }
327
328    return Collections.unmodifiableMap(attrs);
329  }
330}