Running Java Programs From the Command Line

Once a program is spread across several files, it becomes awkward to hand over. Java classes and resource files are often distributed together in a single archive called a jar file, short for java archive. A jar file can hold many classes and resource files at once, so a multi-file program can be packed into one file. The program can then be run directly from that jar, without unpacking it first.

A jar file can be executable, which means it specifies the class that contains the main() routine to run when the jar is executed. If the jar is executable and needs no resources beyond what it already contains, it can be started from the command line with a short command that names only the jar. The source adds that you may even be able to start such a jar by double-clicking its icon in a file browser window.

A jar that is not executable needs one more piece of information: the name of the class that contains the main program, added to the end of the same command. The difference between the two kinds of jar therefore decides whether a main class has to be named at build time, and it also decides what you must type later to start the program.

The jar program comes with the Java Development Kit, and the command-line route to a jar uses it directly. Consider the executable form the source gives. Each piece of the command has a specific job, and you can say what each part contributes once you separate them. The first two options set the mode and the output name. The -e option names the entry point. The file list at the end collects the class files to put into the jar.

Compare this with the earlier non-executable form, jar cf JarFileName.jar *.class. The executable version adds -e and spells out the options, but the rest of the pattern is the same. Reading the two side by side is a good habit: whatever differs between them is what changes the result.

When the class with main() sits inside a package, the -e option still takes the full class name, and the class files in that package must be listed too. The package's subdirectory path appears in the file list, with separators adjusted for the operating system. The example below is an illustration of this rule rather than a command from the source.

The way you create a jar file depends on the programming environment you use. Any Java IDE should have a command for creating jar files. In Eclipse, you create a jar through Export, choosing JAR file, entering a .jar path, and, for an executable jar, entering a Main class on the Jar Manifest Specification screen. Both routes can produce a regular jar or an executable jar, and the choice between the two is what determines whether a main class has to be named.

Most problems with jar files come from a small set of errors. The items below follow the rules the source states, so each correction traces back to something the source says must be true.

When a jar does not behave as expected, the useful question is where in the process the result diverged. There are two checkpoints. First, did the build step produce a jar that contains the files you meant to include? Second, does the jar run the way you expected? Working through these checkpoints in order tells you the stage where the mismatch began. Checking piece by piece is more reliable than rereading the whole command at once, because each option or argument maps to one part of the result.

Read the flowchart as a sequence of questions. A file missing from the jar points to the file list. A missing subdirectory path points to the packages. A jar that is built but does not start, with nothing listed as missing from the jar, points to the executable step, which in the source is the -e option.