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.examples;
037
038
039
040import java.io.IOException;
041import java.io.OutputStream;
042import java.io.Serializable;
043import java.text.ParseException;
044import java.util.ArrayList;
045import java.util.LinkedHashMap;
046import java.util.List;
047import java.util.Set;
048import java.util.concurrent.CyclicBarrier;
049import java.util.concurrent.atomic.AtomicBoolean;
050import java.util.concurrent.atomic.AtomicInteger;
051import java.util.concurrent.atomic.AtomicLong;
052
053import com.unboundid.ldap.sdk.Control;
054import com.unboundid.ldap.sdk.LDAPConnection;
055import com.unboundid.ldap.sdk.LDAPConnectionOptions;
056import com.unboundid.ldap.sdk.LDAPException;
057import com.unboundid.ldap.sdk.ResultCode;
058import com.unboundid.ldap.sdk.Version;
059import com.unboundid.ldap.sdk.controls.AssertionRequestControl;
060import com.unboundid.ldap.sdk.controls.PermissiveModifyRequestControl;
061import com.unboundid.ldap.sdk.controls.PostReadRequestControl;
062import com.unboundid.ldap.sdk.controls.PreReadRequestControl;
063import com.unboundid.util.ColumnFormatter;
064import com.unboundid.util.Debug;
065import com.unboundid.util.FixedRateBarrier;
066import com.unboundid.util.FormattableColumn;
067import com.unboundid.util.HorizontalAlignment;
068import com.unboundid.util.LDAPCommandLineTool;
069import com.unboundid.util.NotNull;
070import com.unboundid.util.Nullable;
071import com.unboundid.util.ObjectPair;
072import com.unboundid.util.OutputFormat;
073import com.unboundid.util.RateAdjustor;
074import com.unboundid.util.ResultCodeCounter;
075import com.unboundid.util.StaticUtils;
076import com.unboundid.util.ThreadSafety;
077import com.unboundid.util.ThreadSafetyLevel;
078import com.unboundid.util.ValuePattern;
079import com.unboundid.util.WakeableSleeper;
080import com.unboundid.util.args.ArgumentException;
081import com.unboundid.util.args.ArgumentParser;
082import com.unboundid.util.args.BooleanArgument;
083import com.unboundid.util.args.ControlArgument;
084import com.unboundid.util.args.FileArgument;
085import com.unboundid.util.args.FilterArgument;
086import com.unboundid.util.args.IntegerArgument;
087import com.unboundid.util.args.StringArgument;
088
089
090
091/**
092 * This class provides a tool that can be used to perform repeated modifications
093 * in an LDAP directory server using multiple threads.  It can help provide an
094 * estimate of the modify performance that a directory server is able to
095 * achieve.  The target entry DN may be a value pattern as described in the
096 * {@link ValuePattern} class.  This makes it possible to modify a range of
097 * entries rather than repeatedly updating the same entry.
098 * <BR><BR>
099 * Some of the APIs demonstrated by this example include:
100 * <UL>
101 *   <LI>Argument Parsing (from the {@code com.unboundid.util.args}
102 *       package)</LI>
103 *   <LI>LDAP Command-Line Tool (from the {@code com.unboundid.util}
104 *       package)</LI>
105 *   <LI>LDAP Communication (from the {@code com.unboundid.ldap.sdk}
106 *       package)</LI>
107 *   <LI>Value Patterns (from the {@code com.unboundid.util} package)</LI>
108 * </UL>
109 * <BR><BR>
110 * All of the necessary information is provided using command line arguments.
111 * Supported arguments include those allowed by the {@link LDAPCommandLineTool}
112 * class, as well as the following additional arguments:
113 * <UL>
114 *   <LI>"-b {entryDN}" or "--targetDN {baseDN}" -- specifies the DN of the
115 *       entry to be modified.  This must be provided.  It may be a simple DN,
116 *       or it may be a value pattern to express a range of entry DNs.</LI>
117 *   <LI>"-A {name}" or "--attribute {name}" -- specifies the name of the
118 *       attribute to modify.  Multiple attributes may be modified by providing
119 *       multiple instances of this argument.  At least one attribute must be
120 *       provided.</LI>
121 *   <LI>"--valuePattern {pattern}" -- specifies the pattern to use to generate
122 *       the value to use for each modification.  If this argument is provided,
123 *       then neither the "--valueLength" nor "--characterSet" arguments may be
124 *       given.</LI>
125 *   <LI>"-l {num}" or "--valueLength {num}" -- specifies the length in bytes to
126 *       use for the values of the target attributes.  If this is not provided,
127 *       then a default length of 10 bytes will be used.</LI>
128 *   <LI>"-C {chars}" or "--characterSet {chars}" -- specifies the set of
129 *       characters that will be used to generate the values to use for the
130 *       target attributes.  It should only include ASCII characters.  Values
131 *       will be generated from randomly-selected characters from this set.  If
132 *       this is not provided, then a default set of lowercase alphabetic
133 *       characters will be used.</LI>
134 *   <LI>"-t {num}" or "--numThreads {num}" -- specifies the number of
135 *       concurrent threads to use when performing the modifications.  If this
136 *       is not provided, then a default of one thread will be used.</LI>
137 *   <LI>"-i {sec}" or "--intervalDuration {sec}" -- specifies the length of
138 *       time in seconds between lines out output.  If this is not provided,
139 *       then a default interval duration of five seconds will be used.</LI>
140 *   <LI>"-I {num}" or "--numIntervals {num}" -- specifies the maximum number of
141 *       intervals for which to run.  If this is not provided, then it will
142 *       run forever.</LI>
143 *   <LI>"--iterationsBeforeReconnect {num}" -- specifies the number of modify
144 *       iterations that should be performed on a connection before that
145 *       connection is closed and replaced with a newly-established (and
146 *       authenticated, if appropriate) connection.</LI>
147 *   <LI>"-r {modifies-per-second}" or "--ratePerSecond {modifies-per-second}"
148 *       -- specifies the target number of modifies to perform per second.  It
149 *       is still necessary to specify a sufficient number of threads for
150 *       achieving this rate.  If this option is not provided, then the tool
151 *       will run at the maximum rate for the specified number of threads.</LI>
152 *   <LI>"--variableRateData {path}" -- specifies the path to a file containing
153 *       information needed to allow the tool to vary the target rate over time.
154 *       If this option is not provided, then the tool will either use a fixed
155 *       target rate as specified by the "--ratePerSecond" argument, or it will
156 *       run at the maximum rate.</LI>
157 *   <LI>"--generateSampleRateFile {path}" -- specifies the path to a file to
158 *       which sample data will be written illustrating and describing the
159 *       format of the file expected to be used in conjunction with the
160 *       "--variableRateData" argument.</LI>
161 *   <LI>"--warmUpIntervals {num}" -- specifies the number of intervals to
162 *       complete before beginning overall statistics collection.</LI>
163 *   <LI>"--timestampFormat {format}" -- specifies the format to use for
164 *       timestamps included before each output line.  The format may be one of
165 *       "none" (for no timestamps), "with-date" (to include both the date and
166 *       the time), or "without-date" (to include only time time).</LI>
167 *   <LI>"-Y {authzID}" or "--proxyAs {authzID}" -- Use the proxied
168 *       authorization v2 control to request that the operation be processed
169 *       using an alternate authorization identity.  In this case, the bind DN
170 *       should be that of a user that has permission to use this control.  The
171 *       authorization identity may be a value pattern.</LI>
172 *   <LI>"--suppressErrorResultCodes" -- Indicates that information about the
173 *       result codes for failed operations should not be displayed.</LI>
174 *   <LI>"-c" or "--csv" -- Generate output in CSV format rather than a
175 *       display-friendly format.</LI>
176 * </UL>
177 */
178@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
179public final class ModRate
180       extends LDAPCommandLineTool
181       implements Serializable
182{
183  /**
184   * The serial version UID for this serializable class.
185   */
186  private static final long serialVersionUID = 2709717414202815822L;
187
188
189
190  // Indicates whether a request has been made to stop running.
191  @NotNull private final AtomicBoolean stopRequested;
192
193  // The number of modrate threads that are currently running.
194  @NotNull private final AtomicInteger runningThreads;
195
196  // The argument used to indicate whether to generate output in CSV format.
197  @Nullable private BooleanArgument csvFormat;
198
199  // Indicates that the tool should use the increment modification type instead
200  // of replace.
201  @Nullable private BooleanArgument increment;
202
203  // Indicates that modify requests should include the permissive modify request
204  // control.
205  @Nullable private BooleanArgument permissiveModify;
206
207  // The argument used to indicate whether to suppress information about error
208  // result codes.
209  @Nullable private BooleanArgument suppressErrorsArgument;
210
211  // The argument used to indicate that a generic control should be included in
212  // the request.
213  @Nullable private ControlArgument control;
214
215  // The argument used to specify a variable rate file.
216  @Nullable private FileArgument sampleRateFile;
217
218  // The argument used to specify a variable rate file.
219  @Nullable private FileArgument variableRateData;
220
221  // Indicates that modify requests should include the assertion request control
222  // with the specified filter.
223  @Nullable private FilterArgument assertionFilter;
224
225  // The argument used to specify the collection interval.
226  @Nullable private IntegerArgument collectionInterval;
227
228  // The increment amount to use when performing an increment instead of a
229  // replace.
230  @Nullable private IntegerArgument incrementAmount;
231
232  // The argument used to specify the number of modify iterations on a
233  // connection before it is closed and re-established.
234  @Nullable private IntegerArgument iterationsBeforeReconnect;
235
236  // The argument used to specify the number of intervals.
237  @Nullable private IntegerArgument numIntervals;
238
239  // The argument used to specify the number of threads.
240  @Nullable private IntegerArgument numThreads;
241
242  // The argument used to specify the seed to use for the random number
243  // generator.
244  @Nullable private IntegerArgument randomSeed;
245
246  // The target rate of modifies per second.
247  @Nullable private IntegerArgument ratePerSecond;
248
249  // The number of values to include in the replace modification.
250  @Nullable private IntegerArgument valueCount;
251
252  // The argument used to specify the length of the values to generate.
253  @Nullable private IntegerArgument valueLength;
254
255  // The number of warm-up intervals to perform.
256  @Nullable private IntegerArgument warmUpIntervals;
257
258  // The argument used to specify the name of the attribute to modify.
259  @Nullable private StringArgument attribute;
260
261  // The argument used to specify the set of characters to use when generating
262  // values.
263  @Nullable private StringArgument characterSet;
264
265  // The argument used to specify the DNs of the entries to modify.
266  @Nullable private StringArgument entryDN;
267
268  // Indicates that modify requests should include the post-read request control
269  // to request the specified attribute.
270  @Nullable private StringArgument postReadAttribute;
271
272  // Indicates that modify requests should include the pre-read request control
273  // to request the specified attribute.
274  @Nullable private StringArgument preReadAttribute;
275
276  // The argument used to specify the proxied authorization identity.
277  @Nullable private StringArgument proxyAs;
278
279  // The argument used to specify the timestamp format.
280  @Nullable private StringArgument timestampFormat;
281
282  // The argument used to specify the pattern to use to generate values.
283  @Nullable private StringArgument valuePattern;
284
285  // A wakeable sleeper that will be used to sleep between reporting intervals.
286  @NotNull private final WakeableSleeper sleeper;
287
288
289
290  /**
291   * Parse the provided command line arguments and make the appropriate set of
292   * changes.
293   *
294   * @param  args  The command line arguments provided to this program.
295   */
296  public static void main(@NotNull final String[] args)
297  {
298    final ResultCode resultCode = main(args, System.out, System.err);
299    if (resultCode != ResultCode.SUCCESS)
300    {
301      System.exit(resultCode.intValue());
302    }
303  }
304
305
306
307  /**
308   * Parse the provided command line arguments and make the appropriate set of
309   * changes.
310   *
311   * @param  args       The command line arguments provided to this program.
312   * @param  outStream  The output stream to which standard out should be
313   *                    written.  It may be {@code null} if output should be
314   *                    suppressed.
315   * @param  errStream  The output stream to which standard error should be
316   *                    written.  It may be {@code null} if error messages
317   *                    should be suppressed.
318   *
319   * @return  A result code indicating whether the processing was successful.
320   */
321  @NotNull()
322  public static ResultCode main(@NotNull final String[] args,
323                                @Nullable final OutputStream outStream,
324                                @Nullable final OutputStream errStream)
325  {
326    final ModRate modRate = new ModRate(outStream, errStream);
327    return modRate.runTool(args);
328  }
329
330
331
332  /**
333   * Creates a new instance of this tool.
334   *
335   * @param  outStream  The output stream to which standard out should be
336   *                    written.  It may be {@code null} if output should be
337   *                    suppressed.
338   * @param  errStream  The output stream to which standard error should be
339   *                    written.  It may be {@code null} if error messages
340   *                    should be suppressed.
341   */
342  public ModRate(@Nullable final OutputStream outStream,
343                 @Nullable final OutputStream errStream)
344  {
345    super(outStream, errStream);
346
347    stopRequested = new AtomicBoolean(false);
348    runningThreads = new AtomicInteger(0);
349    sleeper = new WakeableSleeper();
350  }
351
352
353
354  /**
355   * Retrieves the name for this tool.
356   *
357   * @return  The name for this tool.
358   */
359  @Override()
360  @NotNull()
361  public String getToolName()
362  {
363    return "modrate";
364  }
365
366
367
368  /**
369   * Retrieves the description for this tool.
370   *
371   * @return  The description for this tool.
372   */
373  @Override()
374  @NotNull()
375  public String getToolDescription()
376  {
377    return "Perform repeated modifications against " +
378           "an LDAP directory server.";
379  }
380
381
382
383  /**
384   * Retrieves the version string for this tool.
385   *
386   * @return  The version string for this tool.
387   */
388  @Override()
389  @NotNull()
390  public String getToolVersion()
391  {
392    return Version.NUMERIC_VERSION_STRING;
393  }
394
395
396
397  /**
398   * Indicates whether this tool should provide support for an interactive mode,
399   * in which the tool offers a mode in which the arguments can be provided in
400   * a text-driven menu rather than requiring them to be given on the command
401   * line.  If interactive mode is supported, it may be invoked using the
402   * "--interactive" argument.  Alternately, if interactive mode is supported
403   * and {@link #defaultsToInteractiveMode()} returns {@code true}, then
404   * interactive mode may be invoked by simply launching the tool without any
405   * arguments.
406   *
407   * @return  {@code true} if this tool supports interactive mode, or
408   *          {@code false} if not.
409   */
410  @Override()
411  public boolean supportsInteractiveMode()
412  {
413    return true;
414  }
415
416
417
418  /**
419   * Indicates whether this tool defaults to launching in interactive mode if
420   * the tool is invoked without any command-line arguments.  This will only be
421   * used if {@link #supportsInteractiveMode()} returns {@code true}.
422   *
423   * @return  {@code true} if this tool defaults to using interactive mode if
424   *          launched without any command-line arguments, or {@code false} if
425   *          not.
426   */
427  @Override()
428  public boolean defaultsToInteractiveMode()
429  {
430    return true;
431  }
432
433
434
435  /**
436   * Indicates whether this tool should provide arguments for redirecting output
437   * to a file.  If this method returns {@code true}, then the tool will offer
438   * an "--outputFile" argument that will specify the path to a file to which
439   * all standard output and standard error content will be written, and it will
440   * also offer a "--teeToStandardOut" argument that can only be used if the
441   * "--outputFile" argument is present and will cause all output to be written
442   * to both the specified output file and to standard output.
443   *
444   * @return  {@code true} if this tool should provide arguments for redirecting
445   *          output to a file, or {@code false} if not.
446   */
447  @Override()
448  protected boolean supportsOutputFile()
449  {
450    return true;
451  }
452
453
454
455  /**
456   * Indicates whether this tool should default to interactively prompting for
457   * the bind password if a password is required but no argument was provided
458   * to indicate how to get the password.
459   *
460   * @return  {@code true} if this tool should default to interactively
461   *          prompting for the bind password, or {@code false} if not.
462   */
463  @Override()
464  protected boolean defaultToPromptForBindPassword()
465  {
466    return true;
467  }
468
469
470
471  /**
472   * Indicates whether this tool supports the use of a properties file for
473   * specifying default values for arguments that aren't specified on the
474   * command line.
475   *
476   * @return  {@code true} if this tool supports the use of a properties file
477   *          for specifying default values for arguments that aren't specified
478   *          on the command line, or {@code false} if not.
479   */
480  @Override()
481  public boolean supportsPropertiesFile()
482  {
483    return true;
484  }
485
486
487
488  /**
489   * Indicates whether the LDAP-specific arguments should include alternate
490   * versions of all long identifiers that consist of multiple words so that
491   * they are available in both camelCase and dash-separated versions.
492   *
493   * @return  {@code true} if this tool should provide multiple versions of
494   *          long identifiers for LDAP-specific arguments, or {@code false} if
495   *          not.
496   */
497  @Override()
498  protected boolean includeAlternateLongIdentifiers()
499  {
500    return true;
501  }
502
503
504
505  /**
506   * {@inheritDoc}
507   */
508  @Override()
509  protected boolean logToolInvocationByDefault()
510  {
511    return true;
512  }
513
514
515
516  /**
517   * Adds the arguments used by this program that aren't already provided by the
518   * generic {@code LDAPCommandLineTool} framework.
519   *
520   * @param  parser  The argument parser to which the arguments should be added.
521   *
522   * @throws  ArgumentException  If a problem occurs while adding the arguments.
523   */
524  @Override()
525  public void addNonLDAPArguments(@NotNull final ArgumentParser parser)
526         throws ArgumentException
527  {
528    String description = "The DN of the entry to modify.  It may be a simple " +
529         "DN or a value pattern to specify a range of DN (e.g., " +
530         "\"uid=user.[1-1000],ou=People,dc=example,dc=com\").  See " +
531         ValuePattern.PUBLIC_JAVADOC_URL + " for complete details about the " +
532         "value pattern syntax.  This must be provided.";
533    entryDN = new StringArgument('b', "entryDN", true, 1, "{dn}", description);
534    entryDN.setArgumentGroupName("Modification Arguments");
535    entryDN.addLongIdentifier("entry-dn", true);
536    parser.addArgument(entryDN);
537
538
539    description = "The name of the attribute to modify.  Multiple attributes " +
540                  "may be specified by providing this argument multiple " +
541                  "times.  At least one attribute must be specified.";
542    attribute = new StringArgument('A', "attribute", true, 0, "{name}",
543                                   description);
544    attribute.setArgumentGroupName("Modification Arguments");
545    parser.addArgument(attribute);
546
547
548    description = "The pattern to use to generate values for the replace " +
549                  "modifications.  If this is provided, then neither the " +
550                  "--valueLength argument nor the --characterSet arguments " +
551                  "may be provided.";
552    valuePattern = new StringArgument(null, "valuePattern", false, 1,
553                                     "{pattern}", description);
554    valuePattern.setArgumentGroupName("Modification Arguments");
555    valuePattern.addLongIdentifier("value-pattern", true);
556    parser.addArgument(valuePattern);
557
558
559    description = "The length in bytes to use when generating values for the " +
560                  "replace modifications.  If this is not provided, then a " +
561                  "default length of ten bytes will be used.";
562    valueLength = new IntegerArgument('l', "valueLength", false, 1, "{num}",
563                                      description, 1, Integer.MAX_VALUE);
564    valueLength.setArgumentGroupName("Modification Arguments");
565    valueLength.addLongIdentifier("value-length", true);
566    parser.addArgument(valueLength);
567
568
569    description = "The number of values to include in replace " +
570                  "modifications.  If this is not provided, then a default " +
571                  "of one value will be used.";
572    valueCount = new IntegerArgument(null, "valueCount", false, 1, "{num}",
573                                     description, 0, Integer.MAX_VALUE, 1);
574    valueCount.setArgumentGroupName("Modification Arguments");
575    valueCount.addLongIdentifier("value-count", true);
576    parser.addArgument(valueCount);
577
578
579    description = "Indicates that the tool should use the increment " +
580                  "modification type rather than the replace modification " +
581                  "type.";
582    increment = new BooleanArgument(null, "increment", 1, description);
583    increment.setArgumentGroupName("Modification Arguments");
584    parser.addArgument(increment);
585
586
587    description = "The amount by which to increment values when using the " +
588                  "increment modification type.  The amount may be negative " +
589                  "if values should be decremented rather than incremented.  " +
590                  "If this is not provided, then a default increment amount " +
591                  "of one will be used.";
592    incrementAmount = new IntegerArgument(null, "incrementAmount", false, 1,
593                                          null, description, Integer.MIN_VALUE,
594                                          Integer.MAX_VALUE, 1);
595    incrementAmount.setArgumentGroupName("Modification Arguments");
596    incrementAmount.addLongIdentifier("increment-amount", true);
597    parser.addArgument(incrementAmount);
598
599
600    description = "The set of characters to use to generate the values for " +
601                  "the modifications.  It should only include ASCII " +
602                  "characters.  If this is not provided, then a default set " +
603                  "of lowercase alphabetic characters will be used.";
604    characterSet = new StringArgument('C', "characterSet", false, 1, "{chars}",
605                                      description);
606    characterSet.setArgumentGroupName("Modification Arguments");
607    characterSet.addLongIdentifier("character-set", true);
608    parser.addArgument(characterSet);
609
610
611    description = "Indicates that modify requests should include the " +
612                  "assertion request control with the specified filter.";
613    assertionFilter = new FilterArgument(null, "assertionFilter", false, 1,
614                                         "{filter}", description);
615    assertionFilter.setArgumentGroupName("Request Control Arguments");
616    assertionFilter.addLongIdentifier("assertion-filter", true);
617    parser.addArgument(assertionFilter);
618
619
620    description = "Indicates that modify requests should include the " +
621                  "permissive modify request control.";
622    permissiveModify = new BooleanArgument(null, "permissiveModify", 1,
623                                           description);
624    permissiveModify.setArgumentGroupName("Request Control Arguments");
625    permissiveModify.addLongIdentifier("permissive-modify", true);
626    parser.addArgument(permissiveModify);
627
628
629    description = "Indicates that modify requests should include the " +
630                  "pre-read request control with the specified requested " +
631                  "attribute.  This argument may be provided multiple times " +
632                  "to indicate that multiple requested attributes should be " +
633                  "included in the pre-read request control.";
634    preReadAttribute = new StringArgument(null, "preReadAttribute", false, 0,
635                                          "{attribute}", description);
636    preReadAttribute.setArgumentGroupName("Request Control Arguments");
637    preReadAttribute.addLongIdentifier("pre-read-attribute", true);
638    parser.addArgument(preReadAttribute);
639
640
641    description = "Indicates that modify requests should include the " +
642                  "post-read request control with the specified requested " +
643                  "attribute.  This argument may be provided multiple times " +
644                  "to indicate that multiple requested attributes should be " +
645                  "included in the post-read request control.";
646    postReadAttribute = new StringArgument(null, "postReadAttribute", false, 0,
647                                           "{attribute}", description);
648    postReadAttribute.setArgumentGroupName("Request Control Arguments");
649    postReadAttribute.addLongIdentifier("post-read-attribute", true);
650    parser.addArgument(postReadAttribute);
651
652
653    description = "Indicates that the proxied authorization control (as " +
654                  "defined in RFC 4370) should be used to request that " +
655                  "operations be processed using an alternate authorization " +
656                  "identity.  This may be a simple authorization ID or it " +
657                  "may be a value pattern to specify a range of " +
658                  "identities.  See " + ValuePattern.PUBLIC_JAVADOC_URL +
659                  " for complete details about the value pattern syntax.";
660    proxyAs = new StringArgument('Y', "proxyAs", false, 1, "{authzID}",
661                                 description);
662    proxyAs.setArgumentGroupName("Request Control Arguments");
663    proxyAs.addLongIdentifier("proxy-as", true);
664    parser.addArgument(proxyAs);
665
666
667    description = "Indicates that modify requests should include the " +
668                  "specified request control.  This may be provided multiple " +
669                  "times to include multiple request controls.";
670    control = new ControlArgument('J', "control", false, 0, null, description);
671    control.setArgumentGroupName("Request Control Arguments");
672    parser.addArgument(control);
673
674
675    description = "The number of threads to use to perform the " +
676                  "modifications.  If this is not provided, a single thread " +
677                  "will be used.";
678    numThreads = new IntegerArgument('t', "numThreads", true, 1, "{num}",
679                                     description, 1, Integer.MAX_VALUE, 1);
680    numThreads.setArgumentGroupName("Rate Management Arguments");
681    numThreads.addLongIdentifier("num-threads", true);
682    parser.addArgument(numThreads);
683
684
685    description = "The length of time in seconds between output lines.  If " +
686                  "this is not provided, then a default interval of five " +
687                  "seconds will be used.";
688    collectionInterval = new IntegerArgument('i', "intervalDuration", true, 1,
689                                             "{num}", description, 1,
690                                             Integer.MAX_VALUE, 5);
691    collectionInterval.setArgumentGroupName("Rate Management Arguments");
692    collectionInterval.addLongIdentifier("interval-duration", true);
693    parser.addArgument(collectionInterval);
694
695
696    description = "The maximum number of intervals for which to run.  If " +
697                  "this is not provided, then the tool will run until it is " +
698                  "interrupted.";
699    numIntervals = new IntegerArgument('I', "numIntervals", true, 1, "{num}",
700                                       description, 1, Integer.MAX_VALUE,
701                                       Integer.MAX_VALUE);
702    numIntervals.setArgumentGroupName("Rate Management Arguments");
703    numIntervals.addLongIdentifier("num-intervals", true);
704    parser.addArgument(numIntervals);
705
706    description = "The number of modify iterations that should be processed " +
707                  "on a connection before that connection is closed and " +
708                  "replaced with a newly-established (and authenticated, if " +
709                  "appropriate) connection.  If this is not provided, then " +
710                  "connections will not be periodically closed and " +
711                  "re-established.";
712    iterationsBeforeReconnect = new IntegerArgument(null,
713         "iterationsBeforeReconnect", false, 1, "{num}", description, 0);
714    iterationsBeforeReconnect.setArgumentGroupName("Rate Management Arguments");
715    iterationsBeforeReconnect.addLongIdentifier("iterations-before-reconnect",
716         true);
717    parser.addArgument(iterationsBeforeReconnect);
718
719    description = "The target number of modifies to perform per second.  It " +
720                  "is still necessary to specify a sufficient number of " +
721                  "threads for achieving this rate.  If neither this option " +
722                  "nor --variableRateData is provided, then the tool will " +
723                  "run at the maximum rate for the specified number of " +
724                  "threads.";
725    ratePerSecond = new IntegerArgument('r', "ratePerSecond", false, 1,
726                                        "{modifies-per-second}", description,
727                                        1, Integer.MAX_VALUE);
728    ratePerSecond.setArgumentGroupName("Rate Management Arguments");
729    ratePerSecond.addLongIdentifier("rate-per-second", true);
730    parser.addArgument(ratePerSecond);
731
732    final String variableRateDataArgName = "variableRateData";
733    final String generateSampleRateFileArgName = "generateSampleRateFile";
734    description = RateAdjustor.getVariableRateDataArgumentDescription(
735         generateSampleRateFileArgName);
736    variableRateData = new FileArgument(null, variableRateDataArgName, false, 1,
737                                        "{path}", description, true, true, true,
738                                        false);
739    variableRateData.setArgumentGroupName("Rate Management Arguments");
740    variableRateData.addLongIdentifier("variable-rate-data", true);
741    parser.addArgument(variableRateData);
742
743    description = RateAdjustor.getGenerateSampleVariableRateFileDescription(
744         variableRateDataArgName);
745    sampleRateFile = new FileArgument(null, generateSampleRateFileArgName,
746                                      false, 1, "{path}", description, false,
747                                      true, true, false);
748    sampleRateFile.setArgumentGroupName("Rate Management Arguments");
749    sampleRateFile.addLongIdentifier("generate-sample-rate-file", true);
750    sampleRateFile.setUsageArgument(true);
751    parser.addArgument(sampleRateFile);
752    parser.addExclusiveArgumentSet(variableRateData, sampleRateFile);
753
754    description = "The number of intervals to complete before beginning " +
755                  "overall statistics collection.  Specifying a nonzero " +
756                  "number of warm-up intervals gives the client and server " +
757                  "a chance to warm up without skewing performance results.";
758    warmUpIntervals = new IntegerArgument(null, "warmUpIntervals", true, 1,
759         "{num}", description, 0, Integer.MAX_VALUE, 0);
760    warmUpIntervals.setArgumentGroupName("Rate Management Arguments");
761    warmUpIntervals.addLongIdentifier("warm-up-intervals", true);
762    parser.addArgument(warmUpIntervals);
763
764    description = "Indicates the format to use for timestamps included in " +
765                  "the output.  A value of 'none' indicates that no " +
766                  "timestamps should be included.  A value of 'with-date' " +
767                  "indicates that both the date and the time should be " +
768                  "included.  A value of 'without-date' indicates that only " +
769                  "the time should be included.";
770    final Set<String> allowedFormats =
771         StaticUtils.setOf("none", "with-date", "without-date");
772    timestampFormat = new StringArgument(null, "timestampFormat", true, 1,
773         "{format}", description, allowedFormats, "none");
774    timestampFormat.addLongIdentifier("timestamp-format", true);
775    parser.addArgument(timestampFormat);
776
777    description = "Indicates that information about the result codes for " +
778                  "failed operations should not be displayed.";
779    suppressErrorsArgument = new BooleanArgument(null,
780         "suppressErrorResultCodes", 1, description);
781    suppressErrorsArgument.addLongIdentifier("suppress-error-result-codes",
782         true);
783    parser.addArgument(suppressErrorsArgument);
784
785    description = "Generate output in CSV format rather than a " +
786                  "display-friendly format";
787    csvFormat = new BooleanArgument('c', "csv", 1, description);
788    parser.addArgument(csvFormat);
789
790    description = "Specifies the seed to use for the random number generator.";
791    randomSeed = new IntegerArgument('R', "randomSeed", false, 1, "{value}",
792         description);
793    randomSeed.addLongIdentifier("random-seed", true);
794    parser.addArgument(randomSeed);
795
796
797    // The incrementAmount argument can only be used if the increment argument
798    // is provided.
799    parser.addDependentArgumentSet(incrementAmount, increment);
800
801
802    // None of the valueLength, valueCount, characterSet, or valuePattern
803    // arguments can be used if the increment argument is provided.
804    parser.addExclusiveArgumentSet(increment, valueLength);
805    parser.addExclusiveArgumentSet(increment, valueCount);
806    parser.addExclusiveArgumentSet(increment, characterSet);
807    parser.addExclusiveArgumentSet(increment, valuePattern);
808
809
810    // The valuePattern argument cannot be used with either the valueLength or
811    // characterSet arguments.
812    parser.addExclusiveArgumentSet(valuePattern, valueLength);
813    parser.addExclusiveArgumentSet(valuePattern, characterSet);
814  }
815
816
817
818  /**
819   * Indicates whether this tool supports creating connections to multiple
820   * servers.  If it is to support multiple servers, then the "--hostname" and
821   * "--port" arguments will be allowed to be provided multiple times, and
822   * will be required to be provided the same number of times.  The same type of
823   * communication security and bind credentials will be used for all servers.
824   *
825   * @return  {@code true} if this tool supports creating connections to
826   *          multiple servers, or {@code false} if not.
827   */
828  @Override()
829  protected boolean supportsMultipleServers()
830  {
831    return true;
832  }
833
834
835
836  /**
837   * Retrieves the connection options that should be used for connections
838   * created for use with this tool.
839   *
840   * @return  The connection options that should be used for connections created
841   *          for use with this tool.
842   */
843  @Override()
844  @NotNull()
845  public LDAPConnectionOptions getConnectionOptions()
846  {
847    final LDAPConnectionOptions options = new LDAPConnectionOptions();
848    options.setUseSynchronousMode(true);
849    return options;
850  }
851
852
853
854  /**
855   * Performs the actual processing for this tool.  In this case, it gets a
856   * connection to the directory server and uses it to perform the requested
857   * modifications.
858   *
859   * @return  The result code for the processing that was performed.
860   */
861  @Override()
862  @NotNull()
863  public ResultCode doToolProcessing()
864  {
865    // If the sample rate file argument was specified, then generate the sample
866    // variable rate data file and return.
867    if (sampleRateFile.isPresent())
868    {
869      try
870      {
871        RateAdjustor.writeSampleVariableRateFile(sampleRateFile.getValue());
872        return ResultCode.SUCCESS;
873      }
874      catch (final Exception e)
875      {
876        Debug.debugException(e);
877        err("An error occurred while trying to write sample variable data " +
878             "rate file '", sampleRateFile.getValue().getAbsolutePath(),
879             "':  ", StaticUtils.getExceptionMessage(e));
880        return ResultCode.LOCAL_ERROR;
881      }
882    }
883
884
885    // Determine the random seed to use.
886    final Long seed;
887    if (randomSeed.isPresent())
888    {
889      seed = Long.valueOf(randomSeed.getValue());
890    }
891    else
892    {
893      seed = null;
894    }
895
896    // Create the value patterns for the target entry DN and proxied
897    // authorization identities.
898    final ValuePattern dnPattern;
899    try
900    {
901      dnPattern = new ValuePattern(entryDN.getValue(), seed);
902    }
903    catch (final ParseException pe)
904    {
905      Debug.debugException(pe);
906      err("Unable to parse the entry DN value pattern:  ", pe.getMessage());
907      return ResultCode.PARAM_ERROR;
908    }
909
910    final ValuePattern authzIDPattern;
911    if (proxyAs.isPresent())
912    {
913      try
914      {
915        authzIDPattern = new ValuePattern(proxyAs.getValue(), seed);
916      }
917      catch (final ParseException pe)
918      {
919        Debug.debugException(pe);
920        err("Unable to parse the proxied authorization pattern:  ",
921            pe.getMessage());
922        return ResultCode.PARAM_ERROR;
923      }
924    }
925    else
926    {
927      authzIDPattern = null;
928    }
929
930
931    // Get the set of controls to include in modify requests.
932    final ArrayList<Control> controlList = new ArrayList<>(5);
933    if (assertionFilter.isPresent())
934    {
935      controlList.add(new AssertionRequestControl(assertionFilter.getValue()));
936    }
937
938    if (permissiveModify.isPresent())
939    {
940      controlList.add(new PermissiveModifyRequestControl());
941    }
942
943    if (preReadAttribute.isPresent())
944    {
945      final List<String> attrList = preReadAttribute.getValues();
946      final String[] attrArray = new String[attrList.size()];
947      attrList.toArray(attrArray);
948      controlList.add(new PreReadRequestControl(attrArray));
949    }
950
951    if (postReadAttribute.isPresent())
952    {
953      final List<String> attrList = postReadAttribute.getValues();
954      final String[] attrArray = new String[attrList.size()];
955      attrList.toArray(attrArray);
956      controlList.add(new PostReadRequestControl(attrArray));
957    }
958
959    if (control.isPresent())
960    {
961      controlList.addAll(control.getValues());
962    }
963
964    final Control[] controlArray = new Control[controlList.size()];
965    controlList.toArray(controlArray);
966
967
968    // Get the names of the attributes to modify.
969    final String[] attrs = new String[attribute.getValues().size()];
970    attribute.getValues().toArray(attrs);
971
972
973    // If the --ratePerSecond option was specified, then limit the rate
974    // accordingly.
975    FixedRateBarrier fixedRateBarrier = null;
976    if (ratePerSecond.isPresent() || variableRateData.isPresent())
977    {
978      // We might not have a rate per second if --variableRateData is specified.
979      // The rate typically doesn't matter except when we have warm-up
980      // intervals.  In this case, we'll run at the max rate.
981      final int intervalSeconds = collectionInterval.getValue();
982      final int ratePerInterval =
983           (ratePerSecond.getValue() == null)
984           ? Integer.MAX_VALUE
985           : ratePerSecond.getValue() * intervalSeconds;
986      fixedRateBarrier =
987           new FixedRateBarrier(1000L * intervalSeconds, ratePerInterval);
988    }
989
990
991    // If --variableRateData was specified, then initialize a RateAdjustor.
992    RateAdjustor rateAdjustor = null;
993    if (variableRateData.isPresent())
994    {
995      try
996      {
997        rateAdjustor = RateAdjustor.newInstance(fixedRateBarrier,
998             ratePerSecond.getValue(), variableRateData.getValue());
999      }
1000      catch (final IOException | IllegalArgumentException e)
1001      {
1002        Debug.debugException(e);
1003        err("Initializing the variable rates failed: " + e.getMessage());
1004        return ResultCode.PARAM_ERROR;
1005      }
1006    }
1007
1008
1009    // Determine whether to include timestamps in the output and if so what
1010    // format should be used for them.
1011    final boolean includeTimestamp;
1012    final String timeFormat;
1013    if (timestampFormat.getValue().equalsIgnoreCase("with-date"))
1014    {
1015      includeTimestamp = true;
1016      timeFormat       = "dd/MM/yyyy HH:mm:ss";
1017    }
1018    else if (timestampFormat.getValue().equalsIgnoreCase("without-date"))
1019    {
1020      includeTimestamp = true;
1021      timeFormat       = "HH:mm:ss";
1022    }
1023    else
1024    {
1025      includeTimestamp = false;
1026      timeFormat       = null;
1027    }
1028
1029
1030    // Determine whether any warm-up intervals should be run.
1031    final long totalIntervals;
1032    final boolean warmUp;
1033    int remainingWarmUpIntervals = warmUpIntervals.getValue();
1034    if (remainingWarmUpIntervals > 0)
1035    {
1036      warmUp = true;
1037      totalIntervals = 0L + numIntervals.getValue() + remainingWarmUpIntervals;
1038    }
1039    else
1040    {
1041      warmUp = true;
1042      totalIntervals = 0L + numIntervals.getValue();
1043    }
1044
1045
1046    // Create the table that will be used to format the output.
1047    final OutputFormat outputFormat;
1048    if (csvFormat.isPresent())
1049    {
1050      outputFormat = OutputFormat.CSV;
1051    }
1052    else
1053    {
1054      outputFormat = OutputFormat.COLUMNS;
1055    }
1056
1057    final ColumnFormatter formatter = new ColumnFormatter(includeTimestamp,
1058         timeFormat, outputFormat, " ",
1059         new FormattableColumn(12, HorizontalAlignment.RIGHT, "Recent",
1060                  "Mods/Sec"),
1061         new FormattableColumn(12, HorizontalAlignment.RIGHT, "Recent",
1062                  "Avg Dur ms"),
1063         new FormattableColumn(12, HorizontalAlignment.RIGHT, "Recent",
1064                  "Errors/Sec"),
1065         new FormattableColumn(12, HorizontalAlignment.RIGHT, "Overall",
1066                  "Mods/Sec"),
1067         new FormattableColumn(12, HorizontalAlignment.RIGHT, "Overall",
1068                  "Avg Dur ms"));
1069
1070
1071    // Create values to use for statistics collection.
1072    final AtomicLong        modCounter   = new AtomicLong(0L);
1073    final AtomicLong        errorCounter = new AtomicLong(0L);
1074    final AtomicLong        modDurations = new AtomicLong(0L);
1075    final ResultCodeCounter rcCounter    = new ResultCodeCounter();
1076
1077
1078    // Determine the length of each interval in milliseconds.
1079    final long intervalMillis = 1000L * collectionInterval.getValue();
1080
1081
1082    // Create the threads to use for the modifications.
1083    final CyclicBarrier barrier = new CyclicBarrier(numThreads.getValue() + 1);
1084    final ModRateThread[] threads = new ModRateThread[numThreads.getValue()];
1085    for (int i=0; i < threads.length; i++)
1086    {
1087      final LDAPConnection connection;
1088      try
1089      {
1090        connection = getConnection();
1091      }
1092      catch (final LDAPException le)
1093      {
1094        Debug.debugException(le);
1095        err("Unable to connect to the directory server:  ",
1096            StaticUtils.getExceptionMessage(le));
1097        return le.getResultCode();
1098      }
1099
1100      final String valuePatternString;
1101      if (valuePattern.isPresent())
1102      {
1103        valuePatternString = valuePattern.getValue();
1104      }
1105      else
1106      {
1107        final int length;
1108        if (valueLength.isPresent())
1109        {
1110          length = valueLength.getValue();
1111        }
1112        else
1113        {
1114          length = 10;
1115        }
1116
1117        final String charSet;
1118        if (characterSet.isPresent())
1119        {
1120          charSet =
1121               characterSet.getValue().replace("]", "]]").replace("[", "[[");
1122        }
1123        else
1124        {
1125          charSet = "abcdefghijklmnopqrstuvwxyz";
1126        }
1127
1128        valuePatternString = "[random:" + length + ':' + charSet + ']';
1129      }
1130
1131      final ValuePattern parsedValuePattern;
1132      try
1133      {
1134        parsedValuePattern = new ValuePattern(valuePatternString);
1135      }
1136      catch (final ParseException e)
1137      {
1138        Debug.debugException(e);
1139        err(e.getMessage());
1140        return ResultCode.PARAM_ERROR;
1141      }
1142
1143      threads[i] = new ModRateThread(this, i, connection, dnPattern, attrs,
1144           parsedValuePattern, valueCount.getValue(), increment.isPresent(),
1145           incrementAmount.getValue(), controlArray, authzIDPattern,
1146           iterationsBeforeReconnect.getValue(), runningThreads, barrier,
1147           modCounter, modDurations, errorCounter, rcCounter, fixedRateBarrier);
1148      threads[i].start();
1149    }
1150
1151
1152    // Display the table header.
1153    for (final String headerLine : formatter.getHeaderLines(true))
1154    {
1155      out(headerLine);
1156    }
1157
1158
1159    // Start the RateAdjustor before the threads so that the initial value is
1160    // in place before any load is generated unless we're doing a warm-up in
1161    // which case, we'll start it after the warm-up is complete.
1162    if ((rateAdjustor != null) && (remainingWarmUpIntervals <= 0))
1163    {
1164      rateAdjustor.start();
1165    }
1166
1167
1168    // Indicate that the threads can start running.
1169    try
1170    {
1171      barrier.await();
1172    }
1173    catch (final Exception e)
1174    {
1175      Debug.debugException(e);
1176    }
1177
1178    long overallStartTime = System.nanoTime();
1179    long nextIntervalStartTime = System.currentTimeMillis() + intervalMillis;
1180
1181
1182    boolean setOverallStartTime = false;
1183    long    lastDuration        = 0L;
1184    long    lastNumErrors       = 0L;
1185    long    lastNumMods         = 0L;
1186    long    lastEndTime         = System.nanoTime();
1187    for (long i=0; i < totalIntervals; i++)
1188    {
1189      if (rateAdjustor != null)
1190      {
1191        if (! rateAdjustor.isAlive())
1192        {
1193          out("All of the rates in " + variableRateData.getValue().getName() +
1194              " have been completed.");
1195          break;
1196        }
1197      }
1198
1199      final long startTimeMillis = System.currentTimeMillis();
1200      final long sleepTimeMillis = nextIntervalStartTime - startTimeMillis;
1201      nextIntervalStartTime += intervalMillis;
1202      if (sleepTimeMillis > 0)
1203      {
1204        sleeper.sleep(sleepTimeMillis);
1205      }
1206
1207      if (stopRequested.get())
1208      {
1209        break;
1210      }
1211
1212      final long endTime          = System.nanoTime();
1213      final long intervalDuration = endTime - lastEndTime;
1214
1215      final long numMods;
1216      final long numErrors;
1217      final long totalDuration;
1218      if (warmUp && (remainingWarmUpIntervals > 0))
1219      {
1220        numMods       = modCounter.getAndSet(0L);
1221        numErrors     = errorCounter.getAndSet(0L);
1222        totalDuration = modDurations.getAndSet(0L);
1223      }
1224      else
1225      {
1226        numMods       = modCounter.get();
1227        numErrors     = errorCounter.get();
1228        totalDuration = modDurations.get();
1229      }
1230
1231      final long recentNumMods = numMods - lastNumMods;
1232      final long recentNumErrors = numErrors - lastNumErrors;
1233      final long recentDuration = totalDuration - lastDuration;
1234
1235      final double numSeconds = intervalDuration / 1_000_000_000.0d;
1236      final double recentModRate = recentNumMods / numSeconds;
1237      final double recentErrorRate  = recentNumErrors / numSeconds;
1238
1239      final double recentAvgDuration;
1240      if (recentNumMods > 0L)
1241      {
1242        recentAvgDuration = 1.0d * recentDuration / recentNumMods / 1_000_000;
1243      }
1244      else
1245      {
1246        recentAvgDuration = 0.0d;
1247      }
1248
1249      if (warmUp && (remainingWarmUpIntervals > 0))
1250      {
1251        out(formatter.formatRow(recentModRate, recentAvgDuration,
1252             recentErrorRate, "warming up", "warming up"));
1253
1254        remainingWarmUpIntervals--;
1255        if (remainingWarmUpIntervals == 0)
1256        {
1257          out("Warm-up completed.  Beginning overall statistics collection.");
1258          setOverallStartTime = true;
1259          if (rateAdjustor != null)
1260          {
1261            rateAdjustor.start();
1262          }
1263        }
1264      }
1265      else
1266      {
1267        if (setOverallStartTime)
1268        {
1269          overallStartTime    = lastEndTime;
1270          setOverallStartTime = false;
1271        }
1272
1273        final double numOverallSeconds =
1274             (endTime - overallStartTime) / 1_000_000_000.0d;
1275        final double overallAuthRate = numMods / numOverallSeconds;
1276
1277        final double overallAvgDuration;
1278        if (numMods > 0L)
1279        {
1280          overallAvgDuration = 1.0d * totalDuration / numMods / 1_000_000;
1281        }
1282        else
1283        {
1284          overallAvgDuration = 0.0d;
1285        }
1286
1287        out(formatter.formatRow(recentModRate, recentAvgDuration,
1288             recentErrorRate, overallAuthRate, overallAvgDuration));
1289
1290        lastNumMods     = numMods;
1291        lastNumErrors   = numErrors;
1292        lastDuration    = totalDuration;
1293      }
1294
1295      final List<ObjectPair<ResultCode,Long>> rcCounts =
1296           rcCounter.getCounts(true);
1297      if ((! suppressErrorsArgument.isPresent()) && (! rcCounts.isEmpty()))
1298      {
1299        err("\tError Results:");
1300        for (final ObjectPair<ResultCode,Long> p : rcCounts)
1301        {
1302          err("\t", p.getFirst().getName(), ":  ", p.getSecond());
1303        }
1304      }
1305
1306      lastEndTime = endTime;
1307    }
1308
1309    // Shut down the RateAdjustor if we have one.
1310    if (rateAdjustor != null)
1311    {
1312      rateAdjustor.shutDown();
1313    }
1314
1315    // Stop all of the threads.
1316    ResultCode resultCode = ResultCode.SUCCESS;
1317    for (final ModRateThread t : threads)
1318    {
1319      final ResultCode r = t.stopRunning();
1320      if (resultCode == ResultCode.SUCCESS)
1321      {
1322        resultCode = r;
1323      }
1324    }
1325
1326    return resultCode;
1327  }
1328
1329
1330
1331  /**
1332   * Requests that this tool stop running.  This method will attempt to wait
1333   * for all threads to complete before returning control to the caller.
1334   */
1335  public void stopRunning()
1336  {
1337    stopRequested.set(true);
1338    sleeper.wakeup();
1339
1340    while (true)
1341    {
1342      final int stillRunning = runningThreads.get();
1343      if (stillRunning <= 0)
1344      {
1345        break;
1346      }
1347      else
1348      {
1349        try
1350        {
1351          Thread.sleep(1L);
1352        } catch (final Exception e) {}
1353      }
1354    }
1355  }
1356
1357
1358
1359  /**
1360   * {@inheritDoc}
1361   */
1362  @Override()
1363  @NotNull()
1364  public LinkedHashMap<String[],String> getExampleUsages()
1365  {
1366    final LinkedHashMap<String[],String> examples =
1367         new LinkedHashMap<>(StaticUtils.computeMapCapacity(2));
1368
1369    String[] args =
1370    {
1371      "--hostname", "server.example.com",
1372      "--port", "389",
1373      "--bindDN", "uid=admin,dc=example,dc=com",
1374      "--bindPassword", "password",
1375      "--entryDN", "uid=user.[1-1000000],ou=People,dc=example,dc=com",
1376      "--attribute", "description",
1377      "--valueLength", "12",
1378      "--numThreads", "10"
1379    };
1380    String description =
1381         "Test modify performance by randomly selecting entries across a set " +
1382         "of one million users located below 'ou=People,dc=example,dc=com' " +
1383         "with ten concurrent threads and replacing the values for the " +
1384         "description attribute with a string of 12 randomly-selected " +
1385         "lowercase alphabetic characters.";
1386    examples.put(args, description);
1387
1388    args = new String[]
1389    {
1390      "--generateSampleRateFile", "variable-rate-data.txt"
1391    };
1392    description =
1393         "Generate a sample variable rate definition file that may be used " +
1394         "in conjunction with the --variableRateData argument.  The sample " +
1395         "file will include comments that describe the format for data to be " +
1396         "included in this file.";
1397    examples.put(args, description);
1398
1399    return examples;
1400  }
1401}