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