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