Packages and Class Organization in Java

Suppose you have finished a Java program and want to give it to a friend. A reasonable first step is to gather the compiled class files and resource files into a single jar file and send that along. The catch is that your friend still needs a Java runtime installed on their machine to run it. For most people that is an unlikely situation, unless they are Java developers themselves. Packaging is the problem of closing that gap, so the person receiving the program does not have to prepare a Java environment first.

The Java Development Kit includes a tool called jpackage that is built for this job. It produces an installer that places your program on a machine together with as much Java support as the program needs. This article follows one concrete case from start to finish, so you can see which step produces which artifact and where things can go wrong.

jpackage does not read your source code. It needs a jar file that already contains everything the program needs at run time: the compiled class files and any resource files, such as images. In the example, a network poker game draws on classes from two packages, netgame.common and netgame.fivecarddraw. It also loads an image file named cards.png that lives inside the netgame.fivecarddraw package.

The jar is built in two stages. First, the Java source files are compiled into class files, run from the directory that contains the top-level netgame folder. Then the jar command collects the class files and the image into one archive called Poker.jar. The jar command uses -c to create an archive and -f to name the file that will be created. The image must be listed alongside the class files.

A jar holds the program's compiled code and resources, so it contains everything the program needs except the runtime that executes it. Running the jar still requires Java on the target machine. An installer closes that gap. jpackage bundles a Java virtual machine together with the program, so the person who receives the installer does not need to prepare a Java environment before running the software.

The two constraints that shape every jpackage run also matter here. The resulting files are very large, because they include substantial parts of a Java execution environment. That is why the source describes jpackage as best suited to large, serious applications rather than small utilities. Use it when the benefit of bundling Java for your users outweighs the cost of distributing a big file.

The example command uses four options. Each one answers a different question that jpackage needs answered before it can build anything. A useful way to read the command is to match each option to its question: Where is the jar? Which jar is the program? Which class starts the program? What should the result be called? Once you can answer those four questions for a new program, you can construct a jpackage command for it.

Each option answers one question. --input is where jpackage looks for the jar. --main-jar names the jar within that folder. --main-class names the class with the main program, which tells the installer where the program starts. --name controls what the installer and the program it installs are called. Because the options point at each other, a mismatch between them is a common source of trouble.

jpackage can only make an installer for the type of computer and operating system you are currently using. You cannot run jpackage on Linux and expect a Windows installer. The platform differences come mainly from each operating system's packaging conventions and from the extra software the tool needs.

On MacOS, the author defined an alias that points directly to the jpackage program inside the JDK's installation folder. The source notes that newer versions of MacOS might set jpackage up properly, so the alias may not be needed. On Windows, the source says the tool should work and needs the WiX toolset. The author did not test the Windows path, so treat that claim as unverified.

When a packaging attempt goes wrong, the first question is which stage failed. Each problem belongs to one stage: an incomplete jar, a jpackage run that did not start, or an installer built for the wrong system. Identifying the stage narrows down the fix. The most hidden failure is the one that happens inside the jar stage, because the installer can build without complaint even when the jar is missing an image the program needs.