001/* 002 * Copyright 2008-2017 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-2017 UnboundID Corp. 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.examples; 022 023 024 025import java.io.IOException; 026import java.io.OutputStream; 027import java.io.Serializable; 028import java.util.LinkedHashMap; 029import java.util.List; 030 031import com.unboundid.ldap.sdk.Control; 032import com.unboundid.ldap.sdk.LDAPConnection; 033import com.unboundid.ldap.sdk.LDAPException; 034import com.unboundid.ldap.sdk.ResultCode; 035import com.unboundid.ldap.sdk.Version; 036import com.unboundid.ldif.LDIFChangeRecord; 037import com.unboundid.ldif.LDIFException; 038import com.unboundid.ldif.LDIFReader; 039import com.unboundid.util.LDAPCommandLineTool; 040import com.unboundid.util.ThreadSafety; 041import com.unboundid.util.ThreadSafetyLevel; 042import com.unboundid.util.args.ArgumentException; 043import com.unboundid.util.args.ArgumentParser; 044import com.unboundid.util.args.BooleanArgument; 045import com.unboundid.util.args.ControlArgument; 046import com.unboundid.util.args.FileArgument; 047 048 049 050/** 051 * This class provides a simple tool that can be used to perform add, delete, 052 * modify, and modify DN operations against an LDAP directory server. The 053 * changes to apply can be read either from standard input or from an LDIF file. 054 * <BR><BR> 055 * Some of the APIs demonstrated by this example include: 056 * <UL> 057 * <LI>Argument Parsing (from the {@code com.unboundid.util.args} 058 * package)</LI> 059 * <LI>LDAP Command-Line Tool (from the {@code com.unboundid.util} 060 * package)</LI> 061 * <LI>LDIF Processing (from the {@code com.unboundid.ldif} package)</LI> 062 * </UL> 063 * <BR><BR> 064 * The behavior of this utility is controlled by command line arguments. 065 * Supported arguments include those allowed by the {@link LDAPCommandLineTool} 066 * class, as well as the following additional arguments: 067 * <UL> 068 * <LI>"-f {path}" or "--ldifFile {path}" -- specifies the path to the LDIF 069 * file containing the changes to apply. If this is not provided, then 070 * changes will be read from standard input.</LI> 071 * <LI>"-a" or "--defaultAdd" -- indicates that any LDIF records encountered 072 * that do not include a changetype should be treated as add change 073 * records. If this is not provided, then such records will be 074 * rejected.</LI> 075 * <LI>"-c" or "--continueOnError" -- indicates that processing should 076 * continue if an error occurs while processing an earlier change. If 077 * this is not provided, then the command will exit on the first error 078 * that occurs.</LI> 079 * <LI>"--bindControl {control}" -- specifies a control that should be 080 * included in the bind request sent by this tool before performing any 081 * update operations.</LI> 082 * </UL> 083 */ 084@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE) 085public final class LDAPModify 086 extends LDAPCommandLineTool 087 implements Serializable 088{ 089 /** 090 * The serial version UID for this serializable class. 091 */ 092 private static final long serialVersionUID = -2602159836108416722L; 093 094 095 096 // Indicates whether processing should continue even if an error has occurred. 097 private BooleanArgument continueOnError; 098 099 // Indicates whether LDIF records without a changetype should be considered 100 // add records. 101 private BooleanArgument defaultAdd; 102 103 // The argument used to specify any bind controls that should be used. 104 private ControlArgument bindControls; 105 106 // The LDIF file to be processed. 107 private FileArgument ldifFile; 108 109 110 111 /** 112 * Parse the provided command line arguments and make the appropriate set of 113 * changes. 114 * 115 * @param args The command line arguments provided to this program. 116 */ 117 public static void main(final String[] args) 118 { 119 final ResultCode resultCode = main(args, System.out, System.err); 120 if (resultCode != ResultCode.SUCCESS) 121 { 122 System.exit(resultCode.intValue()); 123 } 124 } 125 126 127 128 /** 129 * Parse the provided command line arguments and make the appropriate set of 130 * changes. 131 * 132 * @param args The command line arguments provided to this program. 133 * @param outStream The output stream to which standard out should be 134 * written. It may be {@code null} if output should be 135 * suppressed. 136 * @param errStream The output stream to which standard error should be 137 * written. It may be {@code null} if error messages 138 * should be suppressed. 139 * 140 * @return A result code indicating whether the processing was successful. 141 */ 142 public static ResultCode main(final String[] args, 143 final OutputStream outStream, 144 final OutputStream errStream) 145 { 146 final LDAPModify ldapModify = new LDAPModify(outStream, errStream); 147 return ldapModify.runTool(args); 148 } 149 150 151 152 /** 153 * Creates a new instance of this tool. 154 * 155 * @param outStream The output stream to which standard out should be 156 * written. It may be {@code null} if output should be 157 * suppressed. 158 * @param errStream The output stream to which standard error should be 159 * written. It may be {@code null} if error messages 160 * should be suppressed. 161 */ 162 public LDAPModify(final OutputStream outStream, final OutputStream errStream) 163 { 164 super(outStream, errStream); 165 } 166 167 168 169 /** 170 * Retrieves the name for this tool. 171 * 172 * @return The name for this tool. 173 */ 174 @Override() 175 public String getToolName() 176 { 177 return "ldapmodify"; 178 } 179 180 181 182 /** 183 * Retrieves the description for this tool. 184 * 185 * @return The description for this tool. 186 */ 187 @Override() 188 public String getToolDescription() 189 { 190 return "Perform add, delete, modify, and modify " + 191 "DN operations in an LDAP directory server."; 192 } 193 194 195 196 /** 197 * Retrieves the version string for this tool. 198 * 199 * @return The version string for this tool. 200 */ 201 @Override() 202 public String getToolVersion() 203 { 204 return Version.NUMERIC_VERSION_STRING; 205 } 206 207 208 209 /** 210 * Indicates whether this tool should provide support for an interactive mode, 211 * in which the tool offers a mode in which the arguments can be provided in 212 * a text-driven menu rather than requiring them to be given on the command 213 * line. If interactive mode is supported, it may be invoked using the 214 * "--interactive" argument. Alternately, if interactive mode is supported 215 * and {@link #defaultsToInteractiveMode()} returns {@code true}, then 216 * interactive mode may be invoked by simply launching the tool without any 217 * arguments. 218 * 219 * @return {@code true} if this tool supports interactive mode, or 220 * {@code false} if not. 221 */ 222 @Override() 223 public boolean supportsInteractiveMode() 224 { 225 return true; 226 } 227 228 229 230 /** 231 * Indicates whether this tool defaults to launching in interactive mode if 232 * the tool is invoked without any command-line arguments. This will only be 233 * used if {@link #supportsInteractiveMode()} returns {@code true}. 234 * 235 * @return {@code true} if this tool defaults to using interactive mode if 236 * launched without any command-line arguments, or {@code false} if 237 * not. 238 */ 239 @Override() 240 public boolean defaultsToInteractiveMode() 241 { 242 return true; 243 } 244 245 246 247 /** 248 * Indicates whether this tool should provide arguments for redirecting output 249 * to a file. If this method returns {@code true}, then the tool will offer 250 * an "--outputFile" argument that will specify the path to a file to which 251 * all standard output and standard error content will be written, and it will 252 * also offer a "--teeToStandardOut" argument that can only be used if the 253 * "--outputFile" argument is present and will cause all output to be written 254 * to both the specified output file and to standard output. 255 * 256 * @return {@code true} if this tool should provide arguments for redirecting 257 * output to a file, or {@code false} if not. 258 */ 259 @Override() 260 protected boolean supportsOutputFile() 261 { 262 return true; 263 } 264 265 266 267 /** 268 * Indicates whether this tool should default to interactively prompting for 269 * the bind password if a password is required but no argument was provided 270 * to indicate how to get the password. 271 * 272 * @return {@code true} if this tool should default to interactively 273 * prompting for the bind password, or {@code false} if not. 274 */ 275 @Override() 276 protected boolean defaultToPromptForBindPassword() 277 { 278 return true; 279 } 280 281 282 283 /** 284 * Indicates whether this tool supports the use of a properties file for 285 * specifying default values for arguments that aren't specified on the 286 * command line. 287 * 288 * @return {@code true} if this tool supports the use of a properties file 289 * for specifying default values for arguments that aren't specified 290 * on the command line, or {@code false} if not. 291 */ 292 @Override() 293 public boolean supportsPropertiesFile() 294 { 295 return true; 296 } 297 298 299 300 /** 301 * Indicates whether the LDAP-specific arguments should include alternate 302 * versions of all long identifiers that consist of multiple words so that 303 * they are available in both camelCase and dash-separated versions. 304 * 305 * @return {@code true} if this tool should provide multiple versions of 306 * long identifiers for LDAP-specific arguments, or {@code false} if 307 * not. 308 */ 309 @Override() 310 protected boolean includeAlternateLongIdentifiers() 311 { 312 return true; 313 } 314 315 316 317 /** 318 * Adds the arguments used by this program that aren't already provided by the 319 * generic {@code LDAPCommandLineTool} framework. 320 * 321 * @param parser The argument parser to which the arguments should be added. 322 * 323 * @throws ArgumentException If a problem occurs while adding the arguments. 324 */ 325 @Override() 326 public void addNonLDAPArguments(final ArgumentParser parser) 327 throws ArgumentException 328 { 329 String description = "Treat LDIF records that do not contain a " + 330 "changetype as add records."; 331 defaultAdd = new BooleanArgument('a', "defaultAdd", description); 332 defaultAdd.addLongIdentifier("default-add"); 333 parser.addArgument(defaultAdd); 334 335 336 description = "Attempt to continue processing additional changes if " + 337 "an error occurs."; 338 continueOnError = new BooleanArgument('c', "continueOnError", 339 description); 340 continueOnError.addLongIdentifier("continue-on-error"); 341 parser.addArgument(continueOnError); 342 343 344 description = "The path to the LDIF file containing the changes. If " + 345 "this is not provided, then the changes will be read from " + 346 "standard input."; 347 ldifFile = new FileArgument('f', "ldifFile", false, 1, "{path}", 348 description, true, false, true, false); 349 ldifFile.addLongIdentifier("ldif-file"); 350 parser.addArgument(ldifFile); 351 352 353 description = "Information about a control to include in the bind request."; 354 bindControls = new ControlArgument(null, "bindControl", false, 0, null, 355 description); 356 bindControls.addLongIdentifier("bind-control"); 357 parser.addArgument(bindControls); 358 } 359 360 361 362 /** 363 * {@inheritDoc} 364 */ 365 @Override() 366 protected List<Control> getBindControls() 367 { 368 return bindControls.getValues(); 369 } 370 371 372 373 /** 374 * Performs the actual processing for this tool. In this case, it gets a 375 * connection to the directory server and uses it to perform the requested 376 * operations. 377 * 378 * @return The result code for the processing that was performed. 379 */ 380 @Override() 381 public ResultCode doToolProcessing() 382 { 383 // Set up the LDIF reader that will be used to read the changes to apply. 384 final LDIFReader ldifReader; 385 try 386 { 387 if (ldifFile.isPresent()) 388 { 389 // An LDIF file was specified on the command line, so we will use it. 390 ldifReader = new LDIFReader(ldifFile.getValue()); 391 } 392 else 393 { 394 // No LDIF file was specified, so we will read from standard input. 395 ldifReader = new LDIFReader(System.in); 396 } 397 } 398 catch (IOException ioe) 399 { 400 err("I/O error creating the LDIF reader: ", ioe.getMessage()); 401 return ResultCode.LOCAL_ERROR; 402 } 403 404 405 // Get the connection to the directory server. 406 final LDAPConnection connection; 407 try 408 { 409 connection = getConnection(); 410 out("Connected to ", connection.getConnectedAddress(), ':', 411 connection.getConnectedPort()); 412 } 413 catch (LDAPException le) 414 { 415 err("Error connecting to the directory server: ", le.getMessage()); 416 return le.getResultCode(); 417 } 418 419 420 // Attempt to process and apply the changes to the server. 421 ResultCode resultCode = ResultCode.SUCCESS; 422 while (true) 423 { 424 // Read the next change to process. 425 final LDIFChangeRecord changeRecord; 426 try 427 { 428 changeRecord = ldifReader.readChangeRecord(defaultAdd.isPresent()); 429 } 430 catch (LDIFException le) 431 { 432 err("Malformed change record: ", le.getMessage()); 433 if (! le.mayContinueReading()) 434 { 435 err("Unable to continue processing the LDIF content."); 436 resultCode = ResultCode.DECODING_ERROR; 437 break; 438 } 439 else if (! continueOnError.isPresent()) 440 { 441 resultCode = ResultCode.DECODING_ERROR; 442 break; 443 } 444 else 445 { 446 // We can try to keep processing, so do so. 447 continue; 448 } 449 } 450 catch (IOException ioe) 451 { 452 err("I/O error encountered while reading a change record: ", 453 ioe.getMessage()); 454 resultCode = ResultCode.LOCAL_ERROR; 455 break; 456 } 457 458 459 // If the change record was null, then it means there are no more changes 460 // to be processed. 461 if (changeRecord == null) 462 { 463 break; 464 } 465 466 467 // Apply the target change to the server. 468 try 469 { 470 out("Processing ", changeRecord.getChangeType().toString(), 471 " operation for ", changeRecord.getDN()); 472 changeRecord.processChange(connection); 473 out("Success"); 474 out(); 475 } 476 catch (LDAPException le) 477 { 478 err("Error: ", le.getMessage()); 479 err("Result Code: ", le.getResultCode().intValue(), " (", 480 le.getResultCode().getName(), ')'); 481 if (le.getMatchedDN() != null) 482 { 483 err("Matched DN: ", le.getMatchedDN()); 484 } 485 486 if (le.getReferralURLs() != null) 487 { 488 for (final String url : le.getReferralURLs()) 489 { 490 err("Referral URL: ", url); 491 } 492 } 493 494 err(); 495 if (! continueOnError.isPresent()) 496 { 497 resultCode = le.getResultCode(); 498 break; 499 } 500 } 501 } 502 503 504 // Close the connection to the directory server and exit. 505 connection.close(); 506 out("Disconnected from the server"); 507 return resultCode; 508 } 509 510 511 512 /** 513 * {@inheritDoc} 514 */ 515 @Override() 516 public LinkedHashMap<String[],String> getExampleUsages() 517 { 518 final LinkedHashMap<String[],String> examples = 519 new LinkedHashMap<String[],String>(); 520 521 String[] args = 522 { 523 "--hostname", "server.example.com", 524 "--port", "389", 525 "--bindDN", "uid=admin,dc=example,dc=com", 526 "--bindPassword", "password", 527 "--ldifFile", "changes.ldif" 528 }; 529 String description = 530 "Attempt to apply the add, delete, modify, and/or modify DN " + 531 "operations contained in the 'changes.ldif' file against the " + 532 "specified directory server."; 533 examples.put(args, description); 534 535 args = new String[] 536 { 537 "--hostname", "server.example.com", 538 "--port", "389", 539 "--bindDN", "uid=admin,dc=example,dc=com", 540 "--bindPassword", "password", 541 "--continueOnError", 542 "--defaultAdd" 543 }; 544 description = 545 "Establish a connection to the specified directory server and then " + 546 "wait for information about the add, delete, modify, and/or modify " + 547 "DN operations to perform to be provided via standard input. If " + 548 "any invalid operations are requested, then the tool will display " + 549 "an error message but will continue running. Any LDIF record " + 550 "provided which does not include a 'changeType' line will be " + 551 "treated as an add request."; 552 examples.put(args, description); 553 554 return examples; 555 } 556}