001/*
002 * Copyright 2010-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.tasks;
022
023
024
025import java.util.Arrays;
026import java.util.Collections;
027import java.util.Date;
028import java.util.LinkedHashMap;
029import java.util.List;
030import java.util.Map;
031
032import com.unboundid.ldap.sdk.Attribute;
033import com.unboundid.ldap.sdk.Entry;
034import com.unboundid.util.NotMutable;
035import com.unboundid.util.ThreadSafety;
036import com.unboundid.util.ThreadSafetyLevel;
037
038import static com.unboundid.ldap.sdk.unboundidds.tasks.TaskMessages.*;
039import static com.unboundid.util.Validator.*;
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 Alcatel-Lucent 8661
055 *   server products.  These classes provide support for proprietary
056 *   functionality or for external specifications that are not considered stable
057 *   or mature enough to be guaranteed to work in an interoperable way with
058 *   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  /**
136   * Creates a new dump DB details task to examine the specified backend.
137   *
138   * @param  taskID     The task ID to use for this task.  If it is {@code null}
139   *                    then a UUID will be generated for use as the task ID.
140   * @param  backendID  The backend ID for the backend to examine.  It must not
141   *                    be {@code null}.
142   */
143  public DumpDBDetailsTask(final String taskID, final String backendID)
144  {
145    this(taskID, backendID, null, null, null, null, null);
146  }
147
148
149
150  /**
151   * Creates a new dump DB details task to examine the specified backend.
152   *
153   * @param  taskID                  The task ID to use for this task.  If it is
154   *                                 {@code null} then a UUID will be generated
155   *                                 for use as the task ID.
156   * @param  backendID               The backend ID for the backend to examine.
157   *                                 It must not be {@code null}.
158   * @param  scheduledStartTime      The time that this task should start
159   *                                 running.
160   * @param  dependencyIDs           The list of task IDs that will be required
161   *                                 to complete before this task will be
162   *                                 eligible to start.
163   * @param  failedDependencyAction  Indicates what action should be taken if
164   *                                 any of the dependencies for this task do
165   *                                 not complete successfully.
166   * @param  notifyOnCompletion      The list of e-mail addresses of individuals
167   *                                 that should be notified when this task
168   *                                 completes.
169   * @param  notifyOnError           The list of e-mail addresses of individuals
170   *                                 that should be notified if this task does
171   *                                 not complete successfully.
172   */
173  public DumpDBDetailsTask(final String taskID, final String backendID,
174                           final Date scheduledStartTime,
175                           final List<String> dependencyIDs,
176                           final FailedDependencyAction failedDependencyAction,
177                           final List<String> notifyOnCompletion,
178                           final List<String> notifyOnError)
179  {
180    super(taskID, DUMP_DB_DETAILS_TASK_CLASS, scheduledStartTime, dependencyIDs,
181         failedDependencyAction, notifyOnCompletion, notifyOnError);
182
183    ensureNotNull(backendID);
184
185    this.backendID = backendID;
186  }
187
188
189
190  /**
191   * Creates a new dump DB details task from the provided entry.
192   *
193   * @param  entry  The entry to use to create this dump DB details task.
194   *
195   * @throws  TaskException  If the provided entry cannot be parsed as a dump DB
196   *                         details task entry.
197   */
198  public DumpDBDetailsTask(final Entry entry)
199         throws TaskException
200  {
201    super(entry);
202
203    // Get the backend ID.  It must be present.
204    backendID = entry.getAttributeValue(ATTR_BACKEND_ID);
205    if (backendID == null)
206    {
207      throw new TaskException(ERR_DUMP_DB_ENTRY_MISSING_BACKEND_ID.get(
208           getTaskEntryDN(), ATTR_BACKEND_ID));
209    }
210  }
211
212
213
214  /**
215   * Creates a new dump DB details task from the provided set of task
216   * properties.
217   *
218   * @param  properties  The set of task properties and their corresponding
219   *                     values to use for the task.  It must not be
220   *                     {@code null}.
221   *
222   * @throws  TaskException  If the provided set of properties cannot be used to
223   *                         create a valid dump DB details task.
224   */
225  public DumpDBDetailsTask(final Map<TaskProperty,List<Object>> properties)
226         throws TaskException
227  {
228    super(DUMP_DB_DETAILS_TASK_CLASS, properties);
229
230    String id = null;
231    for (final Map.Entry<TaskProperty,List<Object>> entry :
232         properties.entrySet())
233    {
234      final TaskProperty p = entry.getKey();
235      final String attrName = p.getAttributeName();
236      final List<Object> values = entry.getValue();
237
238      if (attrName.equalsIgnoreCase(ATTR_BACKEND_ID))
239      {
240        id = parseString(p, values, id);
241      }
242    }
243
244    if (id == null)
245    {
246      throw new TaskException(ERR_DUMP_DB_ENTRY_MISSING_BACKEND_ID.get(
247           getTaskEntryDN(), ATTR_BACKEND_ID));
248    }
249
250    backendID = id;
251  }
252
253
254
255  /**
256   * {@inheritDoc}
257   */
258  @Override()
259  public String getTaskName()
260  {
261    return INFO_TASK_NAME_DUMP_DB.get();
262  }
263
264
265
266  /**
267   * {@inheritDoc}
268   */
269  @Override()
270  public String getTaskDescription()
271  {
272    return INFO_TASK_DESCRIPTION_DUMP_DB.get();
273  }
274
275
276
277  /**
278   * Retrieves the backend ID of the backend to examine.
279   *
280   * @return  The backend ID of the backend to examine.
281   */
282  public String getBackendID()
283  {
284    return backendID;
285  }
286
287
288
289  /**
290   * {@inheritDoc}
291   */
292  @Override()
293  protected List<String> getAdditionalObjectClasses()
294  {
295    return Arrays.asList(OC_DUMP_DB_DETAILS_TASK);
296  }
297
298
299
300  /**
301   * {@inheritDoc}
302   */
303  @Override()
304  protected List<Attribute> getAdditionalAttributes()
305  {
306    return Arrays.asList(new Attribute(ATTR_BACKEND_ID, backendID));
307  }
308
309
310
311  /**
312   * {@inheritDoc}
313   */
314  @Override()
315  public List<TaskProperty> getTaskSpecificProperties()
316  {
317    return Collections.unmodifiableList(Arrays.asList(PROPERTY_BACKEND_ID));
318  }
319
320
321
322  /**
323   * {@inheritDoc}
324   */
325  @Override()
326  public Map<TaskProperty,List<Object>> getTaskPropertyValues()
327  {
328    final LinkedHashMap<TaskProperty,List<Object>> props =
329         new LinkedHashMap<TaskProperty,List<Object>>(1);
330
331    props.put(PROPERTY_BACKEND_ID, Collections.<Object>unmodifiableList(
332         Arrays.asList(backendID)));
333
334    props.putAll(super.getTaskPropertyValues());
335    return Collections.unmodifiableMap(props);
336  }
337}