{"title":"Java Modules (JPMS)","description":"","content":"Java 9 introduced the **Java Platform Module System (JPMS)**, the largest structural change to the language since generics. Packages group related classes, but they have always lived in a flat world where any `public` class from any JAR can be called from anywhere else. JPMS adds a layer above packages that lets a library say what it exports, what it depends on, and what stays internal. This lesson covers what a module is, the problems it solves, how modules differ from JARs and packages, the three kinds of modules a Java program can contain, and how to compile and run a minimal module from the command line.\n\n---\n\n# The Problems JPMS Was Built to Solve\n\nBefore Java 9, the runtime had a single mechanism for finding code: the **classpath**. The classpath is a flat, ordered list of JAR files and directories. The JVM searches it from left to right and uses the first class it finds with the matching fully qualified name. That model is easy to explain, but it leaks three specific kinds of pain that any non-trivial application eventually hits.\n\nThe first is **classpath hell**. Two JARs on the classpath can contain the same class. The JVM picks one and silently ignores the other. Two libraries can demand incompatible versions of a third library and there is no language-level way to say so. A missing transitive dependency does not fail at startup; it fails at the exact moment the missing class is first touched, often deep inside a running request. Classpath problems are runtime problems, and they tend to surface in production.\n\nThe second is **weak encapsulation**. The `public` keyword does only one thing in pre-module Java: it makes a class or member visible to every other class everywhere. There is no way to write a `public` class that some packages can call and others cannot. Internal helper classes inside a library are reachable by any consumer who knows their fully qualified name. Library authors document \"do not use this package\" in JavaDoc, and consumers use it anyway because the compiler does not stop them. When the library refactors the internal package, consumer code breaks.\n\nThe third is the **monolithic JDK**. Before Java 9, the JDK was a single shared blob: `rt.jar`, several megabytes of classes loaded into every Java process regardless of whether the program used Swing, CORBA, or the XML stack. A \"hello world\" program loaded the same runtime as a Swing GUI. Splitting the JDK into modules made it possible to ship runtime images that contain only the platform pieces an application actually needs.\n\nJPMS gives the platform vocabulary to talk about all three problems. A module declares what it depends on, what it exports, and what stays internal. The compiler and runtime check those declarations. Missing dependencies become startup-time errors instead of runtime mysteries. `public` becomes a meaningful access level again, because a class is `public` only to modules that the owning module agrees to export it to. And the JDK itself is now around ninety modules, so a runtime image can include just the parts it needs.\n\n---\n\n# Modules, JARs, and Packages\n\nThe three terms get used interchangeably in casual conversation, but they sit at three different layers.\n\n\n| Layer | What It Is | Example |\n| --- | --- | --- |\n| Package | A namespace for related classes | `com.example.checkout` |\n| JAR | A zip file that bundles compiled classes and resources | `checkout-1.2.jar` |\n| Module | A named, self-describing unit of code with declared dependencies and exports | `com.example.checkout` |\n\n\nA package holds classes. A JAR holds packages. A module describes one or more packages and is usually distributed as a single JAR with extra metadata. The module is the new layer; the package and the JAR existed before.\n\nA module always has a name. The name is a dotted identifier and, by convention, matches the prefix of the packages it contains. The module `com.example.checkout` typically contains packages like `com.example.checkout`, `com.example.checkout.discount`, and `com.example.checkout.internal`. Choosing a globally unique reverse-domain name avoids collisions when modules from different vendors end up in the same application.\n\n\n```mermaid\nflowchart TD\n Module[\"Module com.example.checkout\"]:::cyan\n PackageA[\"Package com.example.checkout\"]:::orange\n PackageB[\"Package com.example.checkout.discount\"]:::orange\n PackageC[\"Package com.example.checkout.internal\"]:::teal\n ClassA[\"Cart, Order\"]:::green\n ClassB[\"DiscountRule\"]:::green\n ClassC[\"PriceTable\"]:::green\n\n Module --> PackageA\n Module --> PackageB\n Module --> PackageC\n PackageA --> ClassA\n PackageB --> ClassB\n PackageC --> ClassC\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe diagram shows one module wrapping three packages. The first two packages are part of the module's public surface and are exported to consumers. The third is an internal package, kept inside the module and not callable from outside. Without modules, all three would be callable from anywhere. With modules, the boundary becomes enforceable.\n\n---\n\n# What Lives in a Module\n\nA module has a small piece of metadata that names it and lists what it gives out and what it takes in. That metadata lives in a special file called `module-info.java`, written at the **root of the module source tree**, alongside the topmost packages.\n\nA typical layout for a module called `com.example.checkout` looks like this:\n\n\n```shell\ncheckout/\n src/\n com.example.checkout/\n module-info.java\n com/example/checkout/Cart.java\n com/example/checkout/Order.java\n com/example/checkout/internal/PriceTable.java\n```\n\n\nThe outer `com.example.checkout/` directory is the module source directory. The compiler uses this directory name as the module name when the `--module-source-path` option is used. Inside it, `module-info.java` is the descriptor file and the rest of the tree follows the normal package structure.\n\nThe minimal descriptor is short:\n\n\n```java\nmodule com.example.checkout {\n exports com.example.checkout;\n requires java.base;\n}\n```\n\n\nThis says three things. The module is named `com.example.checkout`. It exports the `com.example.checkout` package, which means classes in that package are visible to other modules. It requires `java.base`, the foundation module that contains `java.lang`, `java.util`, and the rest of the core. For this lesson, `exports` and `requires` are enough.\n\nIn practice, `requires java.base;` is implicit. Every module gets it automatically, just as every class implicitly extends `java.lang.Object`. The line can be omitted and the module still works.\n\n---\n\n# Module Path vs Classpath\n\nThe classpath did not go away in Java 9. JPMS introduced a parallel mechanism called the **module path**, and a JVM can load code from both at the same time. The two paths look similar at first glance but behave very differently.\n\nThe classpath is flat. The JVM sees a list of JARs and treats every public class in every JAR as equally callable. There are no boundaries.\n\nThe module path is structured. The JVM sees a list of modules. Each module knows its own name, its dependencies, and the packages it exports. The runtime resolves the dependency graph at startup and refuses to start if a required module is missing.\n\n\n```mermaid\nflowchart LR\n subgraph CP[\"Classpath (-cp)\"]\n Jar1[\"foo.jar\"]:::orange\n Jar2[\"bar.jar\"]:::orange\n Jar3[\"baz.jar\"]:::orange\n end\n\n subgraph MP[\"Module Path (-p)\"]\n Mod1[\"com.example.checkout\"]:::cyan\n Mod2[\"com.example.catalog\"]:::cyan\n Mod3[\"java.sql\"]:::teal\n end\n\n CP -->|\"any public class
is callable everywhere\"| Result1[\"Flat visibility\"]:::green\n MP -->|\"only exported packages
from required modules\"| Result2[\"Enforced boundaries\"]:::green\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe classpath side shows three plain JARs, all of which contribute their public classes into a single shared namespace. The module path side shows three modules, each contributing only the packages it explicitly exports, and only to modules that explicitly require it.\n\nOn the command line, the classpath uses `-cp` (or `--class-path`) and the module path uses `-p` (or `--module-path`). Both can be given to the same `javac` or `java` invocation. Code on the classpath sees code on the module path through a fallback mechanism. Code on the module path follows strict modular rules.\n\n---\n\n# The Three Kinds of Modules\n\nA running Java program can contain three different kinds of modules. They differ in whether they have a `module-info.java` file and where their code lives.\n\n### Named (Explicit) Modules\n\nA **named module** has a `module-info.java` file. The compiler reads the descriptor, the runtime enforces the declared dependencies and exports, and the module gets the strong encapsulation that JPMS is designed for. Every platform module (`java.base`, `java.sql`, `java.xml`, and the rest) is a named module. Any module declared with a `module-info.java` is also a named module.\n\nA named module is the default target when migrating a library to modules. It is the strictest of the three kinds and the one that gets the full benefit of the system.\n\n### Automatic Modules\n\nAn **automatic module** is a plain JAR placed on the module path without a `module-info.java`. The runtime treats it as a module so other named modules can depend on it, but it has no declared exports and no declared dependencies of its own.\n\nThe automatic module's name comes from one of two sources. If the JAR's `META-INF/MANIFEST.MF` includes an `Automatic-Module-Name` attribute, that string is the module name. Otherwise, the name is derived from the JAR file name by stripping the version suffix, replacing non-alphanumeric characters with dots, and removing trailing dots. A JAR called `gson-2.10.1.jar` becomes the module `gson`.\n\nBecause the JAR has no explicit declarations, an automatic module behaves permissively. It exports every package it contains. It can read every other module. This is the bridge that allows modular code to depend on libraries that have not yet adopted modules. A modern application can have a module-info that requires both `java.sql` (a named platform module) and `gson` (an automatic module wrapped around an old-style JAR).\n\n### The Unnamed Module\n\nCode on the **classpath** is not in any explicit module. Instead, it lives in a single per-classloader pseudo-module called the **unnamed module**. The unnamed module is the bucket the JVM uses when there is no `module-info.java` to read.\n\nThe unnamed module reads every other module on the module path, including all the platform modules. That is why pre-Java-9 applications still run on a modern JVM: their classpath code is treated as one big unnamed module that can call into the JDK normally.\n\nThe reverse direction does not hold. A named module cannot directly `requires` the unnamed module. Named modules have to declare what they depend on by name, and the unnamed module does not have a name. This rule makes \"move everything to modules gradually\" more difficult than it sounds: a library that becomes a named module can no longer be required by code that has not yet declared itself a module, unless that code stays on the classpath.\n\n\n```mermaid\nflowchart LR\n Named[\"Named modules
com.example.checkout
(has module-info)\"]:::cyan\n Auto[\"Automatic modules
gson.jar on module path
(no module-info)\"]:::orange\n Unnamed[\"Unnamed module
code on classpath
(no module concept)\"]:::teal\n\n Auto -->|\"automatic modules
can read everything\"| Named\n Unnamed -->|\"unnamed module
can read everything\"| Named\n Unnamed --> Auto\n Named -->|\"can require named
and automatic by name\"| Auto\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram captures the visibility rules. Named modules are strict: they only see what they explicitly require. Automatic modules and the unnamed module are loose: they see everything. The named-to-unnamed arrow does not exist.\n\n---\n\n# The Platform Modules\n\nJava 9 split the JDK into named modules. The full list is around ninety, and the following command prints them:\n\n\n```shell\njava --list-modules\n```\n\n\nA small slice of the output looks like this:\n\n\n```shell\njava.base@21\njava.compiler@21\njava.datatransfer@21\njava.desktop@21\njava.logging@21\njava.management@21\njava.naming@21\njava.net.http@21\njava.sql@21\njava.xml@21\njdk.compiler@21\njdk.jartool@21\n```\n\n\nThe version after the `@` is the JDK version. `java.base` is special: every module implicitly requires it, the same way every class implicitly extends `Object`. The other `java.*` modules are platform features that used to be lumped into `rt.jar`: SQL drivers, XML parsers, GUI toolkit, and so on. The `jdk.*` modules are JDK-internal tools and APIs.\n\nTo inspect a single module's contract, the `--describe-module` option prints its descriptor:\n\n\n```shell\njava --describe-module java.sql\n```\n\n\nThe output (trimmed for length) reads like a `module-info` written in shorthand:\n\n\n```shell\njava.sql@21\nexports java.sql\nexports javax.sql\nrequires java.logging transitive\nrequires java.transaction.xa transitive\nrequires java.xml transitive\nrequires java.base mandated\nuses java.sql.Driver\n```\n\n\nThe output uses the same vocabulary: `exports`, `requires`, `uses`, and a few more. The JDK eats its own cooking. Every standard library module follows the same rules user-written modules do.\n\n---\n\n# The Module Graph\n\nWhen a Java program starts in module mode, the runtime resolves a **module graph**. The graph starts from the module that contains the `main` method, called the root module, and walks the `requires` relationships transitively. The result is the set of modules the application actually needs.\n\nConsider a small application with three of its own modules and two platform modules.\n\n\n```mermaid\nflowchart LR\n App[\"com.example.app
(root, has main)\"]:::cyan\n Checkout[\"com.example.checkout\"]:::orange\n Catalog[\"com.example.catalog\"]:::orange\n Sql[\"java.sql\"]:::teal\n Base[\"java.base
(implicit, every module)\"]:::green\n\n App --> Checkout\n App --> Catalog\n Checkout --> Sql\n Catalog --> Sql\n App -.->|\"implicit\"| Base\n Checkout -.->|\"implicit\"| Base\n Catalog -.->|\"implicit\"| Base\n Sql -.->|\"implicit\"| Base\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe root `com.example.app` requires the two application modules. Both of those require `java.sql`. Every module silently requires `java.base`. The runtime computes this graph at startup. If any of the nodes is missing from the module path, the application fails to launch with a clear error, rather than failing with `NoClassDefFoundError` somewhere in the middle of the first request.\n\nIf two modules on the module path have the same name, resolution fails. If a module on the module path exports the same package as another module, resolution fails. The runtime detects these conflicts at startup, not at the moment of first use. That detection is one of the reasons JPMS exists.\n\n---\n\n# Strong Encapsulation in Practice\n\nThe most visible effect of modules on day-to-day Java code is what `public` means.\n\nInside a named module, `public class Cart` is visible to other classes in the same module, the way it always was. To a class in a different module, `Cart` is visible only if the module that owns it exports the package `Cart` lives in. A package not listed in `exports` is internal to the module, no matter how many `public` classes it contains.\n\n\n```java\nmodule com.example.checkout {\n exports com.example.checkout;\n // com.example.checkout.internal is NOT exported\n}\n```\n\n\nWith that descriptor, `com.example.checkout.Cart` is callable from any module that requires `com.example.checkout`. `com.example.checkout.internal.PriceTable` is not, even if it is declared `public`. A consumer that writes `import com.example.checkout.internal.PriceTable;` gets a compile error along the lines of `package com.example.checkout.internal is not visible`.\n\nThis is the change that gives library authors a working tool for separating their public API from their implementation. Before JPMS, the only options were JavaDoc warnings and naming conventions like `impl` and `internal`. Now the boundary is enforced by the compiler and the runtime.\n\nOne behavior to note: reflection respects module boundaries by default. Calling `setAccessible(true)` on a non-exported member of another module throws `InaccessibleObjectException` unless the owning module explicitly opens the package. The `opens` directive is how modules grant reflective access to specific consumers like serialization libraries.\n\n---\n\n# Compiling and Running a Minimal Module\n\nThe fastest way to build intuition is to compile and run a single-module \"hello world\" from the command line, without an IDE or build tool. The example uses one module with one class.\n\nThe source tree:\n\n\n```shell\nhello/\n src/\n com.example.hello/\n module-info.java\n com/example/hello/Main.java\n```\n\n\nThe descriptor declares the module name. There are no exports because nothing depends on this module, and there are no explicit requires because `java.base` is implicit:\n\n\n```java\nmodule com.example.hello {\n}\n```\n\n\nThe class is a normal `main`-method program:\n\n\n```java\npackage com.example.hello;\n\npublic class Main {\n public static void main(String[] args) {\n System.out.println(\"Hello from module \" + Main.class.getModule().getName());\n }\n}\n```\n\n\nCompile the module into an output directory called `out`.\n\n\n```shell\njavac -d out --module-source-path src $(find src -name \"*.java\")\n```\n\n\nThe `--module-source-path src` flag tells `javac` that everything under `src` is organized as one or more module source directories. The shell expansion `$(find src -name \"*.java\")` passes every Java file in the tree to the compiler. After this runs, `out/` contains the compiled output organized by module name.\n\nRun the program with `java`, pointing at the module path and naming the module and main class.\n\n\n```shell\njava -p out -m com.example.hello/com.example.hello.Main\n```\n\n\nThe `-p out` flag is the short form of `--module-path out`. The `-m com.example.hello/com.example.hello.Main` flag is the short form of `--module com.example.hello/com.example.hello.Main`, and it tells the runtime \"start the application by calling `main` on the `Main` class in the `com.example.hello` module.\"\n\nThe output is:\n\n\n```shell\nHello from module com.example.hello\n```\n\n\n`Main.class.getModule().getName()` returns the module name the runtime resolved this class into. For a class on the classpath the same call would return `null` (or report the class as living in the unnamed module). For a class in a named module it returns the declared name.\n\nThe commands look more verbose than `javac Main.java && java Main`, and they are. In practice, build tools like Maven and Gradle drive `javac` and `java`, so these commands rarely get typed by hand after the first day. The exercise shows that JPMS is built into the compiler and the runtime themselves, not added through a separate tool.\n\n---\n\n# Benefits and Trade-offs\n\nJPMS makes three things better and adds friction in a few places. Both halves matter.\n\n\n| Benefit | What It Buys You |\n| --- | --- |\n| Reliable dependency resolution | Missing or duplicate modules fail at startup, not in the middle of a running request |\n| Strong encapsulation | `public` in a non-exported package is no longer reachable from outside the module |\n| Smaller runtime images | `jlink` can build a custom JRE containing only the modules an application needs |\n| Faster startup and lower memory | The JVM can skip platform modules that are not part of the resolved graph |\n\n\nThe flip side:\n\n\n| Trade-off | Why It Hurts |\n| --- | --- |\n| Reflection and serialization libraries need explicit `opens` | Frameworks that scan private fields fail with `InaccessibleObjectException` unless the module opens its packages |\n| Split packages are forbidden | Two modules cannot both contain the same package, which breaks some legacy libraries that split a namespace across JARs |\n| Migration is invasive | Every JAR an application depends on either becomes a named module, becomes an automatic module, or stays on the classpath. Mixing the three takes care. |\n| Tooling churn | Older IDE plugins, code generators, and build configurations sometimes need updates to handle `module-info.java` correctly |\n\n\nThese trade-offs explain why many applications, especially older ones with deep dependency trees, still run on the classpath ten years after JPMS shipped. The classpath has not gone away and does not need to. JPMS provides the most value for library authors, for applications that ship as custom runtime images, and for codebases where access boundaries between teams matter. For a small service with a tight dependency set, the cost of adopting modules may be larger than the benefit.\n\nThe pragmatic middle ground many teams settle on: keep their own code on the classpath, let the JDK be modular (which it is, automatically), and adopt modules only when something concrete pushes them in that direction, like wanting a smaller container image through `jlink`.","pageType":"java"}

Java Modules (JPMS)

Get Premium