Package com.portal.common

Class Options

java.lang.Object
com.portal.common.CommandLineParser
com.portal.common.Options
Direct Known Subclasses:
LoaderOptions
public abstract class Options extends CommandLineParser
This is an abstract class that derives from the CommandLineParser class and is used to impose the following syntactical restrictions on the command line arguments.

  • Restrict the number of leading tokens that are allowed on the command line. The leading tokens are the arguments that precede the first option.
  • Control which options are allowed on the command line, and for each option specify the number and type of values used by that option. In addition, also specify the default values for that option in case the option is not present on the command line.
  • Restrict the number of trailing tokens that are allowed on the command line. The trailing tokens are the arguments that follow the last opion.
  • Because this class knows how many values an option uses it can resolve the ambiguity between the number of values used by the last option and the number of trailing tokens.

    The options defined by this class are:

    -hIf this option is present then the user wants to see the help for the command line program.

    To support the options that are unique to your program you will need to extend this class to support those options. The bulk of the extension can be achieved by adding option definitions for your new options in the constructor of your derived class. The option definitions tell the CommandLineParser.parse method which options are valid and what type of values (if any) they require. If the option definiton classes defined in the Options class don't meet your needs then you can extend OptionDef (or one of it's derived classes) to create an option defintion that will meet your needs. The following example creates two flag options and an integer option.

    // Declare the names or the options.
    final public static String VERBOSE = "-v";
    final public static String DEBUG = "-d";
    final public static String THREADS = "-threads";

    // Add option definitions for this class.
    addOptionDef(new FlagOptionDef(VERBOSE, getStrFromBundle("option.desc.verbose")));
    addOptionDef(new FlagOptionDef(DEBUG, getStrFromBundle("option.desc.debug")));
    addOptionDef(new IntOptionDef(THREADS, 5, getStrFromBundle("option.desc.threads")));

    • Field Details

      • HELP

        public static final String HELP
        The help option. If this option is present on the command line then the program will display help information for the program and then exit.
        See Also:

    • Constructor Details

      • Options

        protected Options(String[] args) throws CommandLineParser.InvalidOptionsException
        This constructor will default to no leading tokens and an indefinite number of trailing tokens.

        You cannot all this constructor directly because you must derive from this class. In the constructor of your derived class you must call the CommandLineParse.parse method after your constructor has finished all initialization. This is because the CommandLineParser.parse method calls the methods overriden in the Options class which depend on the option definitions defined in the constructor of your derived class. All constructor initialization must be complete for the CommandLineParser.parse method to work correctly.

        Parameters:
        args - The array of command line arguments passed to the program.
        Throws:
        CommandLineParser.InvalidOptionsException - An error was encountered when parsing the command line arguments. The error could result from one of the conditions.

        • An incorrect number of leading tokens.
        • An incorrect number of trailing tokens.
        • An undefined option was encountered.
        • An incorrect number of values was associated with the option.
        • A value associated with an option is invalid.
        • A duplicate option was encountered.
        • An undefined option was encountered.

      • Options

        protected Options(String[] args, int numLeadToks, int numTrailToks) throws CommandLineParser.InvalidOptionsException
        Allows the caller to specifiy the number of leading tokens and the number of trailing tokens>.

        You cannot all this constructor directly because you must derive from this class. In the constructor of your derived class you must call the CommandLineParse.parse method after your constructor has finished all initialization. This is because the CommandLineParser.parse method calls the methods overriden in the Options class which depend on the option definitions defined in the constructor of your derived class. All constructor initialization must be complete for the CommandLineParser.parse method to work correctly.

        Parameters:
        args - The array of command line arguments passed to the program.
        numLeadToks - The number of tokens that can exist at the beginning (before any options) of the command line. A value of ALL implies there can be an indefinite number of leading tokens.
        numTrailToks - The number of tokens that can exist at the end (after any options) of the command line. A value of ALL implies there can be an indefinite number of trailing tokens.
        Throws:
        CommandLineParser.InvalidOptionsException - An error was encountered when parsing the command line arguments. The error could result from one of the conditions.

        • An incorrect number of leading tokens.
        • An incorrect number of trailing tokens.
        • An undefined option was encountered.
        • An incorrect number of values was associated with the option.
        • A value associated with an option is invalid.
        • A duplicate option was encountered.
        • An undefined option was encountered.

    • Method Details

      • getString

        public String getString(String optName) throws CommandLineParser.NoSuchOptionException, CommandLineParser.OptionDataException
        Return the 1st value for the option as a string. If there is no value but the option definition has a default value then return the default value, otherwise throw an exception.

        Parameters:
        optName - The option to return the string value for.
        Returns:
        The value or default value for the option as a string.
        Throws:
        CommandLineParser.NoSuchOptionException - There is no option defintion for the specified option.
        CommandLineParser.OptionDataException - There is no value or default value for the option.

      • getBoolean

        public boolean getBoolean(String optName) throws CommandLineParser.NoSuchOptionException, CommandLineParser.OptionDataException
        Return the 1st value for the option as a boolean. If there is no value but the option definition has a default value then return the default value, otherwise throw an exception.

        Parameters:
        optName - The option to return the boolean value for.
        Returns:
        The value or default value for the option as a boolean.
        Throws:
        CommandLineParser.NoSuchOptionException - There is no option defintion for the specified option.
        CommandLineParser.OptionDataException - There is no value or default value for the option or the value (or default value) could not be converted to a boolean value.

      • getInteger

        public Integer getInteger(String optName) throws CommandLineParser.NoSuchOptionException, CommandLineParser.OptionDataException
        Return the 1st value for the option as an integer. If there is no value but the option definition has a default value then return the default value, otherwise throw an exception.

        Parameters:
        optName - The option to return the boolean value for.
        Returns:
        The value or default value for the option as an integer.
        Throws:
        CommandLineParser.NoSuchOptionException - There is no option defintion for the specified option.
        CommandLineParser.OptionDataException - There is no value or default value for the option or the value (or default value) could not be converted to an integer value.

      • getBigDecimal

        public BigDecimal getBigDecimal(String optName) throws CommandLineParser.NoSuchOptionException, CommandLineParser.OptionDataException
        Return the 1st value for the option as a BigDecimal. If there is no value but the option definition has a default value then return the default value, otherwise throw an exception.

        Parameters:
        optName - The option to return the BigDecimal value for.
        Returns:
        The value or default value for the option as a BigDecimal.
        Throws:
        CommandLineParser.NoSuchOptionException - There is no option defintion for the specified option.
        CommandLineParser.OptionDataException - There is no value or default value for the option or the value (or default value) could not be converted to a BigDecimal value.

      • getDate

        public Date getDate(String optName) throws CommandLineParser.NoSuchOptionException, CommandLineParser.OptionDataException
        Return the 1st value for the option as a date. If there is no value but the option definition has a default value then return the default value, otherwise throw an exception.

        Parameters:
        optName - The option to return the date value for.
        Returns:
        The value or default value for the option as a date.
        Throws:
        CommandLineParser.NoSuchOptionException - There is no option defintion for the specified option.
        CommandLineParser.OptionDataException - There is no value or default value for the option or the value (or default value) could not be converted to a date value.

      • getStrings

        public String[] getStrings(String optName) throws CommandLineParser.NoSuchOptionException, CommandLineParser.OptionDataException
        Return the values for the option as an array of strings. If there are no values (the option does not appear on the command line) but the option definition has default values then return the default values.

        Parameters:
        values - The array of values retrieved from the command line for the option.
        Returns:
        the values or default values for the option as an array of strings.
        Throws:
        CommandLineParser.NoSuchOptionException - There is no option defintion for the specified option.
        CommandLineParser.OptionDataException - There are no values or default values for the option.

      • toString

        public String toString()
        Convert this class to a string that will contain the following:
        • The arguments passed to the constructor
        • The leading tokens
        • For each option, the values associated with that option
        • The trailing tokens
        • The option definitions

        Overrides:
        toString in class CommandLineParser
        Returns:
        The string representation of this class.

      • isHelp

        public boolean isHelp()
        Return true if the help option was contained in the command line or the command line is empty.

        Overrides:
        isHelp in class CommandLineParser
        Returns:
        true if the help option was contained in the command line or tthe command line is empty, otherwise false.

      • getHelp

        public String getHelp()
        Get the help string that describes the syntax required by your options class and a desciption of each option used by your class.

        Overrides:
        getHelp in class CommandLineParser
        Returns:
        The appropriate help string.

      • getSyntaxHelp

        protected abstract String getSyntaxHelp()
        Get the help string that describes the syntax required by your options class.

        Returns:
        The appropriate help string.

      • validateLeadingTokens

        protected void validateLeadingTokens(ArrayList tokens) throws CommandLineParser.InvalidOptionsException
        Validate the number of leading tokens passed in the command line.

        Overrides:
        validateLeadingTokens in class CommandLineParser
        Parameters:
        tokens - The list of tokens that appear at the beginning of the command line. The list could be empty.
        Throws:
        CommandLineParser.InvalidOptionsException - There is an error with the number of leading tokens.

      • validateOption

        protected void validateOption(String option, ArrayList values, boolean lastOption) throws CommandLineParser.InvalidOptionsException
        Validate that the option has the correct number of values and that values are of the correct data type. If this is the last option being validated then resolve the ambiguity between option values and trailing tokens. As a side effect this function may alter the number of values stored in values when the last option is validated.

        Overrides:
        validateOption in class CommandLineParser
        Parameters:
        option - The name of the option to validate. This name will include the leading "-" (i.e. "-verbose").
        values - The list of values associated with this option. The list could be empty.
        lastOption - This flag will be true if this is the "last" option contained in the command line.
        Throws:
        CommandLineParser.InvalidOptionsException - The option has not been defined or there is an error with the number of "values" or a particular value is invalid.

      • validateTrailingTokens

        protected void validateTrailingTokens(ArrayList tokens, int numLastOptionArgs) throws CommandLineParser.InvalidOptionsException
        Validate the number of trailing tokens passed in the command line.

        Overrides:
        validateTrailingTokens in class CommandLineParser
        Parameters:
        tokens - The list of tokens that appear at the end of the command line. The list could be empty.
        numLastOptionArgs - The number of arguments "used" by the last option.
        Throws:
        CommandLineParser.InvalidOptionsException - There is an error with the number of trailing tokens.

      • validateRequiredParameters

        protected void validateRequiredParameters() throws CommandLineParser.InvalidOptionsException
        Ensure that all required options were present on the command line.

        Overrides:
        validateRequiredParameters in class CommandLineParser
        Throws:
        CommandLineParser.InvalidOptionsException - A required option was not present on the command line.

      • storeAllTokensAsLeadingTokens

        protected boolean storeAllTokensAsLeadingTokens()
        Override this method if you want to change the default behavior that when a command line only contains tokens (no options) then the tokens will be considered leading tokens and there will be no trailing tokens.

        Overrides:
        storeAllTokensAsLeadingTokens in class CommandLineParser
        Returns:
        trur if the class suuport leading arguments otherwise return false.

      • addOptionDef

        protected final void addOptionDef(Options.OptionDef optDef) throws CommandLineParser.InvalidOptionsException
        Use this method to add option defintions for all of the options that will be supported in your derived class.

        Parameters:
        optDef - The option definiton of an option that will supported in your derived class.
        Throws:
        CommandLineParser.InvalidOptionsException - The value(s) specified for the option are invalid.

      • getOptionDef

        protected final Options.OptionDef getOptionDef(String optName) throws CommandLineParser.NoSuchOptionException
        Helper method used to retrieve an option definition for a particular option.

        Parameters:
        optName - The option to retieve the option defintion for. This name must include the leading "-".

        Throws:
        CommandLineParser.NoSuchOptionException - There is no option defintion for the specified option.

      • getOptValues

        protected String[] getOptValues(String optName)
        Helper method used to get the values that were specified on the command line for the option.

        Parameters:
        optName - The name of the option to return the values for.
        Returns:
        The values that were specified on the command line for the option. If the option did not have any values return an empty array. If the option was not specified on the command line return null.