A general purpose argument parser that uses annotations, reflection, and generics.

This class solves a simple problem: How do I write an argument parser that parses arguments of the form

-xxx value

There are many ways of doing this: the ORB has probably at least 6 different ways of attacking this problem (and I wrote half of them). The approach taken here is to start with an interface, annotate it to indicate some information (like default values) for parsing, and then use reflection to produce an implementation of the interface that uses a dynamic proxy.

The argument parsing is entirely specified in terms of an interface with annotated methods. The name of the method is the name used as a -xxx argument when parsing the data. The type of data determines the valid inputs for the argument. All arguments must be in the -xxx yyy form, where yyy is a valid input for the type of method xxx() in the interface.

The interface is very simply: just create an ArgParser of the appropriate type, and then call parse( String[] ) to get an instance of the interface. There is also a getHelpText() method that returns a String with formatted information about all the valid arguments for this parser.

Not all required information can be derived from the method type and name. Some annotations are defined for additional information:

1. @DefaultValue. This gives a String that is used to construct a default value for the given method.
2. @Separator. This is used to override the default "," separator used for lists of values for fields of type List<Type> or Type[].
3. @Help. This is used to give any help text for the field that is displayed by the getHelpText method.

TODO:

1. Support I18N for this (required before it could be used for public parts of the ORB).
2. Support Set<Type> Similar to list, but all elements must be unique.
3. Support Map<Type,Type>
4. Do we want to support really complex types, like Map<String,List<Map<String,Foo>>> How would we specify needed separators?
5. Should we extend along the lines of the ORB arg parser, with an embedded language to describe how to parse a String?
6. Extend this to support property parsing as well (required for ORB.init parsing). Probably just want to parse Properties as well as String[]. This requires some way to handle the property prefix (as in -ORBInitHost and org.omg.CORBA.ORBInitHost).
7. Extend to support abstract classes. Only non-private abstract methods that are read-only beans and are annotated with @DefaultValue can be set by the parser. Other methods are allowed, but not used by the parser.
8. Support an @Complete annotation. All such methods must be void(), and are executed in some order after the parsing is complete.
9. Add an @Keyword notation to override the default name of the argument (the method name). This allows having different names for the methods and the arguments. Note that this can be used for fully-qualified property names. This supports the ORB dual use of properties and arguments (with perhaps a little fudging for things like ORBInitRef: if there are multiple args, concat them together and use a list separator?)
10. Add an @ClassName annotation that takes no arguments. This means that the string passed must be the name of a class that has a no-args constructor. The class must be assignment compatible with the return type of the annotated method. At parse time, we just load the class named by the string and create a new instance of it.
11. Consider using apt for this. This solves two problems:
    1. We can generate a more efficient class than the current version that uses a dynamic proxy and a table lookup. This becomes important when we consider that ORBData may be referenced many times during an invocation.
    2. We can generate much of the required ORBConstants (say as ORBPropertyNames) directly from the annotated interface.
12. Most of the extensions here are aimed at reducing the code size of the ORB data stuff.
13. If we don't want to use apt:
    1. Use codegen to generate a class that implements the argument interface.
    2. Instead of generating ORBConstants, look things up from it using static reflection on the name of the constant. This would require some other annotations:
       1. @IndirectKeyword gives the name of the constant in the @ConstantClass to look for. Do we need multiple constant classes?
       2. @ConstantClass would give the class to use for looking up public static final constants for @IndirectKeyword, which is like @Keyword.

Summary of current and proposed annotations:

1. @DefaultValue: current method-level takes string
2. @Separator: current method-level takes string
3. @Help: current method-level takes string
4. @ConstantClass: proposed class-level takes class constant
5. @Complete: proposed method-level marker
6. @Keyword: proposed method-level takes string
7. @IndirectKeyword: proposed method-level takes string
8. @ClassName: proposed method-level marker