org.opends.server.util.args
Class SubCommandArgumentParser

java.lang.Object
  extended by org.opends.server.util.args.ArgumentParser
      extended by org.opends.server.util.args.SubCommandArgumentParser
Direct Known Subclasses:
SecureConnectionCliParser

public class SubCommandArgumentParser
extends ArgumentParser

This class defines a variant of the argument parser that can be used with applications that use subcommands to customize their behavior and that have a different set of options per subcommand (e.g, "cvs checkout" takes different options than "cvs commit"). This parser also has the ability to use global options that will always be applicable regardless of the subcommand in addition to the subcommand-specific arguments. There must not be any conflicts between the global options and the option for any subcommand, but it is allowed to re-use subcommand-specific options for different purposes between different subcommands.


Field Summary
 
Fields inherited from class org.opends.server.util.args.ArgumentParser
argumentGroups, defaultArgGroup, generalArgGroup, ioArgGroup, ldapArgGroup
 
Constructor Summary
SubCommandArgumentParser(java.lang.String mainClassName, Message toolDescription, boolean longArgumentsCaseSensitive)
          Creates a new instance of this subcommand argument parser with no arguments.
 
Method Summary
 void addGlobalArgument(Argument argument)
          Adds the provided argument to the set of global arguments handled by this parser.
 void addGlobalArgument(Argument argument, ArgumentGroup group)
          Adds the provided argument to the set of global arguments handled by this parser.
 Argument getGlobalArgument(java.lang.String name)
          Retrieves the global argument with the specified name.
 Argument getGlobalArgumentForLongID(java.lang.String longID)
          Retrieves the global argument with the specified long identifier.
 Argument getGlobalArgumentForShortID(java.lang.Character shortID)
          Retrieves the global argument with the specified short identifier.
 java.util.LinkedList<Argument> getGlobalArgumentList()
          Retrieves the list of all global arguments that have been defined for this argument parser.
 java.util.HashMap<java.lang.String,Argument> getGlobalArgumentsByLongID()
          Retrieves the set of global arguments mapped by the long identifier that may be used to reference them.
 java.util.HashMap<java.lang.Character,Argument> getGlobalArgumentsByShortID()
          Retrieves the set of global arguments mapped by the short identifier that may be used to reference them.
 Message getHelpUsageReference()
          Retrieves a string describing how the user can get more help.
 java.lang.String getMainClassName()
          Retrieves the fully-qualified name of the Java class that should be invoked to launch the program with which this argument parser is associated.
 java.lang.String[] getRawArguments()
          Retrieves the raw set of arguments that were provided.
 SubCommand getSubCommand()
          Retrieves the subcommand that was selected in the set of command-line arguments.
 SubCommand getSubCommand(java.lang.String name)
          Retrieves the subcommand with the specified name.
 java.util.SortedMap<java.lang.String,SubCommand> getSubCommands()
          Retrieves the set of subcommands defined for this argument parser, referenced by subcommand name.
 void getSubCommandUsage(MessageBuilder buffer, SubCommand subCommand)
          Appends usage information for the specified subcommand to the provided buffer.
 Message getToolDescription()
          Retrieves a human-readable description for this tool, which should be included at the top of the command-line usage information.
 java.util.ArrayList<java.lang.String> getTrailingArguments()
          Retrieves the set of unnamed trailing arguments that were provided on the command line.
 java.lang.String getUsage()
          Retrieves a string containing usage information based on the defined arguments.
 void getUsage(java.io.OutputStream outputStream)
          Writes usage information based on the defined arguments to the provided output stream.
 boolean hasGlobalArgument(java.lang.String argumentName)
          Indicates whether this argument parser contains a global argument with the specified name.
 boolean hasGlobalArgumentWithLongID(java.lang.String longID)
          Indicates whether this argument parser has a global argument with the specified long ID.
 boolean hasGlobalArgumentWithShortID(java.lang.Character shortID)
          Indicates whether this argument parser has a global argument with the specified short ID.
 boolean hasSubCommand(java.lang.String name)
          Indicates whether this argument parser has a subcommand with the specified name.
 boolean isUsageArgumentPresent()
          Returns whether the usage argument was provided or not.
 boolean isVersionArgumentPresent()
          Returns whether the version argument was provided or not.
 boolean longArgumentsCaseSensitive()
          Indicates whether subcommand names and long argument strings should be treated in a case-sensitive manner.
 void parseArguments(java.lang.String[] rawArguments)
          Parses the provided set of arguments and updates the information associated with this parser accordingly.
 void parseArguments(java.lang.String[] rawArguments, java.util.Properties argumentProperties)
          Parses the provided set of arguments and updates the information associated with this parser accordingly.
 void parseArguments(java.lang.String[] rawArguments, java.lang.String propertiesFile, boolean requirePropertiesFile)
          Parses the provided set of arguments and updates the information associated with this parser accordingly.
protected  void removeGlobalArgument(Argument argument)
          Removes the provided argument from the set of global arguments handled by this parser.
 void setUsageArgument(Argument argument, java.io.OutputStream outputStream)
          Sets the provided argument as one which will automatically trigger the output of full usage information if it is provided on the command line and no further argument validation will be performed.
 void setUsageGroupArgument(Argument argument, java.util.Collection<SubCommand> subCommands)
          Sets the provided argument as one which will automatically trigger the output of partial usage information if it is provided on the command line and no further argument validation will be performed.
 boolean usageOrVersionDisplayed()
          Indicates whether the usage information has been displayed to the end user either by an explicit argument like "-H" or "--help", or by a built-in argument like "-?".
 
Methods inherited from class org.opends.server.util.args.ArgumentParser
addArgument, addArgument, addDefaultArgument, addGeneralArgument, addInputOutputArgument, addLdapConnectionArgument, allowsTrailingArguments, checkExternalProperties, getArgument, getArgumentForLongID, getArgumentForShortID, getArgumentList, getArgumentsByLongID, getArgumentsByShortID, getMaxTrailingArguments, getMinTrailingArguments, getStandardGroup, getUsage, getUsageMessage, printUsageGroupHeaders, setDefaultArgumentGroupDescription, setFilePropertiesArgument, setGeneralArgumentGroupDescription, setInputOutputArgumentGroupDescription, setLdapArgumentGroupDescription, setNoPropertiesFileArgument, setUsageArgument
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SubCommandArgumentParser

public SubCommandArgumentParser(java.lang.String mainClassName,
                                Message toolDescription,
                                boolean longArgumentsCaseSensitive)
Creates a new instance of this subcommand argument parser with no arguments.

Parameters:
mainClassName - The fully-qualified name of the Java class that should be invoked to launch the program with which this argument parser is associated.
toolDescription - A human-readable description for the tool, which will be included when displaying usage information.
longArgumentsCaseSensitive - Indicates whether subcommand and long argument names should be treated in a case-sensitive manner.
Method Detail

getMainClassName

public java.lang.String getMainClassName()
Retrieves the fully-qualified name of the Java class that should be invoked to launch the program with which this argument parser is associated.

Overrides:
getMainClassName in class ArgumentParser
Returns:
The fully-qualified name of the Java class that should be invoked to launch the program with which this argument parser is associated.

getToolDescription

public Message getToolDescription()
Retrieves a human-readable description for this tool, which should be included at the top of the command-line usage information.

Overrides:
getToolDescription in class ArgumentParser
Returns:
A human-readable description for this tool, or null if none is available.

longArgumentsCaseSensitive

public boolean longArgumentsCaseSensitive()
Indicates whether subcommand names and long argument strings should be treated in a case-sensitive manner.

Returns:
true if subcommand names and long argument strings should be treated in a case-sensitive manner, or false if they should not.

getGlobalArgumentList

public java.util.LinkedList<Argument> getGlobalArgumentList()
Retrieves the list of all global arguments that have been defined for this argument parser.

Returns:
The list of all global arguments that have been defined for this argument parser.

hasGlobalArgument

public boolean hasGlobalArgument(java.lang.String argumentName)
Indicates whether this argument parser contains a global argument with the specified name.

Parameters:
argumentName - The name for which to make the determination.
Returns:
true if a global argument exists with the specified name, or false if not.

getGlobalArgument

public Argument getGlobalArgument(java.lang.String name)
Retrieves the global argument with the specified name.

Parameters:
name - The name of the global argument to retrieve.
Returns:
The global argument with the specified name, or null if there is no such argument.

getGlobalArgumentsByShortID

public java.util.HashMap<java.lang.Character,Argument> getGlobalArgumentsByShortID()
Retrieves the set of global arguments mapped by the short identifier that may be used to reference them. Note that arguments that do not have a short identifier will not be present in this list.

Returns:
The set of global arguments mapped by the short identifier that may be used to reference them.

hasGlobalArgumentWithShortID

public boolean hasGlobalArgumentWithShortID(java.lang.Character shortID)
Indicates whether this argument parser has a global argument with the specified short ID.

Parameters:
shortID - The short ID character for which to make the determination.
Returns:
true if a global argument exists with the specified short ID, or false if not.

getGlobalArgumentForShortID

public Argument getGlobalArgumentForShortID(java.lang.Character shortID)
Retrieves the global argument with the specified short identifier.

Parameters:
shortID - The short identifier for the global argument to retrieve.
Returns:
The global argument with the specified short identifier, or null if there is no such argument.

getGlobalArgumentsByLongID

public java.util.HashMap<java.lang.String,Argument> getGlobalArgumentsByLongID()
Retrieves the set of global arguments mapped by the long identifier that may be used to reference them. Note that arguments that do not have a long identifier will not be present in this list.

Returns:
The set of global arguments mapped by the long identifier that may be used to reference them.

hasGlobalArgumentWithLongID

public boolean hasGlobalArgumentWithLongID(java.lang.String longID)
Indicates whether this argument parser has a global argument with the specified long ID.

Parameters:
longID - The long ID string for which to make the determination.
Returns:
true if a global argument exists with the specified long ID, or false if not.

getGlobalArgumentForLongID

public Argument getGlobalArgumentForLongID(java.lang.String longID)
Retrieves the global argument with the specified long identifier.

Parameters:
longID - The long identifier for the global argument to retrieve.
Returns:
The global argument with the specified long identifier, or null if there is no such argument.

getSubCommands

public java.util.SortedMap<java.lang.String,SubCommand> getSubCommands()
Retrieves the set of subcommands defined for this argument parser, referenced by subcommand name.

Returns:
The set of subcommands defined for this argument parser, referenced by subcommand name.

hasSubCommand

public boolean hasSubCommand(java.lang.String name)
Indicates whether this argument parser has a subcommand with the specified name.

Parameters:
name - The subcommand name for which to make the determination.
Returns:
true if this argument parser has a subcommand with the specified name, or false if it does not.

getSubCommand

public SubCommand getSubCommand(java.lang.String name)
Retrieves the subcommand with the specified name.

Parameters:
name - The name of the subcommand to retrieve.
Returns:
The subcommand with the specified name, or null if no such subcommand is defined.

getSubCommand

public SubCommand getSubCommand()
Retrieves the subcommand that was selected in the set of command-line arguments.

Returns:
The subcommand that was selected in the set of command-line arguments, or null if none was selected.

getRawArguments

public java.lang.String[] getRawArguments()
Retrieves the raw set of arguments that were provided.

Overrides:
getRawArguments in class ArgumentParser
Returns:
The raw set of arguments that were provided, or null if the argument list has not yet been parsed.

addGlobalArgument

public void addGlobalArgument(Argument argument)
                       throws ArgumentException
Adds the provided argument to the set of global arguments handled by this parser.

Parameters:
argument - The argument to be added.
Throws:
ArgumentException - If the provided argument conflicts with another global or subcommand argument that has already been defined.

addGlobalArgument

public void addGlobalArgument(Argument argument,
                              ArgumentGroup group)
                       throws ArgumentException
Adds the provided argument to the set of global arguments handled by this parser.

Parameters:
argument - The argument to be added.
group - The argument group to which the argument belongs.
Throws:
ArgumentException - If the provided argument conflicts with another global or subcommand argument that has already been defined.

removeGlobalArgument

protected void removeGlobalArgument(Argument argument)
Removes the provided argument from the set of global arguments handled by this parser.

Parameters:
argument - The argument to be removed.

setUsageArgument

public void setUsageArgument(Argument argument,
                             java.io.OutputStream outputStream)
Sets the provided argument as one which will automatically trigger the output of full usage information if it is provided on the command line and no further argument validation will be performed.

If sub-command groups are defined using the setUsageGroupArgument(Argument, Collection) method, then this usage argument, when specified, will result in usage information being displayed which does not include information on sub-commands.

Note that the caller will still need to add this argument to the parser with the addGlobalArgument(Argument) method, and the argument should not be required and should not take a value. Also, the caller will still need to check for the presence of the usage argument after calling parseArguments(String[]) to know that no further processing will be required.

Overrides:
setUsageArgument in class ArgumentParser
Parameters:
argument - The argument whose presence should automatically trigger the display of full usage information.
outputStream - The output stream to which the usage information should be written.

setUsageGroupArgument

public void setUsageGroupArgument(Argument argument,
                                  java.util.Collection<SubCommand> subCommands)
Sets the provided argument as one which will automatically trigger the output of partial usage information if it is provided on the command line and no further argument validation will be performed.

Partial usage information will include a usage synopsis, a summary of each of the sub-commands listed in the provided sub-commands collection, and a summary of the global options.

Note that the caller will still need to add this argument to the parser with the addGlobalArgument(Argument) method, and the argument should not be required and should not take a value. Also, the caller will still need to check for the presence of the usage argument after calling parseArguments(String[]) to know that no further processing will be required.

Parameters:
argument - The argument whose presence should automatically trigger the display of partial usage information.
subCommands - The list of sub-commands which should have their usage displayed.

parseArguments

public void parseArguments(java.lang.String[] rawArguments)
                    throws ArgumentException
Parses the provided set of arguments and updates the information associated with this parser accordingly.

Overrides:
parseArguments in class ArgumentParser
Parameters:
rawArguments - The raw set of arguments to parse.
Throws:
ArgumentException - If a problem was encountered while parsing the provided arguments.

parseArguments

public void parseArguments(java.lang.String[] rawArguments,
                           java.lang.String propertiesFile,
                           boolean requirePropertiesFile)
                    throws ArgumentException
Parses the provided set of arguments and updates the information associated with this parser accordingly. Default values for unspecified arguments may be read from the specified properties file.

Overrides:
parseArguments in class ArgumentParser
Parameters:
rawArguments - The set of raw arguments to parse.
propertiesFile - The path to the properties file to use to obtain default values for unspecified properties.
requirePropertiesFile - Indicates whether the parsing should fail if the provided properties file does not exist or is not accessible.
Throws:
ArgumentException - If a problem was encountered while parsing the provided arguments or interacting with the properties file.

parseArguments

public void parseArguments(java.lang.String[] rawArguments,
                           java.util.Properties argumentProperties)
                    throws ArgumentException
Parses the provided set of arguments and updates the information associated with this parser accordingly. Default values for unspecified arguments may be read from the specified properties if any are provided.

Overrides:
parseArguments in class ArgumentParser
Parameters:
rawArguments - The set of raw arguments to parse.
argumentProperties - A set of properties that may be used to provide default values for arguments not included in the given raw arguments.
Throws:
ArgumentException - If a problem was encountered while parsing the provided arguments.

getSubCommandUsage

public void getSubCommandUsage(MessageBuilder buffer,
                               SubCommand subCommand)
Appends usage information for the specified subcommand to the provided buffer.

Parameters:
buffer - The buffer to which the usage information should be appended.
subCommand - The subcommand for which to display the usage information.

getUsage

public java.lang.String getUsage()
Retrieves a string containing usage information based on the defined arguments.

Overrides:
getUsage in class ArgumentParser
Returns:
A string containing usage information based on the defined arguments.

getHelpUsageReference

public Message getHelpUsageReference()
Retrieves a string describing how the user can get more help.

Returns:
A string describing how the user can get more help.

getTrailingArguments

public java.util.ArrayList<java.lang.String> getTrailingArguments()
Retrieves the set of unnamed trailing arguments that were provided on the command line.

Overrides:
getTrailingArguments in class ArgumentParser
Returns:
The set of unnamed trailing arguments that were provided on the command line.

usageOrVersionDisplayed

public boolean usageOrVersionDisplayed()
Indicates whether the usage information has been displayed to the end user either by an explicit argument like "-H" or "--help", or by a built-in argument like "-?".

Overrides:
usageOrVersionDisplayed in class ArgumentParser
Returns:
true if the usage information has been displayed, or false if not.

getUsage

public void getUsage(java.io.OutputStream outputStream)
              throws java.io.IOException
Writes usage information based on the defined arguments to the provided output stream.

Overrides:
getUsage in class ArgumentParser
Parameters:
outputStream - The output stream to which the usage information should be written.
Throws:
java.io.IOException - If a problem occurs while attempting to write the usage information to the provided output stream.

isUsageArgumentPresent

public boolean isUsageArgumentPresent()
Returns whether the usage argument was provided or not. This method should be called after a call to parseArguments.

Overrides:
isUsageArgumentPresent in class ArgumentParser
Returns:
true if the usage argument was provided and false otherwise.

isVersionArgumentPresent

public boolean isVersionArgumentPresent()
Returns whether the version argument was provided or not. This method should be called after a call to parseArguments.

Overrides:
isVersionArgumentPresent in class ArgumentParser
Returns:
true if the version argument was provided and false otherwise.