Java Program Invocation and Command-Line Arguments

A Java program is started by specifying the name of a Java class on the command-line. For example, let's say you have a class like this:

    public class MyProgram {
        ...

        // The entry-point for my program.
        public static void main(String[] args) {
            ...  // My program's code.
        }
    }

(This code would be stored in MyProgram.java, and compiled by running javac MyProgram.java.)

To run this Java code, you would invoke the Java Virtual Machine (JVM) with this command:

    java MyProgram

The JVM would then load MyProgram.class, and begin executing your program with the main method. This is your program's entry-point.

The main method must be declared in a specific way for the JVM to recognize it. It must be declared public and static, and it must take a single String[] argument and return no value (void). If your class doesn't have a main method with these exact characteristics, then you will get an error when you try to start your Java program:

    java MyProgram
    Exception in thread "main" java.lang.NoSuchMethodError: main

If you see this error, make sure to check whether you have correctly declared your main method. The example code above declares the main method properly.

Command-Line Arguments

Frequently, a Java program needs to handle arguments specified on the command-line. For example, you might want to run your program like this:

    java MyProgram 1234 www.caltech.edu "olive festival"

Somehow, your program needs to be able to access these values from the command-line. The way your program can do this is through the String[] argument passed to your main method. Note that the argument is an array of strings. Each element of the array contains one of the values specified on the command-line.

In the above example, the args array will contain the following values:

• args.length = 3
• args[0] = "1234"
• args[1] = "www.caltech.edu"
• args[2] = "olive festival"

Java program arguments are separated by spaces and tabs, except when an argument is enclosed by double-quotes. For the above command-line invocation, the first two arguments are "1234" and "www.caltech.edu", since the Java VM will divide the argument list based on whitespace. The third argument, "olive festival", is not broken into two separate arguments, since it is enclosed with double-quotes.

Note that leading and trailing whitespace characters are removed from the values stored in the args array. Also, for arguments enclosed with double-quotes, note that the double-quotes are removed.

(If you are used to programming in C or C++, you should also note that there is a difference between how arguments are passed to C and C++ programs, vs. how they are passed to Java programs. In C and C++, argv[0] is the name of the program itself, and argv[1] is the first command-line argument to the program. In Java, args[0] is the first command-line argument to the program, and the name of the program itself is not available.)

Numeric Command-Line Arguments

    public static void main(String[] args) {
        int num = 0;

        ...

        try {
            // Parse the string argument into an integer value.
            num = Integer.parseInt(args[0]);
        }
        catch (NumberFormatException nfe) {
            // The first argument isn't a valid integer.  Print
            // an error message, then exit with an error code.
            System.out.println("The first argument must be an integer.");
            System.exit(1);
        }

        ...  // Code that uses the command-line arguments.
    }
    

There are several important points about this code:

• The most important point is that you must handle invalid inputs! The number parsing functions will throw a java.lang.NumberFormatException when parsing fails. Your programs should not crash when they receive invalid input. Instead, catch the exception, print out a helpful message, and then exit your program with a nonzero error code.

• The second important point about this code is that num is declared and initialized before the try/catch block.

  The variable must be declared before the try/catch block because it will be used after the block completes; if it is declared within the block, it will only be visible within the block.

  The variable must be initialized before the try/catch block because otherwise, the Java compiler will report an "uninitialized variable" error at compilation.

Here is a partial list of the primitive data-types, and functions you can use for parsing command-line arguments of those types. These classes are in the java.lang package, so they are available without needing to specify any import statements in your Java programs. Also, the parsing functions are static, so you don't need to create any new objects to use these functions.