You need to parse a simple command line containing optional and required arguments.

Use Commons CLI to parse program arguments. Populate an Options object to configure command-line parsing. Pass the Options class and a String[] of arguments to a CommandLineParser, which parses and returns a CommandLine object capturing the supplied options and parameters.

For the purposes of this recipe, assume that you are attempting to parse a command line with three optional arguments: -h, -v, and -f <filename>. -h prints out a simple help message with usage information and available command-line options, -v runs the program with verbose logging, and -f sends the output of the application to a file. To parse this command line, your main( ) method would resemble the following code:

import org.apache.commons.cli.CommandLineParser;
import org.apache.commons.cli.BasicParser;
import org.apache.commons.cli.Options;
import org.apache.commons.cli.CommandLine;
public static void main(String[] args) throws Exception {
  // Create a Parser
  CommandLineParser parser = new BasicParser( );
  Options options = new Options( );
  options.addOption("h", "help", false, "Print this usage information");
  options.addOption("v", "verbose", false, "Print out VERBOSE information" );
  options.addOption("f", "file", true, "File to save program output to");
  // Parse the program arguments
  CommandLine commandLine = parser.parse( options, args );
  // Set the appropriate variables based on supplied options
  boolean verbose = false;
  String file = "";
  
  if( commandLine.hasOption('h') ) {
    System.out.println( "Help Message")
    System.exit(0);
  }
  if( commandLine.hasOption('v') ) {
    verbose = true;
  }
  if( commandLine.hasOption('f') ) {
    file = commandLine.getOptionValue('f');
  }
}

The Options object tells the CommandLineParser to expect three arguments: -h, -v, and -f. The first argument to options.addOption( ) is the short name or abbreviation of the option, and the second argument is the long name of the argument. When the long name of an option is specified, either may be used as program arguments. For example, a command line specifying short-name arguments, -h -v -f test.xml, is equivalent to a command line specifying long-name arguments, --help --version --file test.xml, and both short- and long-name arguments may be mixed in the same command line. The third argument to options.addOption() specifies whether the option takes a parameter; in the previous example, only the file option expects a parameter. The fourth parameter is a String containing a description of the option for a user.

An Options object may be configured using the options.addOption( ), or an Option object can be created and added to the Options object. The following code is equivalent to the call to options.addOption( ) in the previous example, which adds the help option:

Option helpOption = new Option("h", "Prints this usage information");
helpOption.setLongOpt( "help" );
options.addOption( helpOption );

Both the Options object and the args String[] are passed to parser.parse( ), which returns a CommandLine object. CommandLine captures the supplied program arguments, and provides access to the supplied options and arguments. commandLine.hasOption('h') checks for the presence of the optional help choice, and commandLine.getOptionValue('f') retrieves the filename argument for the file option.

In this recipe, BasicParser , an implementation of CommandLineParser, is used to parse command lines. This implementation allows for mixed short- and long-name options: -f test.xml --help. If you are developing an application that needs to parse arguments using POSIX Conventions, use org.apache.commons.cli.PosixParser instead of BasicParser. If you need to parse arguments using the less strict GNU conventions, use the org.apache.commons.cli.GNUParser.

For background about the differences between POSIX and GNU standards, see Section 4.6 of the "GNU Coding Standards" (http://www.gnu.org/prep/standards_18.html). For information about POSIX syntax guidelines, see Section 12.2, "Utility Syntax Guidelines" of "The Single UNIX Specification Version 3" (http://www.unix-systems.org/online.html), also known as IEEE Standard 1003.1 and ISO/IEC 9945.