The main() Method and Program Entry

Command-line arguments are the words typed after a program's name, and Java passes them to main() in the args array of strings.

Programming

Words Typed After the Program Name

Many command-line tools take their input from the same line that starts them. In UNIX, the copy command is a good example. A user does not open a dialog box to say which file to copy. Instead, the user types the names directly after the command name, as in copy original.dat backup.dat. The words after the command name tell the program which existing file to read and what the new file should be called.

A Java program can receive input in exactly the same way. The words that follow the program's name on the command line are called command-line arguments. In this article we follow one concrete case: a program named CopyFile that the user starts with the words work.dat and oldwork.dat after it. The question is what the program actually receives.

What do you think happens?

The user runs java CopyFile work.dat oldwork.dat. Which string does the program find at args[0]?

CopyFile
work.dat
oldwork.dat
java CopyFile work.dat oldwork.dat

Reveal answer

Answer:

work.dat

The program name is not part of args. The first word after the program name is stored at position 0, so args[0] holds work.dat. The second word, oldwork.dat, is stored at position 1.

Before reading the explanation, you may have guessed that the arguments arrive as an ordered collection and that the position of each word determines which element holds it. Both assumptions are what the rest of this article depends on, and both are correct for Java.

How the Typed Words Reach main()

The command-line arguments are stored in an array of strings named args. This array is a parameter to the main() routine. The program does not have to go looking for the user's words. They are handed to main() as an ordinary array that the program can read like any other array.

java

public class CopyFile {
    public static void main(String[] args) {
        // args is the array of command-line arguments
    }
}

public class CopyFile {
    public static void main(String[] args) {
        // args is the array of command-line arguments
    }
}

How does one typed line become separate strings, and how do those strings travel into main()?

Read the diagram from top to bottom. The typed line is the starting point. Each word after the program name becomes a separate string, and those strings are stored in args, which main() receives as its parameter. The program name itself does not appear among the strings in args.

Reading Arguments by Index Position

Each element of args holds one of the words the user typed, as a string. The first word after the program name goes into position 0, the second into position 1, and so on. The program retrieves an argument by asking for the element at that position. Because the positions are fixed by the order of the words, changing the order the user types them changes which file the program treats as the source.

Which typed word lands at which index in args, and why does the program name not appear in args?

The diagram shows the mapping for the example command. Index 0 holds the first word typed after the program name, and index 1 holds the second. The program name CopyFile is not one of the array elements. It identifies the program that is starting, and it is not treated as data for the program to read.

java

public class CopyFile {
    public static void main(String[] args) {
        System.out.println(args[0]);
        System.out.println(args[1]);
    }
}

public class CopyFile {
    public static void main(String[] args) {
        System.out.println(args[0]);
        System.out.println(args[1]);
    }
}

Output

work.dat
oldwork.dat

Notes on the code

args[0] reads the element in position 0, which holds the first typed word
args[1] reads the element in position 1, which holds the second typed word

Using args.length Before Reading Positions

The program cannot know in advance how many file names the user will type, so it asks the array how long it is before deciding how to proceed. args.length gives the number of command-line arguments the user supplied. Its value comes from what the user typed, not from anything written in the program's source.

When the user types two words, then only one, what is args.length and which indices are valid to read?

Worked example

Running CopyFile With Only One Word

The user runs java CopyFile report.dat. What does args hold, and what happens if the program reads args[1]?

1
Count the words
Only one word follows the program name, so args has one element and args.length is 1.
2
Read position 0
args[0] holds report.dat, the first and only typed word.
3
Try position 1
The array has only position 0, so no element exists at index 1. Java reports an ArrayIndexOutOfBoundsException if the program reads args[1] here.
4
Guard the read
Checking args.length before reading args[1] lets the program stop or report a problem instead of failing.

Result

args.length is 1, args[0] is report.dat, and args[1] does not exist, so the program must check args.length before reading the second file name.

java

public class CopyFile {
    public static void main(String[] args) {
        if (args.length < 2) {
            // fewer than two words were typed, so there is no safe second position to read
            return;
        }
        System.out.println(args[0]);
        System.out.println(args[1]);
    }
}

public class CopyFile {
    public static void main(String[] args) {
        if (args.length < 2) {
            // fewer than two words were typed, so there is no safe second position to read
            return;
        }
        System.out.println(args[0]);
        System.out.println(args[1]);
    }
}

Where a Copy Program Goes Wrong

When a copy program misbehaves, trace the path from typed words to array positions to the index the code reads. In the CopyFile example, the problem often appears as a file being copied in the wrong direction, even though the program ran without an error. The typed words were correct, and the array was filled correctly. The fault lies in which index the code chose to read.

Common mistake
Treating the program name as args[0]
What it looks like
The user runs java CopyFile work.dat oldwork.dat and the code reads args[0] expecting CopyFile.
Why it fails
The program name is not stored in args. The first word after it goes to position 0.
Do this instead
Read args[0] as the first word typed after the program name, which is work.dat in this example.
Common mistake
Reading args[1] without checking args.length
What it looks like
The user runs java CopyFile report.dat and the code reads args[1].
Why it fails
Only position 0 exists, so there is no element at index 1.
Do this instead
Check args.length against the number of values the program needs before reading any position.
Common mistake
Assuming the order of the words does not matter
What it looks like
The user types the source first and the destination second, but the code reads them in the opposite positions.
Why it fails
Positions are fixed by the order the words were typed, so swapping the indices swaps the roles of the files.
Do this instead
Match each index in the code to the meaning the program's design gives it, and confirm the order against the typed command.

Finding the Divergence Point

To locate where a program's behavior diverges from what the user typed, follow three links in order: the typed words, the array positions those words occupy, and the index the code actually reads. The divergence is at the first link where the chain breaks.

MEDIUM

A copy program is meant to read the source file from the first word typed and write to the second. Its code reads args[1] as the source and args[0] as the destination. The user runs java CopyFile work.dat oldwork.dat. Which file is treated as the source, and at which link does the behavior diverge from what the user typed?

Hints

Start with the typed words and their positions: work.dat is at args[0] and oldwork.dat is at args[1].
Compare the index the code reads for the source with the index that holds the first typed word.

Your attempt (not saved)

Key Takeaways

Command-line arguments are the words typed after a program's name, and Java passes them to main() in the args array of strings.
The first word after the program name is at args[0], the second at args[1], and so on, in the order the user typed them. The program name itself is not stored in args.
args.length gives the number of command-line arguments supplied, so a program should check it before reading positions that may not exist.
When a copy program misbehaves, trace typed words to array positions to the index the code reads; the divergence is where that chain breaks.

Words Typed After the Program Name

How the Typed Words Reach main()

Reading Arguments by Index Position

Using args.length Before Reading Positions

Where a Copy Program Goes Wrong

Finding the Divergence Point

Key Takeaways

Related Topics