Command Line and IDE Development Environments

A small Java program may fit in a single class file, but a real program is usually spread across many files. Once that happens, the program becomes awkward to hand over. Someone receiving it would need every class file and every resource file, and they would need to keep all of them in the right places. Java solves this with 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.

This article follows one question through the whole process: what has to be true about a jar file for it to run directly? Keep that question in mind as you read. You will see that the answer depends on a single decision, and that the same decision appears whether you build the jar on the command line or in an IDE.

The source describes two properties that a jar can have. The first is that a jar can hold many classes and resource files together. The second is that the program can then be run directly from that jar, without unpacking it first. A jar that can be started this way is called an executable jar. It specifies the class that contains the main() routine to run when the jar is executed.

If an executable jar needs no resources beyond what it already contains, it can be started from the command line with the java command and the -jar option. The source also notes that you may 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 at launch time: the name of the class that contains the main program, added to the end of the same command.

Both kinds of jar hold classes and resource files, and both can be built with either the command line or an IDE. The difference lies in what the jar tells the Java runtime about where to begin. A regular jar leaves that choice to whoever launches it, so the main class must be named on the launch command. An executable jar records the entry point inside the build, so the launch command can be shorter.

On the command line, the jar program comes with the Java Development Kit. Two forms of the command matter here. The regular form is jar cf JarFileName.jar *.class, and the executable form is jar -c -f JarFileName.jar -e MyMainClass *.class. Both are shown exactly as the source gives them.

Read the executable command from left to right. The first two options set the mode and the output name: -c means create, and -f names the jar file that will be written. The -e option names the entry point, and its value is the full name of the class to run when the jar is executed. The final argument collects the class files. The source states that the -c option means create and that -f names the jar file that will be written. Together with -e and the file list, those pieces make up the whole command. The executable version adds -e and spells out the options, but the rest of the pattern is the same as the regular form.

The -e option is the bridge between the build command and the launch. When you build an executable jar, the entry point you name becomes part of the jar. The Eclipse export screen labels this part Jar Manifest Specification, and it asks for the Main class. The manifest is the piece of the jar that holds this information, so the launch step can find the right class without being told again.

Follow the flow in the diagram. The launch command gives the jar. The jar's manifest names the class holding main(). That class's main() routine is what runs. The learner-visible consequence is that a regular jar makes you repeat the class name at launch, while an executable jar removes that need because the name is already inside the build.

The way you create a jar depends on your programming environment. The source names two basic routes: the command line and the IDE, an Integrated Development Environment. Any Java IDE should have a command for creating jar files. The source walks through Eclipse as its example, and the steps below follow that description.

When a jar does not behave as expected, the useful question is where in the process the result diverged. Instead of rereading the whole command at once, check it against two checkpoints, in order.

Working through these checkpoints in order tells you the stage where the mismatch began. The first checkpoint separates a packaging problem from a launch problem, and the later checks narrow down which piece of the command is responsible.