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