org.glassfish.pfl.basic.tools.argparser

Class ArgParser

java.lang.Object

org.glassfish.pfl.basic.tools.argparser.ArgParser

public class ArgParser
extends Object

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

Author:

Ken Cavanaugh

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ArgParser.StringPair Useful utility class for parsing pairs of strings.

Constructor Summary

Constructors

Constructor and Description
ArgParser(Class<?> cls) Construct an ArgParser that parses an argument string into an instance of the Class argument.
ArgParser(List<Class<?>> classes)

Method Summary

Methods

Modifier and Type	Method and Description
String	getHelpText() Returns a formatted text string that describes the expected arguments for this parser.
static void	main(String[] args)
Object	parse(String[] args) Parse the argument string into an instance of type T.
<T> T	parse(String[] args, Class<T> cls)

Methods inherited from class java.lang.Object

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

Constructor Detail

ArgParser

public ArgParser(Class<?> cls)

Construct an ArgParser that parses an argument string into an instance of the Class argument. cls must be an interface. Each method in this interface must take no arguments. Each method must be annotated with a DefaultValue annotation. Each method must return one of the following types:

• A primitive type
• A String type
• A type that has a public constructor that takes a single String argument
• An Enum
• A List parameterized by one of the above types
• An array of one of the first four types

The name of the method is the name of the keyword.

ArgParser

public ArgParser(List<Class<?>> classes)

Method Detail

getHelpText

public String getHelpText()

Returns a formatted text string that describes the expected arguments for this parser.

parse

public Object parse(String[] args)

Parse the argument string into an instance of type T.

parse

public <T> T parse(String[] args,
          Class<T> cls)

main

public static void main(String[] args)