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}