Java Modules (JPMS) Explained — module-info, Exports, and Real-World Pitfalls

If you've ever cracked open a production JVM heap dump and found a third-party library reaching deep into sun.misc.Unsafe, or spent a day debugging a ClassNotFoundException that only appeared when a JAR was repackaged, you already know the pain that JPMS was built to eliminate. The Java Platform Module System, shipped in Java 9 as part of Project Jigsaw after nearly a decade of design work, is the most structurally significant change to the Java platform since generics. It isn't a minor API addition — it's a new unit of deployment that sits above the JAR and below the application.

Before JPMS, the JVM had exactly one accessibility boundary at runtime: public. If a class was public, anyone on the classpath could use it, full stop. That meant internal JDK APIs like sun.reflect and com.sun.* were fair game for library authors who needed performance shortcuts, and there was no tooling that could enforce the architectural boundaries your team drew on whiteboards. The result was a fragile, monolithic JDK and codebases where 'refactoring an internal package' was a multi-sprint project because you never knew who was secretly depending on it.

By the end of this article you'll understand how the module system enforces strong encapsulation at the JVM level, how to author a correct module-info.java for a real multi-module project, how the module path differs from the classpath at the classloader level, where the system genuinely breaks down (split packages, reflective frameworks, legacy migration), and exactly what to say when an interviewer asks you to contrast --add-opens with --add-exports. This is the practical, internals-first guide that the official Javadoc never was.

What is Java Modules — JPMS?

Java Modules — JPMS is a core concept in Java. Rather than starting with a dry definition, let's see it in action and understand why it exists.

// TheCodeForge — Java Modules — JPMS example
// Always use meaningful names, not x or n
public class ForgeExample {
    public static void main(String[] args) {
        String topic = "Java Modules — JPMS";
        System.out.println("Learning: " + topic + " 🔥");
    }
}

Frequently Asked Questions