Modules, requires and the encapsulated JDK

Understanding Modules, requires and the encapsulated JDK

A module is a jar or a directory with a name and one extra file at its root, module-info.class, compiled from module-info.java. That declaration lists requires, the other modules this one is allowed to read, and exports, the packages this one lets outsiders compile and link against. The two keywords answer different questions, and both must say yes before public even matters: does my module read yours, and does yours export the exact package the class sits in? A package you never export is invisible from outside no matter how public its classes are.

Resolution happens before main runs. The launcher starts from the root module, walks requires edges across the module path, and fails immediately if a required module is missing or if two modules on the path contain the same package. You never write requires java.base; the compiler inserts it. Write requires transitive when a dependency shows up in your own signatures, the way java.sql does for java.xml because some of its methods hand back XML types, and requires static when a dependency is needed to compile but may be absent at runtime.

The classpath did not disappear. Classes loaded from it belong to the unnamed module, which reads every resolved module and exports all of its own packages, which is why non-modular code still compiles and runs unchanged. What changed for everyone is the JDK itself: jdk.internal.misc, sun.security.util and most of com.sun are neither exported nor open, so setAccessible against them throws InaccessibleObjectException from JDK 16 onward instead of printing the warning it did in 9 through 15. sun.misc.Unsafe is the famous survivor, exported on purpose by the jdk.unsupported module; everything else needs --add-exports to compile and link or --add-opens for deep reflection, which puts the decision in the hands of whoever launches the application rather than the library.

import java.lang.reflect.Field;
import java.lang.reflect.InaccessibleObjectException;

public class ModuleProbe {
    public static void main(String[] args) throws NoSuchFieldException {
        Module base = String.class.getModule();
        Module self = ModuleProbe.class.getModule();

        System.out.println("String's module: " + base.getName());
        System.out.println("our module: " + self.getName() + " (named=" + self.isNamed() + ")");
        System.out.println("we read java.base: " + self.canRead(base));
        System.out.println("java.lang exported: " + base.isExported("java.lang"));
        System.out.println("jdk.internal.misc exported: " + base.isExported("jdk.internal.misc"));

        Field value = String.class.getDeclaredField("value");
        try {
            value.setAccessible(true);
            System.out.println("String.value opened");
        } catch (InaccessibleObjectException e) {
            System.out.println("String.value: " + e.getClass().getSimpleName());
        }
    }
}

Worked examples

public class OpenFromInside {
    public static void main(String[] args) {
        Module base = String.class.getModule();
        Module here = OpenFromInside.class.getModule();

        System.out.println("canRead java.base: " + here.canRead(base));
        System.out.println("isExported jdk.internal.misc to us: " + base.isExported("jdk.internal.misc", here));
        System.out.println("isOpen java.lang to us: " + base.isOpen("java.lang", here));
        try {
            base.addOpens("java.lang", here);
            System.out.println("we opened it ourselves");
        } catch (IllegalCallerException e) {
            System.out.println("addOpens refused: " + e.getClass().getSimpleName());
        }
    }
}

public class SqlRequires {
    public static void main(String[] args) {
        Module sql = ModuleLayer.boot().findModule("java.sql").orElseThrow();
        Module xml = ModuleLayer.boot().findModule("java.xml").orElseThrow();

        sql.getDescriptor().requires().stream()
           .map(r -> r.name() + " " + r.modifiers())
           .sorted()
           .forEach(System.out::println);

        System.out.println("java.sql reads java.xml: " + sql.canRead(xml));
    }
}

Important notes

Common mistakes

Try it yourself