org.opends.server.util.args
Class ArgumentParser

java.lang.Object
  extended by org.opends.server.util.args.ArgumentParser
Direct Known Subclasses:
InstallDSArgumentParser, JavaPropertiesToolArgumentParser, LDAPConnectionArgumentParser, SubCommandArgumentParser

public class ArgumentParser
extends java.lang.Object

This class defines a utility that can be used to deal with command-line arguments for applications in a CLIP-compliant manner using either short one-character or longer word-based arguments. It is also integrated with the Directory Server message catalog so that it can display messages in an internationalizeable format, can automatically generate usage information, can detect conflicts between arguments, and can interact with a properties file to obtain default values for arguments there if they are not specified on the command-line.


Field Summary
protected  java.util.Set<ArgumentGroup> argumentGroups
          Set of argument groups.
protected  ArgumentGroup defaultArgGroup
          Group for arguments that have not been explicitly grouped.
protected  ArgumentGroup generalArgGroup
          Group for arguments that are general like help, version etc.
protected  ArgumentGroup ioArgGroup
          Group for arguments that are related to utility input/output like verbose, quite, no-prompt etc.
protected  ArgumentGroup ldapArgGroup
          Group for arguments that are related to utility input/output like verbose, quite, no-prompt etc.
 
Constructor Summary
ArgumentParser(java.lang.String mainClassName, Message toolDescription, boolean longArgumentsCaseSensitive)
          Creates a new instance of this argument parser with no arguments.
ArgumentParser(java.lang.String mainClassName, Message toolDescription, boolean longArgumentsCaseSensitive, boolean allowsTrailingArguments, int minTrailingArguments, int maxTrailingArguments, java.lang.String trailingArgsDisplayName)
          Creates a new instance of this argument parser with no arguments that may or may not be allowed to have unnamed trailing arguments.
 
Method Summary
 void addArgument(Argument argument)
          Adds the provided argument to the set of arguments handled by this parser.
 void addArgument(Argument argument, ArgumentGroup group)
          Adds the provided argument to the set of arguments handled by this parser.
 void addDefaultArgument(Argument argument)
          Adds the provided argument to the set of arguments handled by this parser and puts the arguement in the default group.
 void addGeneralArgument(Argument argument)
          Adds the provided argument to the set of arguments handled by this parser and puts the arguement in the general group.
 void addInputOutputArgument(Argument argument)
          Adds the provided argument to the set of arguments handled by this parser and puts the argument in the input/output group.
 void addLdapConnectionArgument(Argument argument)
          Adds the provided argument to the set of arguments handled by this parser and puts the argument in the LDAP connection group.
 boolean allowsTrailingArguments()
          Indicates whether this parser will allow unnamed trailing arguments.
protected  java.util.Properties checkExternalProperties()
          Check if we have a properties file.
 Argument getArgument(java.lang.String name)
          Retrieves the argument with the specified name.
 Argument getArgumentForLongID(java.lang.String longID)
          Retrieves the argument with the specified long identifier.
 Argument getArgumentForShortID(java.lang.Character shortID)
          Retrieves the argument with the specified short identifier.
 java.util.LinkedList<Argument> getArgumentList()
          Retrieves the list of all arguments that have been defined for this argument parser.
 java.util.HashMap<java.lang.String,Argument> getArgumentsByLongID()
          Retrieves the set of arguments mapped by the long identifier that may be used to reference them.
 java.util.HashMap<java.lang.Character,Argument> getArgumentsByShortID()
          Retrieves the set of arguments mapped by the short identifier that may be used to reference them.
 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.
 int getMaxTrailingArguments()
          Retrieves the maximum number of unnamed trailing arguments that may be provided.
 int getMinTrailingArguments()
          Retrieves the minimum number of unnamed trailing arguments that must be provided.
 java.lang.String[] getRawArguments()
          Retrieves the raw set of arguments that were provided.
protected  ArgumentGroup getStandardGroup(Argument argument)
          Given an argument, returns an appropriate group.
 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.
 void getUsage(java.lang.StringBuilder buffer)
          Appends usage information based on the defined arguments to the provided buffer.
 Message getUsageMessage()
          Retrieves a message containing usage information based on the defined arguments.
 boolean isUsageArgumentPresent()
          Returns whether the usage argument was provided or not.
 boolean isVersionArgumentPresent()
          Returns whether the version argument was provided or not.
 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  boolean printUsageGroupHeaders()
          Indicates whether or not argument group description headers should be printed.
 void setDefaultArgumentGroupDescription(Message description)
          Sets the usage group description for the default argument group.
 void setFilePropertiesArgument(StringArgument argument)
          Sets the provided argument which will be used to identify the file properties.
 void setGeneralArgumentGroupDescription(Message description)
          Sets the usage group description for the general argument group.
 void setInputOutputArgumentGroupDescription(Message description)
          Sets the usage group description for the input/output argument group.
 void setLdapArgumentGroupDescription(Message description)
          Sets the usage group description for the LDAP argument group.
 void setNoPropertiesFileArgument(BooleanArgument argument)
          Sets the provided argument which will be used to identify the file properties.
 void setUsageArgument(Argument argument)
          Sets the provided argument as one which will automatically trigger the output of usage information if it is provided on the command line and no further argument validation will be performed.
 void setUsageArgument(Argument argument, java.io.OutputStream outputStream)
          Sets the provided argument as one which will automatically trigger the output of usage information if it is provided on the command line and no further argument validation will be performed.
 boolean usageOrVersionDisplayed()
          Indicates whether the version or 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 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

argumentGroups

protected java.util.Set<ArgumentGroup> argumentGroups
Set of argument groups.


defaultArgGroup

protected ArgumentGroup defaultArgGroup
Group for arguments that have not been explicitly grouped. These will appear at the top of the usage statement without a header.


ldapArgGroup

protected ArgumentGroup ldapArgGroup
Group for arguments that are related to utility input/output like verbose, quite, no-prompt etc. These will appear toward the bottom of the usage statement.


ioArgGroup

protected ArgumentGroup ioArgGroup
Group for arguments that are related to utility input/output like verbose, quite, no-prompt etc. These will appear toward the bottom of the usage statement.


generalArgGroup

protected ArgumentGroup generalArgGroup
Group for arguments that are general like help, version etc. These will appear at the end of the usage statement.

Constructor Detail

ArgumentParser

public ArgumentParser(java.lang.String mainClassName,
                      Message toolDescription,
                      boolean longArgumentsCaseSensitive)
Creates a new instance of this argument parser with no arguments. Unnamed trailing arguments will not be allowed.

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 long arguments should be treated in a case-sensitive manner.

ArgumentParser

public ArgumentParser(java.lang.String mainClassName,
                      Message toolDescription,
                      boolean longArgumentsCaseSensitive,
                      boolean allowsTrailingArguments,
                      int minTrailingArguments,
                      int maxTrailingArguments,
                      java.lang.String trailingArgsDisplayName)
Creates a new instance of this argument parser with no arguments that may or may not be allowed to have unnamed trailing 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 long arguments should be treated in a case-sensitive manner.
allowsTrailingArguments - Indicates whether this parser allows unnamed trailing arguments to be provided.
minTrailingArguments - The minimum number of unnamed trailing arguments that must be provided. A value less than or equal to zero indicates that no minimum will be enforced.
maxTrailingArguments - The maximum number of unnamed trailing arguments that may be provided. A value less than or equal to zero indicates that no maximum will be enforced.
trailingArgsDisplayName - The display name that should be used as a placeholder for unnamed trailing arguments in the generated usage information.
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.

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.

Returns:
A human-readable description for this tool, or null if none is available.

allowsTrailingArguments

public boolean allowsTrailingArguments()
Indicates whether this parser will allow unnamed trailing arguments. These will be arguments at the end of the list that are not preceded by either a long or short identifier and will need to be manually parsed by the application using this parser. Note that once an unnamed trailing argument has been identified, all remaining arguments will be classified as such.

Returns:
true if this parser allows unnamed trailing arguments, or false if it does not.

getMinTrailingArguments

public int getMinTrailingArguments()
Retrieves the minimum number of unnamed trailing arguments that must be provided.

Returns:
The minimum number of unnamed trailing arguments that must be provided, or a value less than or equal to zero if no minimum will be enforced.

getMaxTrailingArguments

public int getMaxTrailingArguments()
Retrieves the maximum number of unnamed trailing arguments that may be provided.

Returns:
The maximum number of unnamed trailing arguments that may be provided, or a value less than or equal to zero if no maximum will be enforced.

getArgumentList

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

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

getArgument

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

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

getArgumentsByShortID

public java.util.HashMap<java.lang.Character,Argument> getArgumentsByShortID()
Retrieves the set of 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 arguments mapped by the short identifier that may be used to reference them.

getArgumentForShortID

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

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

getArgumentsByLongID

public java.util.HashMap<java.lang.String,Argument> getArgumentsByLongID()
Retrieves the set of 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 arguments mapped by the long identifier that may be used to reference them.

getArgumentForLongID

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

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

getTrailingArguments

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

Returns:
The set of unnamed trailing arguments that were provided on the command line.

getRawArguments

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

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

setDefaultArgumentGroupDescription

public void setDefaultArgumentGroupDescription(Message description)
Sets the usage group description for the default argument group.

Parameters:
description - for the default group

setLdapArgumentGroupDescription

public void setLdapArgumentGroupDescription(Message description)
Sets the usage group description for the LDAP argument group.

Parameters:
description - for the LDAP group

setInputOutputArgumentGroupDescription

public void setInputOutputArgumentGroupDescription(Message description)
Sets the usage group description for the input/output argument group.

Parameters:
description - for the input/output group

setGeneralArgumentGroupDescription

public void setGeneralArgumentGroupDescription(Message description)
Sets the usage group description for the general argument group.

Parameters:
description - for the general group

addArgument

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

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

addDefaultArgument

public void addDefaultArgument(Argument argument)
                        throws ArgumentException
Adds the provided argument to the set of arguments handled by this parser and puts the arguement in the default group.

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

addLdapConnectionArgument

public void addLdapConnectionArgument(Argument argument)
                               throws ArgumentException
Adds the provided argument to the set of arguments handled by this parser and puts the argument in the LDAP connection group.

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

addInputOutputArgument

public void addInputOutputArgument(Argument argument)
                            throws ArgumentException
Adds the provided argument to the set of arguments handled by this parser and puts the argument in the input/output group.

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

addGeneralArgument

public void addGeneralArgument(Argument argument)
                        throws ArgumentException
Adds the provided argument to the set of arguments handled by this parser and puts the arguement in the general group.

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

addArgument

public void addArgument(Argument argument,
                        ArgumentGroup group)
                 throws ArgumentException
Adds the provided argument to the set of 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 argument that has already been defined.

setUsageArgument

public void setUsageArgument(Argument argument)
Sets the provided argument as one which will automatically trigger the output of usage information if it is provided on the command line and no further argument validation will be performed. Note that the caller will still need to add this argument to the parser with the addArgument 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 to know that no further processing will be required.

Parameters:
argument - The argument whose presence should automatically trigger the display of usage information.

setUsageArgument

public void setUsageArgument(Argument argument,
                             java.io.OutputStream outputStream)
Sets the provided argument as one which will automatically trigger the output of usage information if it is provided on the command line and no further argument validation will be performed. Note that the caller will still need to add this argument to the parser with the addArgument 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 to know that no further processing will be required.

Parameters:
argument - The argument whose presence should automatically trigger the display of usage information.
outputStream - The output stream to which the usage information should be written.

setFilePropertiesArgument

public void setFilePropertiesArgument(StringArgument argument)
Sets the provided argument which will be used to identify the file properties.

Parameters:
argument - The argument which will be used to identify the file properties.

setNoPropertiesFileArgument

public void setNoPropertiesFileArgument(BooleanArgument argument)
Sets the provided argument which will be used to identify the file properties.

Parameters:
argument - The argument which will be used to indicate if we have to look for properties file.

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.

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.

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.

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.

checkExternalProperties

protected java.util.Properties checkExternalProperties()
                                                throws ArgumentException
Check if we have a properties file.

Returns:
The properties found in the properties file or null.
Throws:
ArgumentException - If a problem was encountered while parsing the provided arguments.

getUsage

public void getUsage(java.lang.StringBuilder buffer)
Appends usage information based on the defined arguments to the provided buffer.

Parameters:
buffer - The buffer to which the usage information should be appended.

getUsageMessage

public Message getUsageMessage()
Retrieves a message containing usage information based on the defined arguments.

Returns:
A string containing usage information based on the defined arguments.

getUsage

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

Returns:
A string containing usage information based on the defined arguments.

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.

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.

usageOrVersionDisplayed

public boolean usageOrVersionDisplayed()
Indicates whether the version or 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 "-?".

Returns:
true if the usage information has been displayed, or false if not.

getStandardGroup

protected ArgumentGroup getStandardGroup(Argument argument)
Given an argument, returns an appropriate group. Arguments may be part of one of the special groups or the default group.

Parameters:
argument - for which a group is requested
Returns:
argument group appropriate for argument

printUsageGroupHeaders

protected boolean printUsageGroupHeaders()
Indicates whether or not argument group description headers should be printed.

Returns:
boolean where true means print the descriptions

isUsageArgumentPresent

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

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.

Returns:
true if the version argument was provided and false otherwise.