How does the Java Platform Module System (JPMS), introduced in Java 9, enforce API versus implementation separation at the language and runtime level, and how is that different from just relying on the public access modifier?

## The mechanism The mechanism is a `module-info.java` file at the root of a module, declaring something like `module com.example.payments { exports com.example.payments.api; requires com.example.orders; }`. - Only the packages listed after `exports` are visible to other modules - even if the classes inside a non-exported package are individually marked public. - A class in `com.example.payments.impl` marked public is still completely invisible to any other module that requires `com.example.payments`, because that package was never exported. This is called **strong encapsulation**, and it is a genuinely new capability the classic classpath never had: on the classpath, public really did mean visible everywhere, with no way to restrict it further at the language level. ## exports versus opens A distinction worth making precisely is exports versus opens. | Clause | What it grants | |---|---| | `exports` | exports controls both compile-time access and ordinary reflective access to a package's public types. | | `opens` | opens, written as `opens com.foo.impl` or `opens com.foo.impl to SomeModule`, additionally permits deep reflection into that package at runtime - calling `setAccessible(true)` to bypass a private field or constructor - which many frameworks like Hibernate or Jackson rely on to read and write fields directly. | A module author can: - export a package for typed, compile-time access without opening it, blocking that framework-style deep reflection unless deliberately allowed, - or conversely open a package without exporting it, permitting reflection-based frameworks in without exposing a normal compile-time public API at all. ## Why it exists This exists to close a real, long-standing problem inside the JDK itself. Internal packages like `sun.misc.Unsafe` or various `com.sun.*` classes were technically public and heavily used by libraries across the ecosystem simply because nothing stopped them, which meant the JDK team could never safely change those internals without breaking huge swaths of downstream code. **JPMS** was built specifically to let the JDK, and any library author, draw a hard, JVM-enforced line between supported API and please-do-not-touch-this internal detail, enabling real internal evolution again. ## The trade-offs The trade-offs are substantial. Adopting JPMS is heavyweight: - every module needs a `module-info.java`, - the module graph must be acyclic and fully resolved, - and two modules can never both contribute classes to the same package name - a **split-package** error that breaks the build. Migrating a large pre-modular codebase is genuinely painful, and much of the Java ecosystem still ships as **automatic modules**, jars placed on the module path without their own module-info, which get inferred module names and largely bypass strong encapsulation - meaning the guarantees only hold cleanly when the whole dependency graph is properly modularized. Reflection-heavy frameworks that predate JPMS broke under strict enforcement until opens was added, and in practice many teams still open packages broadly out of expedience, quietly undermining the hidden half of the design. ## Failure modes in production 1. **The most common production failure mode is an `InaccessibleObjectException`** or similar error at runtime, usually triggered by a reflection-based library such as a JSON serializer trying to reach a private field in a package that was exported but never opened - code that worked fine on the plain classpath suddenly breaks the moment it runs as a proper module. 2. **Split-package errors** show up at startup when two jars define overlapping packages. 3. **Overuse of `opens ... to ALL-UNNAMED`**, or blanket `--add-opens` JVM flags used as a workaround, quietly defeats the entire encapsulation goal the same way making everything public again would. ## The flagship real-world example The JDK's own modularization in Java 9 is the flagship real-world example: `java.base`, `java.sql`, and similar modules export a curated set of packages while internals like `sun.*` and `jdk.internal.*` stay hidden, which forced libraries that had relied on those internals - many did, via `sun.misc.Unsafe` in particular - to migrate to supported replacements such as `java.lang.invoke.VarHandle`. A smaller-scale but very common pattern is a library author shipping `mylib.api`, exported, alongside `mylib.internal`, not exported, inside the same JPMS module, so the compiler and IDE autocomplete themselves physically prevent consumers from ever importing `mylib.internal.*` at all - a hard, JVM-enforced version of the api-module-versus-impl-module pattern achieved without needing two separate artifacts. ## Back to minimizing a public contract This connects directly back to the broader idea of minimizing a public contract. Because an exported package is now a real, JVM-enforced commitment rather than a documentation suggestion, JPMS pushes module authors toward exporting as little as possible - typically only genuine interfaces, DTOs, and exceptions - since un-exporting a package later is both a source-breaking and a binary-breaking change for anyone who came to depend on it. That is a sharper, less forgiving version of the same discipline required by a plain api/impl module split: with JPMS, the module system itself, not just team convention, is what makes exporting too much expensive to walk back.