org.clapper.util.cmdline

Class CommandLineUtility

java.lang.Object

org.clapper.util.cmdline.CommandLineUtility

public abstract class CommandLineUtility
extends java.lang.Object

CommandLineUtility is an abstract base class for command-line utilities. It provides:

• Parameter-parsing logic, with call-outs for custom parameters
• Built-in support for a --logging parameter, which enables logging via the java.util.logging API, by calling Logger.enableLogging()
• Automatic generation of a usage message, with a call-out that permits subclasses to add subclass-specific usage information.
• Automatic reporting of exceptions

To use this class, subclass it, and have the subclass's main() method instantiate the subclass, and then call the resulting object's execute() method. The execute() method (which resides in this base class) will:

• parse the parameters
• call the runCommand() method, which must be provided by the subclass, to initiate processing

Note that this class does not parse options the way GNU getopt() (or even traditional getopt()) does. In particular, it does not permit combining multiple single-character options into one command-line parameter. CommandLineUtility may be extended to support that capability in the future; however, it doesn't do that yet.

Here's a sample subclass. It takes the usual --logging parameter, plus a -v (verbose) flag, a numeric count (-n) and a file name. (Exactly what it does with those parameters is left as an exercise for the reader.)

 
 public class Foo extends CommandLineUtility
 {
     private boolean verbose  = false;
     private int     count    = 1;
     private String  filename = null;

     public static void main (String[] args)
     {
         try
         {
             Foo foo = new Foo();
             foo.execute (args);
         }

         catch (CommandLineUsageException ex)
         {
             // Already reported

             System.exit (1);
         }

         catch (CommandLineException ex)
         {
             System.err.println (ex.getMessage());
             System.exit (1);
         }

         System.exit (0);
     }

     private Foo()
     {
         super();
     }

     protected void runCommand() throws CommandLineUtilityException
     {
         ...
     }

     protected void parseCustomOption (char shortOption,
                                       String longOption,
                                       Iterator<String> it)
         throws CommandLineUsageException,
                NoSuchElementException
     {
         if (longOption.equals ("verbose") || (shortOption == 'v'))
             verbose = true;

         else if (longOption.equals ("count") || (shortOption == 'n'))
             count = parseIntParameter ((String) it.next());

         else
             throw new CommandLineUsageException ("Unknown option: " + option);
     }

     protected void processPostOptionCommandLine (Iterator<String> it)
         throws CommandLineUsageException,
                NoSuchElementException
     {
         filename = it.next();
     }

     protected void getCustomUsageInfo (UsageInfo info)
     {
         info.addOption ('v', "verbose", null, "Enable verbose messages")
         info.addOption ('n', "count", "total", "Read specified file <total> times. Defaults to 1.");
         info.addParameter ("filename", "File to process.", false);
     }
 }
 
 

See Also:

ParameterParser

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	CommandLineUtility() Constructor.

Method Summary

Modifier and Type	Method and Description
void	execute(java.lang.String[] args) Called to initiate execution of the command line utility.
protected void	getCustomUsageInfo(UsageInfo info) Called by parseParams() to get the custom command-line options and parameters handled by the subclass.
protected void	parseCustomOption(char shortOption, java.lang.String longOption, java.util.Iterator<java.lang.String> it) Called by parseParams() to handle any option it doesn't recognize.
protected double	parseDoubleOptionArgument(char shortOption, java.lang.String longOption, java.lang.String value) Convenience method that parses a double option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected double	parseDoubleOptionArgument(char shortOption, java.lang.String longOption, java.lang.String value, double min, double max) Convenience method that parses a double floating point option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected double	parseDoubleParameter(java.lang.String value) Convenience method that parses a double value, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected double	parseDoubleParameter(java.lang.String value, double min, double max) Convenience method that parses a double value, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected float	parseFloatOptionArgument(char shortOption, java.lang.String longOption, java.lang.String value) Convenience method that parses a float point option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected float	parseFloatOptionArgument(char shortOption, java.lang.String longOption, java.lang.String value, float min, float max) Convenience method that parses a floating point option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected float	parseFloatParameter(java.lang.String value) Convenience method that parses a floating point value, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected float	parseFloatParameter(java.lang.String value, float min, float max) Convenience method that parses a floating point value, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected int	parseIntOptionArgument(char shortOption, java.lang.String longOption, java.lang.String value) Convenience method that parses an integer option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected int	parseIntOptionArgument(char shortOption, java.lang.String longOption, java.lang.String value, int min, int max) Convenience method that parses an integer option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected int	parseIntParameter(java.lang.String value) Convenience method that parses an integer value, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected int	parseIntParameter(java.lang.String value, int min, int max) Convenience method that parses an integer value, throwing a CommandLineUsageException, not a NumberFormatException, on error.
protected void	processPostOptionCommandLine(java.util.Iterator<java.lang.String> it) Called by parseParams() once option parsing is complete, this method must handle any additional parameters on the command line.
protected abstract void	runCommand() Actually runs the command.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CommandLineUtility

protected CommandLineUtility()

Constructor. Initializes this base class.

Method Detail

execute

public final void execute(java.lang.String[] args)
                   throws CommandLineException

Called to initiate execution of the command line utility. This method

• parse the parameters
• call the runCommand() method, which must be provided by the subclass, to initiate processing.

Parameters:

args - The command-line parameters

Throws:

CommandLineException - command failed

parseCustomOption

protected void parseCustomOption(char shortOption,
                                 java.lang.String longOption,
                                 java.util.Iterator<java.lang.String> it)
                          throws CommandLineUsageException,
                                 java.util.NoSuchElementException

Called by parseParams() to handle any option it doesn't recognize. If the option takes any parameters, the overridden method must extract the parameter by advancing the supplied Iterator (which returns String objects). This default method simply throws an exception.

Parameters:

shortOption - the short option character, or UsageInfo.NO_SHORT_OPTION if there isn't one (i.e., if this is a long-only option).

longOption - the long option string, without any leading "-" characters, or null if this is a short-only option

it - the Iterator for the remainder of the command line, for extracting parameters.

Throws:

CommandLineUsageException - on error

java.util.NoSuchElementException - overran the iterator (i.e., missing parameter)

processPostOptionCommandLine

protected void processPostOptionCommandLine(java.util.Iterator<java.lang.String> it)
                                     throws CommandLineUsageException,
                                            java.util.NoSuchElementException

Called by parseParams() once option parsing is complete, this method must handle any additional parameters on the command line. It's not necessary for the method to ensure that the iterator has the right number of strings left in it. If you attempt to pull too many parameters from the iterator, it'll throw a NoSuchElementException, which parseParams() traps and converts into a suitable error message. Similarly, if there are any parameters left in the iterator when this method returns, parseParams() throws an exception indicating that there are too many parameters on the command line.

This method is called unconditionally, even if there are no parameters left on the command line, so it's a useful place to do post-option consistency checks, as well.

Parameters:

it - the Iterator for the remainder of the command line

Throws:

CommandLineUsageException - on error

java.util.NoSuchElementException - attempt to iterate past end of args; parseParams() automatically handles this exception, so it's safe for subclass implementations of this method not to handle it

getCustomUsageInfo

protected void getCustomUsageInfo(UsageInfo info)

Called by parseParams() to get the custom command-line options and parameters handled by the subclass. This list is used solely to build a usage message. The overridden method must fill the supplied UsageInfo object:

• Each parameter must be added to the object, via the UsageInfo.addParameter() method.
• Each option must be added to the object, via the UsageInfo.addOption() method.

That information will be combined with the common options supported by the base class, and used to build a usage message.

Parameters:

info - The UsageInfo object to fill.

See Also:

UsageInfo.addOption(char, java.lang.String, java.lang.String), UsageInfo.addParameter(java.lang.String, java.lang.String, boolean)

runCommand

protected abstract void runCommand()
                            throws CommandLineException

Actually runs the command. All subclasses are required to provide this method.

Throws:

CommandLineException - on error

parseIntParameter

protected int parseIntParameter(java.lang.String value)
                         throws CommandLineUsageException

Convenience method that parses an integer value, throwing a CommandLineUsageException, not a NumberFormatException, on error.

Parameters:

value - the string value to parse

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseIntParameter(String,int,int), parseIntOptionArgument(char,String,String), parseDoubleParameter(String), parseFloatParameter(String)

parseIntParameter

protected int parseIntParameter(java.lang.String value,
                                int min,
                                int max)
                         throws CommandLineUsageException

Convenience method that parses an integer value, throwing a CommandLineUsageException, not a NumberFormatException, on error. This version of the method also does range checking.

Parameters:

value - the string value to parse

min - the minimum legal value for the result

max - the maximum legal value for the result

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseIntParameter(String), parseIntOptionArgument(char,String,String,int,int), parseDoubleParameter(String,double,double), parseFloatParameter(String,float,float)

parseIntOptionArgument

protected int parseIntOptionArgument(char shortOption,
                                     java.lang.String longOption,
                                     java.lang.String value)
                              throws CommandLineUsageException

Convenience method that parses an integer option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.

Parameters:

shortOption - short option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

longOption - long option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

value - the string value to parse

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseIntOptionArgument(char,String,String,int,int), parseDoubleOptionArgument(char,String,String), parseFloatOptionArgument(char,String,String)

parseIntOptionArgument

protected int parseIntOptionArgument(char shortOption,
                                     java.lang.String longOption,
                                     java.lang.String value,
                                     int min,
                                     int max)
                              throws CommandLineUsageException

Convenience method that parses an integer option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error. This version of the method also does range checking.

Parameters:

shortOption - short option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

longOption - long option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

value - the string value to parse

min - the minimum legal value for the result

max - the maximum legal value for the result

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseIntOptionArgument(char,String,String,int,int), parseDoubleOptionArgument(char,String,String), parseFloatOptionArgument(char,String,String)

parseFloatParameter

protected float parseFloatParameter(java.lang.String value)
                             throws CommandLineUsageException

Convenience method that parses a floating point value, throwing a CommandLineUsageException, not a NumberFormatException, on error.

Parameters:

value - the string value to parse

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseFloatParameter(String,float,float), parseFloatOptionArgument(char,String,String), parseDoubleParameter(String), parseIntParameter(String)

parseFloatParameter

protected float parseFloatParameter(java.lang.String value,
                                    float min,
                                    float max)
                             throws CommandLineUsageException

Convenience method that parses a floating point value, throwing a CommandLineUsageException, not a NumberFormatException, on error. This version of the method also does range checking.

Parameters:

value - the string value to parse

min - the minimum legal value for the result

max - the maximum legal value for the result

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseFloatParameter(String), parseFloatOptionArgument(char,String,String,float,float), parseDoubleParameter(String,double,double), parseIntParameter(String,int,int)

parseFloatOptionArgument

protected float parseFloatOptionArgument(char shortOption,
                                         java.lang.String longOption,
                                         java.lang.String value)
                                  throws CommandLineUsageException

Convenience method that parses a float point option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.

Parameters:

shortOption - short option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

longOption - long option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

value - the string value to parse

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseFloatOptionArgument(char,String,String,float,float), parseDoubleOptionArgument(char,String,String), parseIntOptionArgument(char,String,String)

parseFloatOptionArgument

protected float parseFloatOptionArgument(char shortOption,
                                         java.lang.String longOption,
                                         java.lang.String value,
                                         float min,
                                         float max)
                                  throws CommandLineUsageException

Convenience method that parses a floating point option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error. This version of the method also does range checking.

Parameters:

shortOption - short option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

longOption - long option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

value - the string value to parse

min - the minimum legal value for the result

max - the maximum legal value for the result

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseFloatOptionArgument(char,String,String,float,float), parseDoubleOptionArgument(char,String,String), parseIntOptionArgument(char,String,String)

parseDoubleParameter

protected double parseDoubleParameter(java.lang.String value)
                               throws CommandLineUsageException

Convenience method that parses a double value, throwing a CommandLineUsageException, not a NumberFormatException, on error.

Parameters:

value - the string value to parse

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseDoubleParameter(String,double,double), parseDoubleOptionArgument(char,String,String), parseFloatParameter(String), parseIntParameter(String)

parseDoubleParameter

protected double parseDoubleParameter(java.lang.String value,
                                      double min,
                                      double max)
                               throws CommandLineUsageException

Convenience method that parses a double value, throwing a CommandLineUsageException, not a NumberFormatException, on error. This version of the method also does range checking.

Parameters:

value - the string value to parse

min - the minimum legal value for the result

max - the maximum legal value for the result

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseDoubleParameter(String), parseDoubleOptionArgument(char,String,String,double,double), parseFloatParameter(String,float,float), parseIntParameter(String,int,int)

parseDoubleOptionArgument

protected double parseDoubleOptionArgument(char shortOption,
                                           java.lang.String longOption,
                                           java.lang.String value)
                                    throws CommandLineUsageException

Convenience method that parses a double option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error.

Parameters:

shortOption - short option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

longOption - long option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

value - the string value to parse

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseDoubleOptionArgument(char,String,String,double,double), parseDoubleOptionArgument(char,String,String), parseIntOptionArgument(char,String,String)

parseDoubleOptionArgument

protected double parseDoubleOptionArgument(char shortOption,
                                           java.lang.String longOption,
                                           java.lang.String value,
                                           double min,
                                           double max)
                                    throws CommandLineUsageException

Convenience method that parses a double floating point option argument, throwing a CommandLineUsageException, not a NumberFormatException, on error. This version of the method also does range checking.

Parameters:

shortOption - short option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

longOption - long option, as passed to parseCustomOption(char, java.lang.String, java.util.Iterator<java.lang.String>)

value - the string value to parse

min - the minimum legal value for the result

max - the maximum legal value for the result

Returns:

the numeric value

Throws:

CommandLineUsageException - bad numeric value

See Also:

parseDoubleOptionArgument(char,String,String,double,double), parseDoubleOptionArgument(char,String,String), parseIntOptionArgument(char,String,String)