The Java Platform Module System (JPMS)

A module is a named group of packages with a declaration, module-info.java, that says which other modules it needs (requires) and which of its packages other code may use (exports). The Java Platform Module System (JPMS), part of Java since Java 9, checks those declarations when code compiles and again when the JVM starts. A package that a module does not export is invisible to every other module, even its public classes: this is strong encapsulation, and reflection into such a package needs an opens directive. You compile modules with javac --module-source-path and run them from the module path with java --module-path mods --module app/com.example.Main. Use modules for libraries whose internals must stay hidden, and to build small runtime images with jlink; plain JARs on the class path keep working beside them.

This lesson splits the shop’s billing program from the JAR lesson into two modules, runs them on Eclipse Temurin 25.0.4.1, and shows the two compile errors that the module system adds.

A module declaration

The program becomes two modules, each in its own folder with its declaration at the top of its sources. kirana.bill, in bill/src, holds the bill and a formatter in an internal package; kirana.app, in app/src, holds the program and declares that it needs kirana.bill:

/** The bill model. Its API is the package com.example.kirana.bill; the internal package stays inside the module. */
module kirana.bill {
    exports com.example.kirana.bill;
}

/** The shop's program. It reads kirana.bill, and so can use the packages kirana.bill exports. */
module kirana.app {
    requires kirana.bill;
}

package com.example.kirana.bill;

import com.example.kirana.bill.internal.Paise;
import java.util.ArrayList;
import java.util.List;

/** A shop's bill: lines of goods, each with a quantity and a price in paise. */
public final class Bill {
    public record Line(String item, int quantity, long paise) {}

    private final String shop;
    private final List<Line> lines = new ArrayList<>();

    public Bill(String shop) {
        this.shop = shop;
    }

    public Bill add(String item, int quantity, long paise) {
        lines.add(new Line(item, quantity, paise));
        return this;
    }

    public List<Line> lines() {
        return List.copyOf(lines);
    }

    public long totalPaise() {
        return lines.stream().mapToLong(l -> l.quantity() * l.paise()).sum();
    }

    /** The total in rupees with Indian digit grouping, such as ₹1,01,340.00. */
    public String total() {
        return shop + ": " + Paise.asRupees(totalPaise());
    }
}

package com.example.kirana.app;

import com.example.kirana.bill.Bill;

public class Main {
    public static void main(String[] args) {
        Bill bill = new Bill("Sharma Kirana Store")
                .add("Basmati rice, 25 kg", 12, 2_450_00)
                .add("Toor dal, 30 kg", 4, 4_875_00)
                .add("Sugar, 50 kg", 10, 2_250_00);
        System.out.println(bill.lines().size() + " lines, " + bill.total());
        System.out.println("Main is in module " + Main.class.getModule().getName()
                + ", Bill in module " + Bill.class.getModule().getName());
    }
}

A declaration holds directives, and these are all of them:

Compile and run two modules

from session import run

# How many modules the JDK itself has; then two modules compiled with one javac command, each from its own folder,
# run from the output folder, packed as modular JARs, described, and run again from the JARs.
run(
    """
java --list-modules | wc -l
javac -d out --module-source-path kirana.bill=bill/src --module-source-path kirana.app=app/src --module kirana.app
find out -name "*.class" | sort
java --module-path out --module kirana.app/com.example.kirana.app.Main
jar --create --file mods/kirana.bill.jar -C out/kirana.bill .
jar --create --file mods/kirana.app.jar --main-class com.example.kirana.app.Main -C out/kirana.app .
jar --describe-module --file mods/kirana.bill.jar
jar --describe-module --file mods/kirana.app.jar
java --module-path mods --module kirana.app
"""
)

# openjdk version "25.0.4.1" LTS
$ java --list-modules | wc -l
      69
$ javac -d out --module-source-path kirana.bill=bill/src --module-source-path kirana.app=app/src --module kirana.app
$ find out -name "*.class" | sort
out/kirana.app/com/example/kirana/app/Main.class
out/kirana.app/module-info.class
out/kirana.bill/com/example/kirana/bill/Bill.class
out/kirana.bill/com/example/kirana/bill/Bill$Line.class
out/kirana.bill/com/example/kirana/bill/internal/Paise.class
out/kirana.bill/module-info.class
$ java --module-path out --module kirana.app/com.example.kirana.app.Main
3 lines, Sharma Kirana Store: ₹71,400.00
Main is in module kirana.app, Bill in module kirana.bill
$ jar --create --file mods/kirana.bill.jar -C out/kirana.bill .
$ jar --create --file mods/kirana.app.jar --main-class com.example.kirana.app.Main -C out/kirana.app .
$ jar --describe-module --file mods/kirana.bill.jar
kirana.bill jar:mods/kirana.bill.jar!/module-info.class
exports com.example.kirana.bill
requires java.base mandated
contains com.example.kirana.bill.internal

$ jar --describe-module --file mods/kirana.app.jar
kirana.app jar:mods/kirana.app.jar!/module-info.class
requires java.base mandated
requires kirana.bill
contains com.example.kirana.app
main-class com.example.kirana.app.Main

$ java --module-path mods --module kirana.app
3 lines, Sharma Kirana Store: ₹71,400.00
Main is in module kirana.app, Bill in module kirana.bill

• The JDK is modules too. This JDK 25 lists 69 modules, from java.base to the jdk.* tools.
• --module-source-path kirana.bill=bill/src says where a module’s sources are. javac’s documentation calls this module-specific form the simpler one when only a few modules are involved. --module kirana.app compiled that module and the module it requires, each into its own folder below out, named after the module.
• --module kirana.app/com.example.kirana.app.Main names a module and its main class. At run time each class reports its own module, so Main and Bill really ran as two modules.
• A modular JAR is a JAR with module-info.class at its root. jar --describe-module reads it back: exports lists the API, contains lists the packages kept inside, and requires java.base mandated is the dependence every module has without writing it. With --main-class recorded, --module kirana.app was enough to start the program.

What strong encapsulation stops

Two copies of the program are compiled against the packed kirana.bill: one imports the formatter from the internal package, and one has a declaration without requires:

from session import run

# kirana.bill is compiled on its own and packed as a modular JAR; then two versions of the program are compiled
# against it: one that uses the internal package, and one whose declaration leaves out the requires directive.
run(
    """
javac -d out/kirana.bill $(find bill/src -name "*.java")
jar --create --file mods/kirana.bill.jar -C out/kirana.bill .
javac -d leaky-out --module-path mods $(find leaky/src -name "*.java")
javac -d noread-out --module-path mods $(find noread/src -name "*.java")
""",
    fails=(
        'javac -d leaky-out --module-path mods $(find leaky/src -name "*.java")',
        'javac -d noread-out --module-path mods $(find noread/src -name "*.java")',
    ),
)

# openjdk version "25.0.4.1" LTS
$ javac -d out/kirana.bill $(find bill/src -name "*.java")
$ jar --create --file mods/kirana.bill.jar -C out/kirana.bill .
$ javac -d leaky-out --module-path mods $(find leaky/src -name "*.java")
leaky/src/com/example/kirana/app/Main.java:4: error: package com.example.kirana.bill.internal is not visible
import com.example.kirana.bill.internal.Paise;
                              ^
  (package com.example.kirana.bill.internal is declared in module kirana.bill, which does not export it)
1 error
[exit status 1]
$ javac -d noread-out --module-path mods $(find noread/src -name "*.java")
noread/src/com/example/kirana/app/Main.java:3: error: package com.example.kirana.bill is not visible
import com.example.kirana.bill.Bill;
                         ^
  (package com.example.kirana.bill is declared in module kirana.bill, but module kirana.app does not read it)
1 error
[exit status 1]

The two errors name two different rules. Exports: Paise is a public class, but its package is “declared in module kirana.bill, which does not export it”, so outside that module the class might as well not exist. Across modules, public means public to the modules that may see the package. Readability: Bill is in an exported package, but “module kirana.app does not read it”, because nothing requires kirana.bill. The JVM checks exports again at run time, for code that javac never saw.

Reflection follows its own rule. exports allows reflection on public members only, and code that reads private fields, as many mapping and serialisation libraries do, needs the package opened to it with opens. The JDK’s own internal packages have been closed to such reflection since Java 17 (JEP 403). The --add-opens option opens one package for one run, and --add-exports does the same for compile-time and run-time access to public types. Code on the class path lives in the unnamed module, which reads every module. A plain JAR on the module path becomes an automatic module, which exports and opens all its packages.

Check yourself

Reflection across modules: opens, open modules and --add-opens, failures reproduced Pro: opens with a Pro, Premium or Ultimate pass

Migrating class-path code: automatic modules, the unnamed module and split packages Pro: opens with a Pro, Premium or Ultimate pass

Exercise: split a three-package app into two modules with minimal exports Pro: opens with a Pro, Premium or Ultimate pass

Key takeaways

• module-info.java names a module, the modules it requires and the packages it exports.
• Compile modules with javac --module-source-path and run them with java --module-path … --module m/main.Class.
• A public class in a package that is not exported cannot be used from another module.
• Code must read a module, through requires, before it can use that module’s exported packages.
• Reflection on private members needs opens; --add-opens opens a package for one run.