UnboundID LDAP SDK for Java

Command Line Argument Processing

The com.unboundid.util.args package contains a set of classes that may be used for processing command line arguments provided to a program, as well as generating program usage information based on the arguments that it accepts.

The Argument Parser

The ArgumentParser class is used to hold all of the arguments that are defined, as well as parsing the provided set of arguments and generating usage information.

When an argument parser is created, it must be created with a name and general description for the command. It may also specify a maximum number of unnamed trailing arguments and a placeholder string for the set of trailing arguments. Named arguments may be added to the argument parser using the addArgument method. Once all of the arguments have been registered, then argument information may be parsed using the parse(String[] args) method. Alternately, usage information may be obtained using one of the getUsage or getUsageString methods.

The argument parser also provides support for dependent argument sets, exclusive argument sets, and required argument sets. A dependent argument set defines a set of one or more arguments that must be provided if a given target attribute is given. An exclusive argument set defines a collection of arguments that may not be used in conjunction with each other, so at most one of the arguments in an exclusive argument set may be provided. A required argument set defines a collection of arguments in which at least one of the specified arguments must be provided. If the same set of arguments is registered as both an exclusive argument set and a required argument set, then exactly one of those arguments must be provided.

Generic Named Arguments

All arguments have the provided properties:

• Zero or more short identifiers, each of which consists of a single character.
  
  
• Zero or more long identifiers, each of which consists of a string.
  
  
• A human-readable description that explains the purpose of the argument.
  
  
• A flag that indicates whether the argument is required to be provided.
  
  
• A value that specifies the maximum number of times (if any) that the argument may be provided.
  
  
• A placeholder string that suggests the type of value required for the argument (if it takes a value).
  
  
• A flag that indicates whether the argument should be excluded from usage information.
  
  

An argument may be specified using a single dash followed by any of its short identifier characters (e.g., "-H") or two dashes followed by any of its long identifier strings (e.g., "--help"). If an argument takes a value, then it may be provided in one of the following ways:

• Separated from either the short identifier or long identifier by one or more spaces (e.g., "-h server.example.com" or "--host server.example.com").
  
  
• Immediately following the short identifier without any spaces (e.g., "-hserver.example.com").
  
  
• Separated from the long identifier using a single equal sign (e.g., "--host=server.example.com").
  
  

If there are multiple arguments which have short identifiers and do not take values, then they may be specified using a single dash followed by the short identifiers for each of those arguments with no spaces (e.g., for arguments with short identifiers of "-a", "-b", and "-c", then they can be specified as "-abc").

Generic arguments are abstract and therefore cannot be directly instantiated. Instead, it is necessary to create an instance of an argument subclass. Those specific types of arguments are described below.

Boolean Arguments

Boolean arguments are those which represent a Boolean condition. Boolean arguments do not have values, but rather the condition is indicated based on whether or not that argument is provided. For example, if a Boolean argument is defined with a short identifier of "-v" and is used to indicate that the command should operate in verbose mode, then if the "-v" argument is not provided then it would be interpreted as if the command should not operate in verbose mode, whereas it should use verbose mode if the "-v" argument is provided. The isPresent() method may be used to determine whether a Boolean argument was provided.

In addition, it may be desirable to allow Boolean argument to be provided multiple times (by calling the setMaxOccurrences method) if the effect may be enhanced by providing the value multiple times. For example, if "-v" enables verbose mode then something like "-v -v -v" could increase the level of verbosity.

Integer Arguments

Integer arguments are intended to hold integer values. Integer arguments are required to take values which can be parsed as integers. It is also possible to define lower and upper bounds for the values that are allowed, so that any value which is below the lower bound or above the upper bound will be rejected.

String Arguments

String arguments are intended to hold text-based values. String arguments are required to take values. It is also possible to provide a set of allowed values, and if that is done then values which are not contained in that set of allowed values will be rejected.

DN Arguments

DN arguments are intended to hold values that are distinguished names. DN arguments are required to take values, and it must be possible to parse them as valid DNs.

Filter Arguments

Filter arguments are intended to hold values that are string representations of LDAP search filters. Filter arguments are required to take values, and it must be possible to parse them as valid search filters.

File Arguments

File arguments are intended to refer to files or directories on the local filesystem. It is possible to specify whether values must be files that exist, or at least whose parent directories exist. It is also possible to specify whether the target file must be a regular file or a directory. Finally, there are methods that can be used to retrieve the contents of the specified file (either as strings that comprise the lines of the file or the bytes that comprise the raw file data).