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}