-----
  How to use Args4J
  -----
  
Prepare your environment

  Because we only want to have a very small example, we use only one single directory containing all the stuff— sources, class files and the args4j jarfile. You need a JDK 1.5 or higher.

 [[1]] Create a directory args4j-sample this will be our project directory.

 [[1]] Download the latest args4j version from the download page

 [[1]] Extract the args4j-{version}.jar from the archive into the project directory
 
 []

Implementing pure business logic

  Create the business bean <<<Business.java>>>. At this point, it only contains the business logic. To run this logic, we want a <<<run()>>> method.

------------------------------
import java.io.File;

public class Business {

    public String name;
    public File file;

    public void setFile(File f) { 
        if (f.exists()) file = f; 
    }

    public void run() {
        System.out.println("Business-Logic");
        System.out.println("- name: " + name);
        System.out.println("- file: " + ((file!=null) 
                                      ? file.getAbsolutePath() 
                                      : "null"));
    }

}
------------------------------

 Compile the sources

------------------------------
javac -classpath .;args4j-2.0.5.jar Business.java
------------------------------

Start the class

 Now we have three options for setting the field from the command line:

 [[1]] implement a main-method and the command line parsing for our own

 [[1]] implement a main-method and use args4j for parsing

 [[1]] use the starter class

 []

  Okay...because this is a sample, the first method isn't the right solution here ;-) In the first step we just use the <<<Starter>>>.

  Start the class

------------------------------
java -classpath .;args4j-2.0.5.jar -Dmainclass=Business org.kohsuke.args4j.Starter
------------------------------

 and we get

------------------------------
Business-Logic
- name: null
- file: null
------------------------------

 What happened? The starter class had a look into the Java system property <<<mainclass>>> loads that class, instantiates it, and executes their <<<run()>>> method. We provide the <<<classpath>>> so the Java VM could find the starter class and our business class.

 Next, let's try to start the class with arguments:

------------------------------
java -classpath .;args4j-2.0.5.jar -Dmainclass=Business org.kohsuke.args4j.Starter -name "Hrld" -file args4j-2.0.5.jar
------------------------------

 which results in

------------------------------
"-name" is not a valid option
Business
------------------------------

Adding Args4J Annotations

 Well, we don't have any annotations to handle the command line parameters yet. Let's fix that:

------------------------------
    ...
    import org.kohsuke.args4j.Option;
    ...
    @Option(name="-name",usage="Sets a name")
    public String name;
    ...
    @Option(name="-file",usage="Sets a file if that is present")
    public void setFile(File f) { 
    ...
------------------------------

 Recompile and try the start again

------------------------------
Business-Logic
- name: Hello World
- file: C:\temp\args4j-sample\args4j-2.0.5.jar
------------------------------

 So far so good. 
 
 What is with wrong parameters?

------------------------------
java -classpath .;args4j-2.0.5.jar -Dmainclass=Business org.kohsuke.args4j.Starter -wrong
------------------------------

 which outputs

------------------------------
"-wrong" is not a valid option
Business [options]
 -file FILE : Sets a file if that is present
 -name VAL  : Sets a name
------------------------------

 Again—what happened? 
 
 args4j throws a <<<CmdLineException>>> when we wrote an incorrect parameter (<<<-wrong>>>). The starter class catches this and prints a help message: the classname and an <<<[Option]>>> (since we have some <<<@Option>>>s in the code). (Since we don't have an <<<@Argument>>>, that line is not <<<Business [options] arguments>>>.) 
 
 Then it shows the possible options, as given by the parser's <<<printUsage()>>> method. 

 As you can see, we added an <<<@Option>>> to an attribute and to a setter method. Using this with attributes is the simplest way to use args4j. But if you wanted to do some checks (e.g. our file existence check), you could add the annotation to a setter.

Enhancing the parsing

 If you want to have more control over parsing and error handling, don't use the starter. Use <<<CmdLineParser>>> directly. 
 
 Here are the main steps:

------------------------------
    import org.kohsuke.args4j.CmdLineParser;
    import org.kohsuke.args4j.CmdLineException;
    ...
    public static void main(String[] args) {
    	Business bean = new Business();
    	CmdLineParser parser = new CmdLineParser(bean);
    	try {
    		parser.parseArgument(args);
    		bean.run();
        } catch (CmdLineException e) {
            // handling of wrong arguments
            System.err.println(e.getMessage());
            parser.printUsage(System.err);
        }
    }
------------------------------

 Since we're not using the <<<Starter>>>, we also have to supply the main method and start it. So, after compiling, we could start that with:

------------------------------
java -classpath .;args4j-2.0.5.jar Business -name "Hello World" -file args4j-2.0.5.jar
------------------------------

 and we get

------------------------------
Business-Logic
- name: Hello World
- file: C:\temp\args4j-sample\args4j-2.0.5.jar
------------------------------

 The error case from above

------------------------------
java -classpath .;args4j-2.0.5.jar Business -wrong
------------------------------

results in

------------------------------
"-wrong" is not a valid option
 -file FILE : Sets a file if that is present
 -name VAL  : Sets a name
------------------------------