de.unkrig.commons.util

Class CommandLineOptions

java.lang.Object

de.unkrig.commons.util.CommandLineOptions

public final class CommandLineOptions
extends java.lang.Object

Parses "command line options" from the args of your main() method and configures a Java bean accordingly.

See Also:

parse(String[], Object)

Method Summary

Modifier and Type	Method and Description
static int	applyCommandLineOption(java.lang.String optionName, java.lang.reflect.Method method, java.lang.String[] args, int optionArgumentIndex, java.lang.Object target) Parses the command line option's arguments from the args and invokes the method.
static java.lang.reflect.Method	getMethodForOption(java.lang.String optionName, java.lang.Class<?> targetClass) Determines the method of targetClass that is applicable for the given optionName.
static java.lang.String[]	parse(java.lang.String[] args, java.lang.Object target) Invokes methods of the target object based on the args.
static void	printResource(java.lang.Class<?> baseClass, java.lang.String relativeResourceName, java.nio.charset.Charset resourceCharset, java.io.PrintStream printStream) Reads (and decodes) the contents of a resource, replaces all occurrences of "${system-property-name}" with the value of the designated system property, and writes the result to the printStream.

Methods inherited from class java.lang.Object

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

Method Detail

parse

public static java.lang.String[] parse(java.lang.String[] args,
                                       java.lang.Object target)
                                throws CommandLineOptionException

Invokes methods of the target object based on the args.

All public methods of the target (including those declared by superclasses) are regarded candidates iff they are annotated with the CommandLineOption annotation.

The possible "names" of the command line option are derived from the name element of the CommandLineOption annotation, or, if that is missing, from the method name (see examples below).

When an element of args equals such a name, then the following elements in args are converted to match the parameter types of the method (see example code below). After that, the method is invoked with the arguments.

Parsing terminates iff either

• The args are exhausted
• The special arg "--" is reached (which is consumed)
• The special arg "-" is reached (which is notconsumed)
• A "normal" command line arguments appears, i.e. one that does not start with "-"

Example:

   public
   class MyMain {

       // ...

       // This one maps to "-font-size <x>" and "--font-size <x>".
       @CommandLineOption public static void
       setFontSize(double size) { System.out.println("fontSize=" + size); }

       // This one maps to "-help" and "--help".
       @CommandLineOption public static void
       help() {}

       // This one maps to "-alpha" and "--alpha".
       @CommandLineOption(name = "alpha") public static void
       method1() {}

       // This one maps to "-beta" and "--gamma".
       @CommandLineOption(name = { "-beta", "--gamma" }) public static void
       method2() {}

       // This one maps to "-foo <a> <b> <c>". (A single dashes may be used instead of the double dash.)
       @CommandLineOption public static void
       foo(int one, String two, java.util.Pattern three) {}

       // This one maps to "--person [ --name <>name> ] [ --age <age> ]". (Single dashes may be used
       // instead of the double dashes.)
       @CommandLineOption public static void
       addPerson(Person p) {}

       public static
       class Person {
           public void setName(String name) {}
           public void setAge(int age) {}
       }
   }

   ...

   final MyMain main = new MyMain();

   String[] args = { "--font-size", "17.5", "a", "b" };
   System.out.println(Arrays.toString(args));           // Prints "[--font-size, 17.5, a, b]".

   args = MainBean.parseCommandLineOptions(args, main); // Prints "fontSize=17.5".

   System.out.println(Arrays.toString(args);            // Prints "[a, b]".
 

Option cardinality

To enforce that a particular command line option must be given a specific number of times, use the cardinality() element of the @CommandLineOption annotation:

   @CommandLineOption(cardinality = CommandLineOption.Cardinality.MANDATORY)
   setColor(String color) {
       this.color = color;
   }
 

For this example, it is now guaranteed that parse(String[], Object) will invoke the "setColor()" method exactly once.

The default value for the command line option cardinality is CommandLineOption.Cardinality.OPTIONAL.

Option groups

To enforce that a particular number of a set of command line options must be given, use the group() element of the @CommandLineOption annotation:

   @CommandLineOption(group = Sources.class)
   setFile(File file) {
       this.file = file;
   }

   @CommandLineOption(group = Sources.class)
   setStdin() {
       this.stdin = true;
   }

   // This interface solely serves as the "connector" between the related command line options; it is (typically)
   // not used otherwise.
   @CommandLineOptionGroup(cardinality = CommandLineOptionGroup.Cardinality.EXACTLY_ONE)
   interface Sources {}
 

For this example, it is now guaranteed that parse(String[], Object) will invoke exactly one of the methods "setFile()" and "setStdin()".

The default value for the command line option group cardinality is ZERO_OR_ONE.

Returns:

The args, less the elements that were parsed as command line options

Throws:

CommandLineOptionException - An error occurred during the parsing; typically a command-line application would print the message of the exception to STDERR and call "System.exit(1)"

getMethodForOption

@Nullable
public static java.lang.reflect.Method getMethodForOption(java.lang.String optionName,
                                                                     java.lang.Class<?> targetClass)

Determines the method of targetClass that is applicable for the given optionName.

Returns:

null iff there is no applicable method

See Also:

CommandLineOptions.Parser.getOption(String, Class)

applyCommandLineOption

public static int applyCommandLineOption(java.lang.String optionName,
                                         java.lang.reflect.Method method,
                                         java.lang.String[] args,
                                         int optionArgumentIndex,
                                         @Nullable
                                         java.lang.Object target)
                                  throws CommandLineOptionException

Parses the command line option's arguments from the args and invokes the method.

Iff the method is a varargs method, then all remaining arguments are converted to an array.

Parameters:

optionArgumentIndex - The position of the first option argument in args

Returns:

The position of the last option argument in args plus one

Throws:

CommandLineOptionException - An error occurred during the parsing

java.lang.AssertionError - The method is not annotated with @CommandLineOption

printResource

public static void printResource(java.lang.Class<?> baseClass,
                                 java.lang.String relativeResourceName,
                                 @Nullable
                                 java.nio.charset.Charset resourceCharset,
                                 java.io.PrintStream printStream)
                          throws java.io.IOException

Reads (and decodes) the contents of a resource, replaces all occurrences of "${system-property-name}" with the value of the designated system property, and writes the result to the printStream.

The resource is found through the baseClass's class loader and the name "package-name/simple-class-name.relativeResourceName", where all periods in the package-name have been replaced with slashes.

To ensure that the resource is decoded with the same charset as it was encoded, you should not use the JVM charset (which could be different in the build environment and the runtime environment).

Parameters:

baseClass - Poses the base for the resource name

relativeResourceName - The name of the resource, relative to the baseClass

resourceCharset - The charset to use for decoding the contents of the resource; null for the JVM default charset

Throws:

java.io.FileNotFoundException - The resource could not be found

java.io.IOException