001/*
002 * Copyright 2010-2022 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2010-2022 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) 2010-2022 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.tasks;
037
038
039
040import java.util.Collections;
041import java.util.Date;
042import java.util.LinkedHashMap;
043import java.util.List;
044import java.util.Map;
045
046import com.unboundid.ldap.sdk.Attribute;
047import com.unboundid.ldap.sdk.Entry;
048import com.unboundid.util.NotMutable;
049import com.unboundid.util.NotNull;
050import com.unboundid.util.Nullable;
051import com.unboundid.util.StaticUtils;
052import com.unboundid.util.ThreadSafety;
053import com.unboundid.util.ThreadSafetyLevel;
054import com.unboundid.util.Validator;
055
056import static com.unboundid.ldap.sdk.unboundidds.tasks.TaskMessages.*;
057
058
059
060/**
061 * This class defines a Directory Server task that can be used to dump
062 * information about the contents of a backend which stores its data in a
063 * Berkeley DB Java Edition database.  It reports information about the total
064 * number of keys, total and average key size, and total an average value size
065 * for all of the databases in the environment, and the percentage of the total
066 * live data size contained in each database.
067 * <BR>
068 * <BLOCKQUOTE>
069 *   <B>NOTE:</B>  This class, and other classes within the
070 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
071 *   supported for use against Ping Identity, UnboundID, and
072 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
073 *   for proprietary functionality or for external specifications that are not
074 *   considered stable or mature enough to be guaranteed to work in an
075 *   interoperable way with other types of LDAP servers.
076 * </BLOCKQUOTE>
077 * <BR>
078 * The properties that are available for use with this type of task include:
079 * <UL>
080 *   <LI>The backend ID of the backend for to be examined.  The specified
081 *       backend must be enabled and must store its contents in the Berkeley DB
082 *       Java Edition.</LI>
083 * </UL>
084 */
085@NotMutable()
086@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
087public final class DumpDBDetailsTask
088       extends Task
089{
090  /**
091   * The fully-qualified name of the Java class that is used for the dump DB
092   * details task.
093   */
094  @NotNull static final String DUMP_DB_DETAILS_TASK_CLASS =
095       "com.unboundid.directory.server.tasks.DumpDBDetailsTask";
096
097
098
099  /**
100   * The name of the attribute used to specify the backend ID of the target
101   * backend.
102   */
103  @NotNull private static final String ATTR_BACKEND_ID =
104       "ds-task-dump-db-backend-id";
105
106
107
108  /**
109   * The name of the object class used in dump DB details task entries.
110   */
111  @NotNull private static final String OC_DUMP_DB_DETAILS_TASK =
112       "ds-task-dump-db";
113
114
115
116  /**
117   * The task property that will be used for the backend ID.
118   */
119  @NotNull private static final TaskProperty PROPERTY_BACKEND_ID =
120     new TaskProperty(ATTR_BACKEND_ID,
121          INFO_DUMP_DB_DISPLAY_NAME_BACKEND_ID.get(),
122          INFO_DUMP_DB_DESCRIPTION_BACKEND_ID.get(), String.class, true,
123          false, false);
124
125
126
127  /**
128   * The serial version UID for this serializable class.
129   */
130  private static final long serialVersionUID = 7267871080385864231L;
131
132
133
134  // The name of the backend to be examined.
135  @NotNull private final String backendID;
136
137
138
139  /**
140   * Creates a new uninitialized dump DB details task instance which should only
141   * be used for obtaining general information about this task, including the
142   * task name, description, and supported properties.  Attempts to use a task
143   * created with this constructor for any other reason will likely fail.
144   */
145  public DumpDBDetailsTask()
146  {
147    backendID = null;
148  }
149
150
151
152  /**
153   * Creates a new dump DB details task to examine the specified backend.
154   *
155   * @param  taskID     The task ID to use for this task.  If it is {@code null}
156   *                    then a UUID will be generated for use as the task ID.
157   * @param  backendID  The backend ID for the backend to examine.  It must not
158   *                    be {@code null}.
159   */
160  public DumpDBDetailsTask(@Nullable final String taskID,
161                           @NotNull final String backendID)
162  {
163    this(taskID, backendID, null, null, null, null, null);
164  }
165
166
167
168  /**
169   * Creates a new dump DB details task to examine the specified backend.
170   *
171   * @param  taskID                  The task ID to use for this task.  If it is
172   *                                 {@code null} then a UUID will be generated
173   *                                 for use as the task ID.
174   * @param  backendID               The backend ID for the backend to examine.
175   *                                 It must not be {@code null}.
176   * @param  scheduledStartTime      The time that this task should start
177   *                                 running.
178   * @param  dependencyIDs           The list of task IDs that will be required
179   *                                 to complete before this task will be
180   *                                 eligible to start.
181   * @param  failedDependencyAction  Indicates what action should be taken if
182   *                                 any of the dependencies for this task do
183   *                                 not complete successfully.
184   * @param  notifyOnCompletion      The list of e-mail addresses of individuals
185   *                                 that should be notified when this task
186   *                                 completes.
187   * @param  notifyOnError           The list of e-mail addresses of individuals
188   *                                 that should be notified if this task does
189   *                                 not complete successfully.
190   */
191  public DumpDBDetailsTask(@Nullable final String taskID,
192              @NotNull final String backendID,
193              @Nullable final Date scheduledStartTime,
194              @Nullable final List<String> dependencyIDs,
195              @Nullable final FailedDependencyAction failedDependencyAction,
196              @Nullable final List<String> notifyOnCompletion,
197              @Nullable final List<String> notifyOnError)
198  {
199    this(taskID, backendID, scheduledStartTime, dependencyIDs,
200         failedDependencyAction, null, notifyOnCompletion, null,
201         notifyOnError, null, null, null);
202  }
203
204
205
206  /**
207   * Creates a new dump DB details task to examine the specified backend.
208   *
209   * @param  taskID                  The task ID to use for this task.  If it is
210   *                                 {@code null} then a UUID will be generated
211   *                                 for use as the task ID.
212   * @param  backendID               The backend ID for the backend to examine.
213   *                                 It must not be {@code null}.
214   * @param  scheduledStartTime      The time that this task should start
215   *                                 running.
216   * @param  dependencyIDs           The list of task IDs that will be required
217   *                                 to complete before this task will be
218   *                                 eligible to start.
219   * @param  failedDependencyAction  Indicates what action should be taken if
220   *                                 any of the dependencies for this task do
221   *                                 not complete successfully.
222   * @param  notifyOnStart           The list of e-mail addresses of individuals
223   *                                 that should be notified when this task
224   *                                 starts running.
225   * @param  notifyOnCompletion      The list of e-mail addresses of individuals
226   *                                 that should be notified when this task
227   *                                 completes.
228   * @param  notifyOnSuccess         The list of e-mail addresses of individuals
229   *                                 that should be notified if this task
230   *                                 completes successfully.
231   * @param  notifyOnError           The list of e-mail addresses of individuals
232   *                                 that should be notified if this task does
233   *                                 not complete successfully.
234   * @param  alertOnStart            Indicates whether the server should send an
235   *                                 alert notification when this task starts.
236   * @param  alertOnSuccess          Indicates whether the server should send an
237   *                                 alert notification if this task completes
238   *                                 successfully.
239   * @param  alertOnError            Indicates whether the server should send an
240   *                                 alert notification if this task fails to
241   *                                 complete successfully.
242   */
243  public DumpDBDetailsTask(@Nullable final String taskID,
244              @NotNull final String backendID,
245              @Nullable final Date scheduledStartTime,
246              @Nullable final List<String> dependencyIDs,
247              @Nullable final FailedDependencyAction failedDependencyAction,
248              @Nullable final List<String> notifyOnStart,
249              @Nullable final List<String> notifyOnCompletion,
250              @Nullable final List<String> notifyOnSuccess,
251              @Nullable final List<String> notifyOnError,
252              @Nullable final Boolean alertOnStart,
253              @Nullable final Boolean alertOnSuccess,
254              @Nullable final Boolean alertOnError)
255  {
256    super(taskID, DUMP_DB_DETAILS_TASK_CLASS, scheduledStartTime, dependencyIDs,
257         failedDependencyAction, notifyOnStart, notifyOnCompletion,
258         notifyOnSuccess, notifyOnError, alertOnStart, alertOnSuccess,
259         alertOnError);
260
261    Validator.ensureNotNull(backendID);
262
263    this.backendID = backendID;
264  }
265
266
267
268  /**
269   * Creates a new dump DB details task from the provided entry.
270   *
271   * @param  entry  The entry to use to create this dump DB details task.
272   *
273   * @throws  TaskException  If the provided entry cannot be parsed as a dump DB
274   *                         details task entry.
275   */
276  public DumpDBDetailsTask(@NotNull final Entry entry)
277         throws TaskException
278  {
279    super(entry);
280
281    // Get the backend ID.  It must be present.
282    backendID = entry.getAttributeValue(ATTR_BACKEND_ID);
283    if (backendID == null)
284    {
285      throw new TaskException(ERR_DUMP_DB_ENTRY_MISSING_BACKEND_ID.get(
286           getTaskEntryDN(), ATTR_BACKEND_ID));
287    }
288  }
289
290
291
292  /**
293   * Creates a new dump DB details task from the provided set of task
294   * properties.
295   *
296   * @param  properties  The set of task properties and their corresponding
297   *                     values to use for the task.  It must not be
298   *                     {@code null}.
299   *
300   * @throws  TaskException  If the provided set of properties cannot be used to
301   *                         create a valid dump DB details task.
302   */
303  public DumpDBDetailsTask(
304              @NotNull final Map<TaskProperty,List<Object>> properties)
305         throws TaskException
306  {
307    super(DUMP_DB_DETAILS_TASK_CLASS, properties);
308
309    String id = null;
310    for (final Map.Entry<TaskProperty,List<Object>> entry :
311         properties.entrySet())
312    {
313      final TaskProperty p = entry.getKey();
314      final String attrName = p.getAttributeName();
315      final List<Object> values = entry.getValue();
316
317      if (attrName.equalsIgnoreCase(ATTR_BACKEND_ID))
318      {
319        id = parseString(p, values, id);
320      }
321    }
322
323    if (id == null)
324    {
325      throw new TaskException(ERR_DUMP_DB_ENTRY_MISSING_BACKEND_ID.get(
326           getTaskEntryDN(), ATTR_BACKEND_ID));
327    }
328
329    backendID = id;
330  }
331
332
333
334  /**
335   * {@inheritDoc}
336   */
337  @Override()
338  @NotNull()
339  public String getTaskName()
340  {
341    return INFO_TASK_NAME_DUMP_DB.get();
342  }
343
344
345
346  /**
347   * {@inheritDoc}
348   */
349  @Override()
350  @NotNull()
351  public String getTaskDescription()
352  {
353    return INFO_TASK_DESCRIPTION_DUMP_DB.get();
354  }
355
356
357
358  /**
359   * Retrieves the backend ID of the backend to examine.
360   *
361   * @return  The backend ID of the backend to examine.
362   */
363  @NotNull()
364  public String getBackendID()
365  {
366    return backendID;
367  }
368
369
370
371  /**
372   * {@inheritDoc}
373   */
374  @Override()
375  @NotNull()
376  protected List<String> getAdditionalObjectClasses()
377  {
378    return Collections.singletonList(OC_DUMP_DB_DETAILS_TASK);
379  }
380
381
382
383  /**
384   * {@inheritDoc}
385   */
386  @Override()
387  @NotNull()
388  protected List<Attribute> getAdditionalAttributes()
389  {
390    return Collections.singletonList(new Attribute(ATTR_BACKEND_ID, backendID));
391  }
392
393
394
395  /**
396   * {@inheritDoc}
397   */
398  @Override()
399  @NotNull()
400  public List<TaskProperty> getTaskSpecificProperties()
401  {
402    return Collections.singletonList(PROPERTY_BACKEND_ID);
403  }
404
405
406
407  /**
408   * {@inheritDoc}
409   */
410  @Override()
411  @NotNull()
412  public Map<TaskProperty,List<Object>> getTaskPropertyValues()
413  {
414    final LinkedHashMap<TaskProperty,List<Object>> props =
415         new LinkedHashMap<>(StaticUtils.computeMapCapacity(1));
416
417    props.put(PROPERTY_BACKEND_ID,
418         Collections.<Object>singletonList(backendID));
419
420    props.putAll(super.getTaskPropertyValues());
421    return Collections.unmodifiableMap(props);
422  }
423}