001/*
002 * Copyright 2008-2024 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2008-2024 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) 2008-2024 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.ArrayList;
041import java.util.Collections;
042import java.util.Date;
043import java.util.LinkedHashMap;
044import java.util.List;
045import java.util.Map;
046
047import com.unboundid.ldap.sdk.Attribute;
048import com.unboundid.ldap.sdk.Entry;
049import com.unboundid.util.NotMutable;
050import com.unboundid.util.NotNull;
051import com.unboundid.util.Nullable;
052import com.unboundid.util.StaticUtils;
053import com.unboundid.util.ThreadSafety;
054import com.unboundid.util.ThreadSafetyLevel;
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 cause the
062 * server to leave lockdown mode and resume normal operation.  Note that because
063 * of the nature of lockdown mode, it this task may only be requested by a user
064 * with the lockdown-mode privilege.  Alternately, the server may be restarted
065 * and it will not be placed in lockdown mode at startup unless a significant
066 * problem is encountered in which there may be a risk of unauthorized access to
067 * data.
068 * <BR>
069 * <BLOCKQUOTE>
070 *   <B>NOTE:</B>  This class, and other classes within the
071 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
072 *   supported for use against Ping Identity, UnboundID, and
073 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
074 *   for proprietary functionality or for external specifications that are not
075 *   considered stable or mature enough to be guaranteed to work in an
076 *   interoperable way with other types of LDAP servers.
077 * </BLOCKQUOTE>
078 * <BR>
079 * The leave lockdown mode task does not have any task-specific properties.  See
080 * the {@link EnterLockdownModeTask} class for more information about lockdown
081 * mode and a task that may be used to force the server to enter this state.
082 */
083@NotMutable()
084@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
085public final class LeaveLockdownModeTask
086       extends Task
087{
088  /**
089   * The fully-qualified name of the Java class that is used for the leave
090   * lockdown mode task.
091   */
092  @NotNull static final String LEAVE_LOCKDOWN_MODE_TASK_CLASS =
093       "com.unboundid.directory.server.tasks.LeaveLockdownModeTask";
094
095
096
097  /**
098   * The name of the attribute used to specify the reason for taking the server
099   * out of lockdown mode.
100   */
101  @NotNull private static final String ATTR_LEAVE_LOCKDOWN_REASON =
102       "ds-task-leave-lockdown-reason";
103
104
105
106  /**
107   * The task property for the leave-lockdown reason.
108   */
109  @NotNull private static final TaskProperty PROPERTY_LEAVE_LOCKDOWN_REASON =
110       new TaskProperty(ATTR_LEAVE_LOCKDOWN_REASON,
111                        INFO_DISPLAY_NAME_LEAVE_LOCKDOWN_REASON.get(),
112                        INFO_DESCRIPTION_LEAVE_LOCKDOWN_REASON.get(),
113                        String.class, false, false, false);
114
115
116
117  /**
118   * The name of the object class used in leave-lockdown-mode task entries.
119   */
120  @NotNull private static final String OC_LEAVE_LOCKDOWN_MODE_TASK =
121      "ds-task-leave-lockdown-mode";
122
123
124
125  /**
126   * The serial version UID for this serializable class.
127   */
128  private static final long serialVersionUID = -1353712468653879793L;
129
130
131
132  // The reason for leaving lockdown mode.
133  @Nullable private final String reason;
134
135
136
137  /**
138   * Creates a new uninitialized enter lockdown mode task instance which should
139   * only be used for obtaining general information about this task, including
140   * the task name, description, and supported properties.  Attempts to use a
141   * task created with this constructor for any other reason will likely fail.
142   */
143  public LeaveLockdownModeTask()
144  {
145    reason = null;
146  }
147
148
149
150  /**
151   * Creates a new leave lockdown mode task with the specified task ID.
152   *
153   * @param  taskID  The task ID to use for this task.  If it is {@code null}
154   *                 then a UUID will be generated for use as the task ID.
155   */
156  public LeaveLockdownModeTask(@Nullable final String taskID)
157  {
158    this(taskID, null);
159  }
160
161
162
163  /**
164   * Creates a new leave lockdown mode task with the specified task ID.
165   *
166   * @param  taskID  The task ID to use for this task.  If it is {@code null}
167   *                 then a UUID will be generated for use as the task ID.
168   * @param  reason  The user-specified reason for leaving lockdown mode. This
169   *                 may be {@code null}.
170   */
171  public LeaveLockdownModeTask(@Nullable final String taskID,
172                               @Nullable final String reason)
173  {
174    this(taskID, reason, null, null, null, null, null);
175  }
176
177
178
179  /**
180   * Creates a new leave lockdown mode task with the provided information.
181   *
182   * @param  taskID                  The task ID to use for this task.  If it is
183   *                                 {@code null} then a UUID will be generated
184   *                                 for use as the task ID.
185   * @param  scheduledStartTime      The time that this task should start
186   *                                 running.
187   * @param  dependencyIDs           The list of task IDs that will be required
188   *                                 to complete before this task will be
189   *                                 eligible to start.
190   * @param  failedDependencyAction  Indicates what action should be taken if
191   *                                 any of the dependencies for this task do
192   *                                 not complete successfully.
193   * @param  notifyOnCompletion      The list of e-mail addresses of individuals
194   *                                 that should be notified when this task
195   *                                 completes.
196   * @param  notifyOnError           The list of e-mail addresses of individuals
197   *                                 that should be notified if this task does
198   *                                 not complete successfully.
199   */
200  public LeaveLockdownModeTask(@Nullable final String taskID,
201              @Nullable final Date scheduledStartTime,
202              @Nullable final List<String> dependencyIDs,
203              @Nullable final FailedDependencyAction failedDependencyAction,
204              @Nullable final List<String> notifyOnCompletion,
205              @Nullable final List<String> notifyOnError)
206  {
207    this(taskID, null, scheduledStartTime, dependencyIDs,
208         failedDependencyAction, notifyOnCompletion, notifyOnError);
209  }
210
211
212
213  /**
214   * Creates a new leave lockdown mode task with the provided information.
215   *
216   * @param  taskID                  The task ID to use for this task.  If it is
217   *                                 {@code null} then a UUID will be generated
218   *                                 for use as the task ID.
219   * @param  reason                  The user-specified reason for leaving
220   *                                 lockdown mode. This may be {@code null}.
221   * @param  scheduledStartTime      The time that this task should start
222   *                                 running.
223   * @param  dependencyIDs           The list of task IDs that will be required
224   *                                 to complete before this task will be
225   *                                 eligible to start.
226   * @param  failedDependencyAction  Indicates what action should be taken if
227   *                                 any of the dependencies for this task do
228   *                                 not complete successfully.
229   * @param  notifyOnCompletion      The list of e-mail addresses of individuals
230   *                                 that should be notified when this task
231   *                                 completes.
232   * @param  notifyOnError           The list of e-mail addresses of individuals
233   *                                 that should be notified if this task does
234   *                                 not complete successfully.
235   */
236  public LeaveLockdownModeTask(@Nullable final String taskID,
237              @Nullable final String reason,
238              @Nullable final Date scheduledStartTime,
239              @Nullable final List<String> dependencyIDs,
240              @Nullable final FailedDependencyAction failedDependencyAction,
241              @Nullable final List<String> notifyOnCompletion,
242              @Nullable final List<String> notifyOnError)
243  {
244    this(taskID, reason, scheduledStartTime, dependencyIDs,
245         failedDependencyAction, null, notifyOnCompletion, null,
246         notifyOnError, null, null, null);
247  }
248
249
250
251  /**
252   * Creates a new leave lockdown mode task with the provided information.
253   *
254   * @param  taskID                  The task ID to use for this task.  If it is
255   *                                 {@code null} then a UUID will be generated
256   *                                 for use as the task ID.
257   * @param  reason                  The user-specified reason for leaving
258   *                                 lockdown mode. This may be {@code null}.
259   * @param  scheduledStartTime      The time that this task should start
260   *                                 running.
261   * @param  dependencyIDs           The list of task IDs that will be required
262   *                                 to complete before this task will be
263   *                                 eligible to start.
264   * @param  failedDependencyAction  Indicates what action should be taken if
265   *                                 any of the dependencies for this task do
266   *                                 not complete successfully.
267   * @param  notifyOnStart           The list of e-mail addresses of individuals
268   *                                 that should be notified when this task
269   *                                 starts running.
270   * @param  notifyOnCompletion      The list of e-mail addresses of individuals
271   *                                 that should be notified when this task
272   *                                 completes.
273   * @param  notifyOnSuccess         The list of e-mail addresses of individuals
274   *                                 that should be notified if this task
275   *                                 completes successfully.
276   * @param  notifyOnError           The list of e-mail addresses of individuals
277   *                                 that should be notified if this task does
278   *                                 not complete successfully.
279   * @param  alertOnStart            Indicates whether the server should send an
280   *                                 alert notification when this task starts.
281   * @param  alertOnSuccess          Indicates whether the server should send an
282   *                                 alert notification if this task completes
283   *                                 successfully.
284   * @param  alertOnError            Indicates whether the server should send an
285   *                                 alert notification if this task fails to
286   *                                 complete successfully.
287   */
288  public LeaveLockdownModeTask(@Nullable final String taskID,
289              @Nullable final String reason,
290              @Nullable final Date scheduledStartTime,
291              @Nullable final List<String> dependencyIDs,
292              @Nullable final FailedDependencyAction failedDependencyAction,
293              @Nullable final List<String> notifyOnStart,
294              @Nullable final List<String> notifyOnCompletion,
295              @Nullable final List<String> notifyOnSuccess,
296              @Nullable final List<String> notifyOnError,
297              @Nullable final Boolean alertOnStart,
298              @Nullable final Boolean alertOnSuccess,
299              @Nullable final Boolean alertOnError)
300  {
301    super(taskID, LEAVE_LOCKDOWN_MODE_TASK_CLASS, scheduledStartTime,
302         dependencyIDs, failedDependencyAction, notifyOnStart,
303         notifyOnCompletion, notifyOnSuccess, notifyOnError, alertOnStart,
304         alertOnSuccess, alertOnError);
305
306    this.reason = reason;
307  }
308
309
310
311  /**
312   * Creates a new leave lockdown mode task from the provided entry.
313   *
314   * @param  entry  The entry to use to create this leave lockdown mode task.
315   *
316   * @throws  TaskException  If the provided entry cannot be parsed as a leave
317   *                         lockdown mode task entry.
318   */
319  public LeaveLockdownModeTask(@NotNull final Entry entry)
320         throws TaskException
321  {
322    super(entry);
323
324    // Get the "reason" string if it is present.
325    reason = entry.getAttributeValue(ATTR_LEAVE_LOCKDOWN_REASON);
326  }
327
328
329
330  /**
331   * Creates a new leave lockdown mode task from the provided set of task
332   * properties.
333   *
334   * @param  properties  The set of task properties and their corresponding
335   *                     values to use for the task.  It must not be
336   *                     {@code null}.
337   *
338   * @throws  TaskException  If the provided set of properties cannot be used to
339   *                         create a valid leave lockdown mode task.
340   */
341  public LeaveLockdownModeTask(
342              @NotNull final Map<TaskProperty,List<Object>> properties)
343         throws TaskException
344  {
345    super(LEAVE_LOCKDOWN_MODE_TASK_CLASS, properties);
346
347    String r = null;
348    for (final Map.Entry<TaskProperty,List<Object>> entry :
349            properties.entrySet())
350    {
351      final TaskProperty p = entry.getKey();
352      final String attrName = p.getAttributeName();
353      final List<Object> values = entry.getValue();
354
355      if (attrName.equalsIgnoreCase(ATTR_LEAVE_LOCKDOWN_REASON))
356      {
357        r = parseString(p, values, null);
358        break;
359      }
360    }
361
362    reason = r;
363  }
364
365
366
367  /**
368   * Retrieves the user-specified reason why the server is leaving lockdown
369   * mode.
370   *
371   * @return  The reason the server is leaving lockdown mode, or {@code null}
372   *          if none was specified.
373   */
374  @Nullable()
375  public String getReason()
376  {
377    return reason;
378  }
379
380
381
382  /**
383   * {@inheritDoc}
384   */
385  @Override()
386  @NotNull()
387  public String getTaskName()
388  {
389    return INFO_TASK_NAME_LEAVE_LOCKDOWN_MODE.get();
390  }
391
392
393
394  /**
395   * {@inheritDoc}
396   */
397  @Override()
398  @NotNull()
399  public String getTaskDescription()
400  {
401    return INFO_TASK_DESCRIPTION_LEAVE_LOCKDOWN_MODE.get();
402  }
403
404
405
406  /**
407   * {@inheritDoc}
408   */
409  @Override()
410  @NotNull()
411  protected List<String> getAdditionalObjectClasses()
412  {
413    return Collections.singletonList(OC_LEAVE_LOCKDOWN_MODE_TASK);
414  }
415
416
417
418  /**
419   * {@inheritDoc}
420   */
421  @Override()
422  @NotNull()
423  protected List<Attribute> getAdditionalAttributes()
424  {
425    final ArrayList<Attribute> attrs = new ArrayList<>(1);
426    if (reason != null)
427    {
428      attrs.add(new Attribute(ATTR_LEAVE_LOCKDOWN_REASON, reason));
429    }
430    return attrs;
431  }
432
433
434
435  /**
436   * {@inheritDoc}
437   */
438  @Override()
439  @NotNull()
440  public List<TaskProperty> getTaskSpecificProperties()
441  {
442    final List<TaskProperty> propList =
443              Collections.singletonList(PROPERTY_LEAVE_LOCKDOWN_REASON);
444
445    return Collections.unmodifiableList(propList);
446  }
447
448
449
450  /**
451   * {@inheritDoc}
452   */
453  @Override()
454  @NotNull()
455  public Map<TaskProperty,List<Object>> getTaskPropertyValues()
456  {
457    final LinkedHashMap<TaskProperty,List<Object>> props =
458         new LinkedHashMap<>(StaticUtils.computeMapCapacity(10));
459
460    if (reason != null)
461    {
462      props.put(PROPERTY_LEAVE_LOCKDOWN_REASON,
463              Collections.<Object>singletonList(reason));
464    }
465
466    props.putAll(super.getTaskPropertyValues());
467    return Collections.unmodifiableMap(props);
468  }
469}