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