com.nevelex.app.args
Class ArgumentProcessor

java.lang.Object
  |
  +--com.nevelex.app.args.ArgumentProcessor

public class ArgumentProcessor

extends java.lang.Object

SINGLETON object used to processes the consumption of every command-line argument passed in to an application.

This is the equivalent of the Invoker class of the Command Pattern.

Version:

1.0 03/22/2001: Initial Version.,
1.1 04/29/2003: Updated documenation.

Author:

Michel Dalal

Method Summary

static ArgumentCommand	getArgumentCommand(java.lang.String argumentName) Returns the associated ArgumentCommand object for the supplied argumentName.
static void	processArguments(java.lang.String[] args) Processes the argument list.
static void	processArguments(java.lang.String[] args, int startingIndex, int indexLimit) Processes the argument list.
static void	registerArgumentCommand(java.lang.String argument, ArgumentCommand argumentCommand) Registers an ArgumentCommand concrete class to handle the supplied command-line argument.
static void	registerArgumentCommand(java.lang.String argumentLong, java.lang.String argumentShort, ArgumentCommand argumentCommand) Registers an ArgumentCommand concrete class to handle the supplied long and short version of a command-line argument.
static void	setArgumentConsumer(ArgumentConsumer argumentConsumer) Sets the ArgumentConsumer object used to verify that all required arguments have been given on the command-line.

Methods inherited from class java.lang.Object

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

Method Detail

setArgumentConsumer

public static final void setArgumentConsumer(ArgumentConsumer argumentConsumer)

Sets the ArgumentConsumer object used to verify that all required arguments have been given on the command-line. This is NOT a required operation.

Parameters:

argumentConsumer - the ArgumentConsumer concrete instance.

registerArgumentCommand

public static final void registerArgumentCommand(java.lang.String argument,
                                                 ArgumentCommand argumentCommand)

Registers an ArgumentCommand concrete class to handle the supplied command-line argument.

Parameters:

argument - the command-line argument string. (e.g. "--help" or "-h")

argumentCommand - the ArgumentCommand concrete instance.

registerArgumentCommand

public static final void registerArgumentCommand(java.lang.String argumentLong,
                                                 java.lang.String argumentShort,
                                                 ArgumentCommand argumentCommand)

Registers an ArgumentCommand concrete class to handle the supplied long and short version of a command-line argument.

Parameters:

argumentLong - the long version of the command-line argument string. (e.g. "--help" or "--filename")

argumentShort - the short version of the command-line argument string. (e.g. "-h" or "-f")

argumentCommand - the ArgumentCommand concrete instance.

getArgumentCommand

public static final ArgumentCommand getArgumentCommand(java.lang.String argumentName)

Returns the associated ArgumentCommand object for the supplied argumentName.

Parameters:

argumentName - the command-line argument name.

Returns:

the associated ArgumentCommand object for the supplied argumentName. Returns null if the supplied argumentName is not a valid command.

processArguments

public static final void processArguments(java.lang.String[] args,
                                          int startingIndex,
                                          int indexLimit)
                                   throws java.lang.IllegalStateException,
                                          InvalidArgumentException,
                                          MissingArgumentException,
                                          UnknownArgumentException

Processes the argument list. This method does not assume that every string given on the command-line is actually an argument that can be processed.

Here are a few examples:

1. If your application only supports arguments that should be processed via this ArgumentProcessor:
   java JavaApp [options... & arguments...]
   
   This method would be called as follows:
   ArgumentProcessor.processArguments(args, 0, args.length);
   
   This is the default behavior of ArgumentProcessor.processArguments(String[]) method.

2. If your application supports any number of options followed by two required parameters (reqParam1 & reqParam2):
   java JavaApp [options...] <reqParam1> <reqParam2>
   
   This method would be called as follows:
   ArgumentProcessor.processArguments(args, 0, args.length - 2);
   
   

3. If your application supports a required parameter (reqParam1) followed by any number of options followed by two required parameters (reqParam2 & reqParam3):
   java JavaApp <reqParam1> [options...] <reqParam2> <reqParam3>
   
   This method would be called as follows:
   ArgumentProcessor.processArguments(args, 1, args.length - 2);
   
   

Parameters:

args - the command-line arguments to process.

startingIndex - the starting index (inclusinve) into the command-line argument list to begin prcessing.

indexLimit - the ending index (exclusive) at which to terminate command-line argument processing.

Throws:

java.lang.IllegalStateException - thrown if the application is not in the desired state prior to starting or after completing argument processing.

InvalidArgumentException - thrown if the argument does not have all of its required options.

MissingArgumentException - thrown if the argument list did not contain all the required arguments.

UnknownArgumentException - thrown if the argument is not known to the application.

See Also:

processArguments(String[])

processArguments

public static final void processArguments(java.lang.String[] args)
                                   throws java.lang.IllegalStateException,
                                          InvalidArgumentException,
                                          MissingArgumentException,
                                          UnknownArgumentException

Processes the argument list. This method assumes that every string given on the command-line is actually an argument that can be processed. The following command-line would NOT work with this method because the filenames do not have an argument:

java JavaClass inFile outFile

However, the following command line would work because each filename is identified using an argument:

java JavaClass --in inFile --out outFile

Parameters:

args - the command-line arguments to process.

Throws:

java.lang.IllegalStateException - thrown if the application is not in the desired state prior to starting argument processing.

InvalidArgumentException - thrown if the argument does not have all of its required options.

MissingArgumentException - thrown if the argument list did not contain all the required arguments.

UnknownArgumentException - thrown if the argument is not known to this application.

See Also:

processArguments(String[], int, int)