org.josef.util

Class CArguments

java.lang.Object

org.josef.util.CArguments

public class CArguments
extends Object

Processes command line arguments.
Lots of programs will have to process command line arguments and this class tries to support these programs by using a call-back mechanism for arguments and by implementing basic error checking code. Let's take the jar command as an example. It has the following format:
jar {ctxu}[vfm0M] [jar-file] [manifest-file] [-C dir] files ...
c, t, x, u, v, 0 and M are options that do not take any further arguments. We will call these flags. f, m and C are options that take exactly one argument. The following simplified code will process the arguments:

 public class Jar implements ArgumentsHandler {
     public static void main(final String [] args) {
         Jar jar = new Jar();
         CArguments arguments = new CArguments(jar,
             new String [] {"c", "t", "x", "u" "v", "0", "M"},
             new String [] {"f", "m", "C"});
         arguments.processArguments(args);
     }

     public void option(final String name, final String argument) {
         // Handle flags and options here...
     }

     public void programArguments(final String [] arguments) {
         // Handle program arguments (files) here...
     }
 }

The Jar class can now be called like this:
java Jar -cmf manifest.mft file.jar a.class b.class
java Jar -c -m manifest.mft -f file.jar a.class b.class
java Jar a.class b.class -fm -c file.jar manifest.mft
This class will handle all situations gracefully. As you might have noticed it is allowed to supply multiple options like: -cmf. This however is only allowed when all allowable options and flags consist of exactly one letter. Another thing to note is that this class currently does not solve the problem that the user has to choose either: c, t, x or u.
Note: The classes in the util.args take a different approach in handling command line arguments. Annotations are used instead of call back methods. Unfortunately these classes are not yet as mature as CArguments.

Version:

1.0 $Revision: 5814 $

Author:

Kees Schotanus

See Also:

ArgumentsHandler

Constructor Summary

Constructors

Constructor and Description
CArguments(ArgumentsHandler argumentsHandler, String[] flags, String[] options) Creates an arguments object from the supplied arguments handler, flags and options.
CArguments(ArgumentsHandler argumentsHandler, String[] flags, String[] options, boolean allowUnspecifiedOptions) Creates an arguments object from the supplied arguments handler, flags and options.

Method Summary

Modifier and Type	Method and Description
void	parseArguments(String[] arguments) Parses the actual arguments that have been supplied to a program.
String	toString() Creates a String representation of this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

CArguments

public CArguments(ArgumentsHandler argumentsHandler,
                  String[] flags,
                  String[] options)

Creates an arguments object from the supplied arguments handler, flags and options.

Parameters:

argumentsHandler - Object that will receive callbacks for all flags, options and program arguments that are encountered.

flags - All allowable flags.
A flag is an option that does not take any arguments.

options - All allowable options.
An option should have exactly one argument.

Throws:

IllegalArgumentException - When duplicate flags are supplied or when duplicate options are supplied or when a flag and an option with the same name have been supplied.

NullPointerException - When the supplied argumentsHandler is null.

CArguments

public CArguments(ArgumentsHandler argumentsHandler,
                  String[] flags,
                  String[] options,
                  boolean allowUnspecifiedOptions)

Creates an arguments object from the supplied arguments handler, flags and options.

Parameters:

argumentsHandler - Object that will receive callbacks for all flags, options and program arguments that are encountered.

flags - All allowable flags.
A flag is an option that does not take any arguments.

options - All allowable options.
An option should have exactly one argument.

allowUnspecifiedOptions - When the actual command line arguments contain an option that has not been specified in the supplied options array then this option is handled gracefully when true is specified.

Throws:

NullPointerException - When the supplied argumentsHandler is null.

IllegalArgumentException - When duplicate flags are supplied or when duplicate options are supplied or when a flag and an option with the same name have been supplied.

Method Detail

parseArguments

public void parseArguments(String[] arguments)

Parses the actual arguments that have been supplied to a program.
When a flag or option with an argument has been encountered the method ArgumentsHandler.option(String, String) will be called. Even in the absence of program arguments will the method ArgumentsHandler.programArguments(String[]) be called.

Parameters:

arguments - Arguments supplied to the program.
You will normally pass the arguments (args) that have been passed to your main method.

Throws:

IllegalArgumentException - When the actual arguments do not comply with the allowed flags and options.

toString

public String toString()

Creates a String representation of this object.

Overrides:

toString in class Object

Returns:

String representation of this object.