org.kohsuke.args4j
Annotation Type Option


@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface Option

Marks a field/setter that receives a command line switch value.

This annotation can be placed on a field of type T or the method of the form void methodName(T value). Its access modified can be anything, but if it's not public, your application needs to run in a security context that allows args4j to access the field/method (see AccessibleObject.setAccessible(boolean).

The behavior of the annotation differs depending on T --- the type of the field or the parameter of the method.

Boolean Switch

When T is boolean , it represents a boolean option that takes the form of "-OPT". When this option is set, the property will be set to true.

String Switch

When T is String, it represents an option that takes one operand. The value of the operand is set to the property.

Enum Switch

When T is derived from Enum, it represents an option that takes an operand, which must be one of the enum constant. The comparion between the operand and the enum constant name is done in a case insensitive fashion.

For example, the following definition will represent command line options like "-coin penny" or "-coin DIME" but things like "-coin" or "-coin abc" are errors.

 enum Coin { PENNY,NICKEL,DIME,QUARTER }

 class Option {
   @Option(name="-coin")
   public Coin coin;
 }
 

File Switch

When T is a File, it represents an option that takes a file/directory name as an operand.


Required Element Summary
 java.lang.String name
          Name of the option, such as "-foo" or "-bar".
 
Optional Element Summary
 java.lang.String[] aliases
          Aliases for the options, such as "--long-option-name".
 java.lang.Class<? extends OptionHandler> handler
          Specify the OptionHandler that processes the command line arguments.
 java.lang.String metaVar
          When the option takes an operand, the usage screen will show something like this:
 boolean multiValued
          Whether the option is multi-valued.
 boolean required
          Specify that the option is mandatory.
 java.lang.String usage
          Help string used to display the usage screen.
 

Element Detail

name

public abstract java.lang.String name
Name of the option, such as "-foo" or "-bar".

aliases

public abstract java.lang.String[] aliases
Aliases for the options, such as "--long-option-name".

Default:
{}

usage

public abstract java.lang.String usage
Help string used to display the usage screen.

This parameter works in two ways. For a simple use, you can just encode the human-readable help string directly, and that will be used as the message. This is easier, but it doesn't support localization.

For more advanced use, this property is set to a key of a ResourceBundle. The actual message is obtained by querying a ResourceBundle instance supplied to CmdLineParser by this key. This allows the usage screen to be properly localized.

If this value is empty, the option will not be displayed in the usage screen.

Default:
""

metaVar

public abstract java.lang.String metaVar
When the option takes an operand, the usage screen will show something like this:
 -x FOO  : blah blah blah
 
You can replace the 'FOO' token by using this parameter.

If left unspecifiied, this value is infered from the type of the option.

Just like usage(), normally, this value is printed as is. But if a ResourceBundle is given to the CmdLineParser, it will be used to obtain the locale-specific value.

Default:
""

required

public abstract boolean required
Specify that the option is mandatory.

At the end of CmdLineParser.parseArgument(String...), a CmdLineException will be thrown if a required option is not present.

Note that in most of the command line interface design principles, options should be really optional. So use caution when using this flag.

Default:
false

handler

public abstract java.lang.Class<? extends OptionHandler> handler
Specify the OptionHandler that processes the command line arguments.

The default value OptionHandler indicates that the OptionHandler will be infered from the type of the field/method where a Option annotation is placed.

If this annotation element is used, it overrides the inference and determines the handler to be used. This is convenient for defining a non-standard option parsing semantics.

Example

 // this is a normal "-r" option
 @Option(name="-r")
 boolean value;

 // this causes arg4j to use MyHandler, not the default
 // handler provided for boolean
 @Option(name="-b",handler=MyHandler.class)
 boolean value;
 

Default:
org.kohsuke.args4j.spi.OptionHandler.class

multiValued

public abstract boolean multiValued
Whether the option is multi-valued. For mappings to List<...>, this defaults to true, otherwise false

Default:
false