Packages and Classes in Java

Imagine a small command-line tool that only reads text files. It uses a handful of standard classes, yet the runtime it runs on carries the entire standard library along with it. Most of that library is never touched by the tool. This mismatch between what a program uses and what it ships with is the problem that Java modules were introduced to address. Java 9 brought modules in to handle the way large Java programs and the platform itself are organized at the largest scale.

The central question for this article is this: if code is already grouped into classes and packages, what extra grouping did Java need, and what does that grouping let a developer control? The answer starts with where a module sits in the structure of Java code.

A Java module is a collection of packages. It adds one more layer of containment on top of the layers that already existed. Read from the outside inward, the nesting goes: a module holds packages, a package holds classes, and a class holds variables and methods. Each layer contains the one beneath it.

The chain above describes how code is nested, but it does not require every package to be placed in a module. The source is explicit that a package does not have to belong to a module to be used. The standard classes, however, have been divided into a set of modules, so the platform's own code follows the same structure that application developers can now use.

Before modules, marking a class public was a broad promise. Any class in any package could use that class, along with its public variables and methods. Modules change the meaning of public for code placed inside a module. Inside the module where a class is defined, a public class is public. Outside that module, it is not automatically visible.

The control point is the export. A module can explicitly export a package, and doing so makes the public classes in that package accessible from anywhere. That includes other modules and code that belongs to no module at all. Trace the effect on a module with two packages, one exported and one not. Both contain a public class, but only one of those classes is reachable from outside.

Because a package can be left unexported, it can be effectively private. It can serve other packages inside its module while staying invisible to the outside world. In that sense a module hides its internal packages the way a well-designed class hides its implementation details. The module's internal structure becomes a detail that outside code does not need to know about.

The second motivation for modules concerns the size of the standard JRE, which contains all of the standard classes. An application typically uses only a small part of that runtime. Modules make it possible to assemble a smaller custom JRE that includes only the modules the application requires. The JDK provides a jlink command for this purpose.

Once built, the custom runtime can be shipped as a standalone application. People who have not installed a JDK on their machine can still run it. Building it, however, creates responsibilities for the developer. The source is careful to note that the runtime is not portable in the way a single program file might be. Separate runtimes are needed for Windows, macOS, and Linux, just as the JDK itself has platform-specific builds.

The three layers differ in scope and in what they group together. A module groups packages and sits at the outermost layer. A package groups classes. A class groups variables and methods. The table below summarizes these differences, along with the access role each one plays.