modules

the picture

before java 9, public had one setting: everyone. if your library had a public class in com.acme.internal, anyone could import it, and then you could never change it without breaking them. the package name saying "internal" was a polite request. people ignored it (hi, sun.misc.Unsafe).

a module puts a wall around a jar. think of an office building: the floor plan (module-info.java) says which rooms visitors may walk into (exports), and the visitor list says whose offices you're allowed to visit (requires). rooms not on the plan are still there, staff use them all day. you just can't get in from the lobby.

module shop.orders {
    requires transitive shop.money;   // i need it, and so will anyone who uses me
    exports shop.orders.api;          // the front door
                                      // shop.orders.internal: not listed, so sealed
}

import shop.money.Money;
import shop.orders.api.Orders;
...
Money m = Orders.total(1000);
System.out.println(m);

$ javac -d mods --module-source-path src $(find src -name "*.java")
$ java -p mods -m shop.app/shop.app.Main
$11.80

two words to keep straight:

reads

module A reads module B if A requires B (or gets it implied, below). you can only use types from modules you read.

exports

B makes a package accessible to modules that read it. reading isn't enough: the package also has to be exported.

implied readability

requires transitive B in A means everyone who reads A also reads B. use it when B's types show up in A's public API (Orders.total() returns a Money).

everything a module-info can say

there are only a handful of directives. you'll write the first three 95% of the time.

the module path also gets checked when the JVM starts, not just when you compile. a missing requires dependency is a startup error, not a NoClassDefFoundError an hour into production. reliable configuration, the JEP calls it.

exports vs opens

this is the one that confuses everyone, because there are really two kinds of "access". exports is about compiling and calling: can your code use these types? opens is about reflection: can a framework reach in and touch private fields? jackson filling a private field from JSON, hibernate setting an entity's id, spring injecting into a private field: that's all deep reflection, and it needs opens.

exports shop.orders.internal;

the JDK holds itself to the same rules. java.base exports 58 packages to everyone and keeps the other 138 to itself (57 of those are qualified exports to specific JDK modules). so reaching into String's private bytes doesn't work anymore:

void main() throws Exception {
    var f = String.class.getDeclaredField("value");
    try {
        f.setAccessible(true);
        IO.println("got in");
    } catch (RuntimeException e) {
        IO.println(e.getClass().getSimpleName());
    }
}

InaccessibleObjectException

the JDK is made of modules too

the JDK was the first big project to be modularized (project jigsaw, java 9). it's 69 modules on temurin 25: the java.* ones are the standard API, the jdk.* ones are this JDK's tools and extras.

import java.lang.module.ModuleFinder;
 
void main() {
    var names = ModuleFinder.ofSystem().findAll().stream()
            .map(m -> m.descriptor().name())
            .toList();
    IO.println(names.size() + " modules in this JDK");
    IO.println("java.*: " + names.stream().filter(n -> n.startsWith("java.")).count());
    IO.println("jdk.*:  " + names.stream().filter(n -> n.startsWith("jdk.")).count());
    IO.println("named? " + getClass().getModule().isNamed());
}

69 modules in this JDK
java.*: 22
jdk.*:  47
named? false

that last line: code that isn't in a module (like this file) lives in the unnamed module, which reads everything. that's the compatibility story, and it's the whole next chapter: classpath to module path.

java.base is special: every module reads it without saying so (--describe-module prints it as requires java.base mandated). it's where String, List and Thread live.