Java 21 Modules and Deployment: JPMS, ServiceLoader and jlink
Introduction
Java 21 modules and deployment connect source layout, dependency readability and runtime configuration. This 1Z0-830 lesson builds a three-module application with JPMS, packages it into JARs, discovers a service with ServiceLoader and assembles a runtime with jlink.
Commands below use Bash syntax on Linux or macOS. On Windows, adapt shell syntax and use a semicolon rather than a colon between path entries. Commands have been reviewed against the Java 21 tool references; they are examples to run in a separate practice directory.
Learning objectives
After this lesson you will be able to:
- Write a
module-info.javawithrequires,requires transitive,requires static,exports,exports ... to,opens,usesandprovides ... with. - Distinguish named (explicit), automatic and unnamed modules, and the class path from the module path.
- Compile, package and run modular code with
javac,jarandjavausing--module-path,--moduleand--module-source-path. - Inspect and migrate code with
java --list-modules,--describe-module,jar --describe-moduleandjdeps. - Build a custom runtime image with
jlink. - Implement and consume a service with
ServiceLoader. - Explain what strong encapsulation allows for reflection.
1. Why modules
Before Java 9, every public class in every JAR on the class path was visible to every other class. Modules add strong encapsulation (a package is hidden unless exported) and reliable configuration (the JVM checks at startup that every required module is present, with no cycles). The JDK itself is modular: java.base (always read by every module, including java.lang, java.util, java.io), java.sql, java.logging, java.desktop and so on. java --list-modules prints the modules in your runtime.
A module is a set of packages plus a descriptor, module-info.java, placed at the root of the source tree. It compiles to module-info.class at the root of the JAR.
2. The module descriptor
Here are the three descriptors of our example application:
// com.acme.api/module-info.java
module com.acme.api {
exports com.acme.api;
}
// com.acme.impl/module-info.java
module com.acme.impl {
requires com.acme.api;
provides com.acme.api.Greeter with com.acme.impl.Hello;
}
// com.acme.app/module-info.java
module com.acme.app {
requires com.acme.api;
uses com.acme.api.Greeter;
}The directives you must know:
| Directive | Meaning |
|---|---|
requires m; |
This module reads m. Needed at compile time and run time. |
requires transitive m; |
Same, and every module that requires this one also reads m ("implied readability"). |
requires static m; |
m is required at compile time only; optional at run time. |
exports p; |
Public types in p are exported to modules that read this module. |
exports p to m1, m2; |
Qualified export: only the named modules can access p. |
opens p; |
Deep reflection (including private members) on package p at run time. |
opens p to m; |
Qualified opens. |
uses S; |
This module consumes service interface S through ServiceLoader. |
provides S with C; |
This module supplies implementation class C for service S. |
open module m { } |
Opens every package for reflection at run time. |
Rules that are tested again and again:
- A requires static dependency must be available when compiling. At run time it is optional and is not resolved merely by that directive; code using it still needs the module resolved, for example through an appropriate root or --add-modules.
java.baseis always required implicitly. You never writerequires java.base;(it is allowed, but redundant).exportsapplies to one package only, never its subpackages: exportingcom.acmedoes not exportcom.acme.api.exportsmakes public types accessible at compile time and run time.opensgrants run-time reflective access (includingsetAccessible(true)on private members) but not compile-time access. A package can be both exported and opened.- An
open modulecannot also containopensdirectives (it is redundant, so the compiler rejects it). - Module dependencies cannot be cyclic. If A requires B, B cannot require A, directly or indirectly.
- Avoid split packages. Compilation rejects conflicting visible packages, and runtime configuration/class-loader checks can also reject them. A flat application module path does not make duplicate packages safe merely because the module names differ.
- A module name usually follows the reverse-domain convention; the module source folder must match the module name when you use
--module-source-path. - An exported package is not enough: if A requires B and B requires C (without
transitive), code in A cannot use the types of C. Addrequires Cto A, or declarerequires transitive Cin B.
3. Compiling, packaging and running
Use a fresh practice directory with the descriptors above under src/com.acme.api, src/com.acme.impl and src/com.acme.app. Each public type below belongs in its own indicated file.
// src/com.acme.api/com/acme/api/Greeter.java
package com.acme.api;
public interface Greeter { String greet(String name); }
// src/com.acme.impl/com/acme/impl/Hello.java
package com.acme.impl;
import com.acme.api.Greeter;
public final class Hello implements Greeter {
public Hello() { }
public String greet(String name) { return "Hello " + name; }
}
// src/com.acme.app/com/acme/app/Main.java
package com.acme.app;
import com.acme.api.Greeter;
import java.util.ServiceLoader;
public class Main {
public static void main(String[] args) {
ServiceLoader.load(Greeter.class)
.forEach(g -> System.out.println(g.greet("Ana")));
Module module = Main.class.getModule();
System.out.println(module.getName() + " " + module.isNamed());
}
}Compile all three modules, then package their exploded output directories:
javac --release 21 -d out --module-source-path src --module com.acme.api,com.acme.impl,com.acme.app
mkdir -p mods
jar --create --file mods/api.jar -C out/com.acme.api .
jar --create --file mods/impl.jar -C out/com.acme.impl .
jar --create --file mods/app.jar -C out/com.acme.app .Run it by naming the module path and the main class as module/class:
java --module-path mods --module com.acme.app/com.acme.app.Main
# Hello Ana
# com.acme.app trueShort forms exist: -p for --module-path, -m for --module. If the JAR declares a main class (jar --create --file app.jar --main-class com.acme.app.Main -C ...), java -p mods -m com.acme.app is enough. Do not confuse this with java -jar app.jar, which starts the JAR on the class path (unnamed module).
When you compile one module whose dependencies are already packaged, use javac --release 21 -d single-out --module-path mods src/com.acme.app/module-info.java src/com.acme.app/com/acme/app/Main.java. The compiler needs module-info.java among the files. Note the difference between the two flags: --module-source-path points to sources of several modules, --module-path points to compiled modules (JARs or exploded directories).
Useful switches for inspection:
java -p mods --list-modules # modules available (includes the JDK ones)
java -p mods --describe-module com.acme.impl # requires, provides, contains
jar --describe-module --file mods/app.jar # same, for a JARThe output for the implementation module is:
com.acme.impl file:///.../mods/impl.jar
requires com.acme.api
requires java.base mandated
provides com.acme.api.Greeter with com.acme.impl.Hello
contains com.acme.implThe word mandated marks the implicit dependency on java.base.
4. Named, automatic and unnamed modules
| Kind | Where it comes from | Reads | Exports |
|---|---|---|---|
| Named (explicit) module | A JAR with module-info.class on the module path |
Only what it requires (plus java.base) |
Only what it exports |
| Automatic module | A plain JAR (no descriptor) on the module path | All resolved modules, including access to unnamed modules | All its packages |
| Unnamed module | Class-path code associated with a class loader | All resolved modules | All its packages |
Key consequences:
- An explicit named module does not read unnamed modules by default, and requires cannot name them. Automatic modules do read unnamed modules. The migration option --add-reads app=ALL-UNNAMED can add that readability explicitly at compilation and launch; it is not an ordinary requires directive.
- The unnamed module can read all named modules that are resolved (the root modules and their dependencies). Old applications therefore still run on the class path.
- An automatic module gets its name from the manifest attribute
Automatic-Module-Nameif present. Otherwise the name derives from the file name: the.jarextension and the version suffix are removed, and every non-alphanumeric character becomes a dot. For examplecommons-text-1.10.0.jarbecomescommons.text. Because file names are fragile, library authors should setAutomatic-Module-Name. - Running the example on the class path shows the difference:
java -cp mods/api.jar:mods/impl.jar:mods/app.jar com.acme.app.Main
# null falseMain.class.getModule().getName() is null and isNamed() is false: everything is in the unnamed module. The line Hello Ana is also missing, because on the class path ServiceLoader finds providers only through META-INF/services files, not through provides directives. That is a typical "works on the module path, silently does nothing on the class path" question.
Migration strategies. Bottom-up: modularize the libraries with no dependencies first, then those that depend on them; unmodularized dependencies are placed on the module path as automatic modules. Top-down: modularize the application first and expose legacy dependencies as automatic modules on the module path. Leaving a directly used dependency on the class path needs an explicit migration workaround. Both approaches use jdeps to discover dependencies.
5. Services with ServiceLoader
A service is an interface (or abstract class) with provider implementations discovered at run time. This decouples the consumer from the implementations: the consumer module never requires the provider module.
// consumer, module com.acme.app
ServiceLoader<Greeter> loader = ServiceLoader.load(Greeter.class);
for (Greeter g : loader) {
System.out.println(g.greet("Ana")); // Hello Ana
}
loader.findFirst().ifPresent(g -> System.out.println(g.greet("Bo")));
loader.stream().map(ServiceLoader.Provider::type).forEach(System.out::println); // inspect provider typesRules to remember:
- The consumer module must declare
uses Greeter;. Without it,ServiceLoader.load(Greeter.class)throwsServiceConfigurationErrorat run time. - The provider module declares
provides Greeter with Hello;. In an explicit module, the provider type is public and uses either a public no-argument constructor or a public static no-argument provider method whose return type is assignable to the service. Automatic-module and class-path providers use the constructor form, not the provider-method form. - The provider package does not need to be exported: the service is reachable through the interface.
- The provider module must be resolved (present in the module graph). The standard java launcher performs service binding and can resolve observable providers for a resolved consumer’s uses directive. Custom module layers must choose a suitable resolution/binding strategy. For
jlink, however, you must include the provider explicitly or use--bind-services(see below). ServiceLoaderfinds zero providers without error if none are present; the iterator is simply empty.- On the class path, providers are declared in
META-INF/services/<fully qualified service name>files.
Provider implementations still obey Java class and interface access rules, even when their packages are not exported.
6. Reflection and strong encapsulation
Since Java 17 (JEP 403) the JDK strongly encapsulates its internals, and the same rule applies to your own modules. For a reflective call such as field.setAccessible(true) on a private field of class p.C from another module, the package p must be opened to the caller (or the module must be open). Exporting is not enough:
module com.shop.model {
exports com.shop.model; // other modules can compile against public types
opens com.shop.model to com.fasterxml.jackson.databind; // only the JSON library can reflect deeply
}From another module, setAccessible(true) on this private field throws InaccessibleObjectException when the package is not opened to the caller. Reading it with Field.get without suppressing access checks instead throws IllegalAccessException. Exported public types and members have ordinary reflective access. The command-line escape hatches --add-exports, --add-opens and --add-reads exist for legacy code; they do not replace proper descriptors.
7. jdeps and jlink
jdeps analyzes dependencies of compiled code:
jdeps -s --module-path mods mods/app.jar # summary
# com.acme.app -> com.acme.api
# com.acme.app -> java.base
jdeps --module-path mods --print-module-deps --module com.acme.app # comma-separated module dependencies
# Separate migration example: legacy.jar must be an existing non-modular JAR.
jdeps --generate-module-info descriptors legacy.jarjdeps sees static dependencies in compiled code; reflection, resource lookup and service loading can require additional runtime configuration.
jlink assembles a custom runtime image containing only the modules you need, which shrinks size and attack surface:
jlink --module-path "mods:$JAVA_HOME/jmods" \
--add-modules com.acme.app,com.acme.impl \
--output rt
rt/bin/java --list-modules
# com.acme.api
# com.acme.app
# com.acme.impl
# java.base@21... (the installed JDK build determines the version)Important points:
- jlink defaults to the JDK jmods directory. If a supplied module path cannot resolve java.base, Java 21 jlink appends that directory. Listing it explicitly, as above, makes the input clear.
- jlink accepts explicit modules; an automatic module makes it fail. This is why libraries must be modularized (or wrapped) before creating an image.
jlinkresolvesrequiresbut does not add service providers by default. In the example,com.acme.implappears in the image only because it was listed in--add-modules; use--bind-servicesto include providers automatically.- Useful options: --launcher name=module/class creates a launcher script, --compress=2 enables ZIP compression in Java 21,
--strip-debugremoves debug information. jmodcreates.jmodfiles (a packaging format for jlink input and native code); it cannot be used on the regular module path at run time.
Resources accessed inside a packaged application also need suitable lookup paths. Review Java I/O and resource handling when separating filesystem paths from packaged resources.
8. Non-modular packaging reminders
Not all questions concern modules. Remember the basics of JAR packaging:
jar --create --file app.jar --main-class com.acme.Main -C classes .writes theMain-Classmanifest attribute;java -jar app.jarthen uses it. With-jar, the-cpoption is ignored; dependencies must be listed in the manifestClass-Pathattribute.- Package names map to directories: class
com.acme.Mainmust be incom/acme/Main.class.javac -d outcreates these directories. - A multi-release JAR has Multi-Release: true in its manifest and version-specific classes under META-INF/versions/N/. The runtime selects the highest applicable version no greater than its own, with base entries as fallback.
- An
importis a compile-time convenience only; it has no run-time effect and never loads a class.
Worked example: implied readability
Statement. Three modules are defined as follows. Does module reports compile?
module orders { exports com.orders; } // contains public class Order
module billing { requires orders; exports com.billing; } // com.billing.Invoice has a public method Order order()
module reports { requires billing; } // Report.java calls invoice.order().getId()Step 1. reports reads billing and may use com.billing.Invoice.
Step 2. The call invoice.order() returns an Order, a type from orders. To use Order, even implicitly through a method chain, reports must read orders.
Step 3. reports does not require orders, and billing uses a plain requires orders, so readability is not implied.
Solution. The code does not compile: Order is not accessible because module reports does not read module orders. The best fix is requires transitive orders; in billing, because billing exposes Order in its public API.
Why the other choices are worse. Changing the exports of orders does not help: com.orders is already exported to everyone, so accessibility is fine and readability is the missing piece. Adding requires orders; in reports works but must be repeated in every consumer of billing. Using opens is irrelevant: it concerns reflection at run time.
Second worked example: reflection and opens
Statement. A mapper library in module lib.mapper runs this code on an object of class com.shop.model.Product, which belongs to module com.shop.model:
Field f = Product.class.getDeclaredField("price"); // private double price
f.setAccessible(true);
double price = f.getDouble(product);The descriptor of com.shop.model is module com.shop.model { exports com.shop.model; }. What happens, and what is the minimum fix?
Step 1. getDeclaredField succeeds: retrieving the field object does not check access.
Step 2. setAccessible(true) on a private member needs deep reflection, which requires the package to be opened to the caller module (or to all modules).
Step 3. exports does not provide that permission.
Solution. setAccessible throws InaccessibleObjectException. The minimum fix is opens com.shop.model to lib.mapper; in com.shop.model (opening to a named module is preferable to opening to everyone).
Why the other choices fail. Changing the field to public breaks encapsulation. requires lib.mapper in the model module reverses the dependency and does not grant reflection access. --add-opens on the command line works but hides the requirement outside the code and is meant as a temporary workaround.
Common pitfalls and exam tips
- Exam tip: for each question, first check the readability (who requires whom), then the accessibility (what is exported), and only then the reflection (what is opened).
exportsis per package;exports com.acmedoes not covercom.acme.util.requiresis not transitive by default; userequires transitivewhen your API exposes a type from the dependency.- Check explicit requires cycles and split-package visibility or class-loader conflicts when resolving a modular application.
- Explicit named modules do not read the class path by default. Automatic modules and explicit --add-reads migration options are exceptions.
module-info.javais not a regular class: nopackagedeclaration, it must be at the root, andimportstatements are allowed only to simplify names in directives.usesis required forServiceLoader.load;provides ... withalone does not allow the provider module to consume the service.jlinkrejects automatic modules and does not bind services unless asked.- The short flags are
-pand-mforjava;javacuses-ptoo, but--module-source-pathhas no short form.
Mini case study: modularizing the shipping application
Scenario. A shipping application is split into ship.core (domain types), ship.fedex and ship.ups (carrier plugins) and ship.cli (the executable). The team wants plugins to be swappable without recompiling the CLI. They also use a library geo-utils-2.3.jar that has no descriptor, and a Jackson-style JSON library that reflects on ship.core entities.
Questions. (1) How should the descriptors of ship.core, ship.fedex and ship.cli look? (2) How is geo-utils-2.3.jar handled? (3) What must be done to create a jlink image?
Solution.
ship.coredefines the interfaceCarrierin the exported packageship.core.spiand the entities inship.core.model. The descriptor ismodule ship.core { exports ship.core.spi; exports ship.core.model; opens ship.core.model to com.fasterxml.jackson.databind; }. Each plugin ismodule ship.fedex { requires ship.core; provides ship.core.spi.Carrier with ship.fedex.FedexCarrier; }and the CLI ismodule ship.cli { requires ship.core; uses ship.core.spi.Carrier; }. The CLI never requires a plugin; it loads them withServiceLoader.load(Carrier.class). Adding a carrier at the next launch means adding its provider JAR to the module path.geo-utils-2.3.jargoes on the module path as an automatic module namedgeo.utils(file name minus the version). Modules that need it declarerequires geo.utils;. The better long-term fix is a library release that setsAutomatic-Module-Nameor ships a real descriptor.jlinkrefuses automatic modules, so eithergeo.utilsmust be modularized (for example withjdeps --generate-module-infoand a repackaged JAR), or the team ships the application as a regular module-path deployment on a full JDK. For the image they would calljlink --module-path mods:$JAVA_HOME/jmods --add-modules ship.cli,ship.fedex,ship.ups --output imageand, if they want the providers selected automatically, add--bind-services.
Key terms
- Module: a named set of packages with a descriptor declaring its dependencies and exports.
- Module path: the location searched for modules, as opposed to the class path.
- Readability: the relation "module A can use module B", created by
requires(or implied byrequires transitive). - Strong encapsulation: only exported packages are accessible; only opened packages allow deep reflection.
- Automatic module: a plain JAR on the module path with an assigned or derived name, broad readability and exported/open packages.
- Unnamed module: a class loader’s module for its classes outside named modules, including class-path code.
- Service / provider: an interface and an implementation discovered with
ServiceLoader. - jlink: the tool that builds a custom runtime image from modules.
- jdeps: the tool that lists the dependencies of classes and JARs.
Summary checklist
- I can write
requires,requires transitive,requires static,exports,exports to,opens,usesandprovides withcorrectly. - I know
java.baseis implicit and that exports are per package. - I can tell the difference between readability, accessibility and reflection access.
- I can use
javac --module-source-path,jar,java -p ... -m module/class. - I know the three kinds of modules and how an automatic module name is derived.
- I can distinguish default explicit-module readability from automatic modules and migration overrides.
- I can implement a service with
uses,provides withandServiceLoader. - I know when
InaccessibleObjectExceptionoccurs and howopensfixes it. - I can use
jdeps -s,--print-module-depsandjlink --add-modules --output. - I know
jlinkrejects automatic modules and needs--bind-servicesfor providers.
Official sources
-
Oracle exam page 1Z0-830 (objectives): https://education.oracle.com/java-se-21-developer-professional/pexam_1Z0-830 (opens in a new tab)
-
Java SE 21 documentation, module system: https://docs.oracle.com/en/java/javase/21/docs/specs/man/java.html (opens in a new tab)
-
Java Language Specification SE 21, modules (chapter 7.7): https://docs.oracle.com/javase/specs/jls/se21/html/jls-7.html#jls-7.7 (opens in a new tab)
-
jlinktool reference: https://docs.oracle.com/en/java/javase/21/docs/specs/man/jlink.html (opens in a new tab) -
jdepstool reference: https://docs.oracle.com/en/java/javase/21/docs/specs/man/jdeps.html (opens in a new tab) -
ServiceLoaderAPI: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/ServiceLoader.html (opens in a new tab) -
javac tool reference: https://docs.oracle.com/en/java/javase/21/docs/specs/man/javac.html (opens in a new tab)
-
jar tool reference: https://docs.oracle.com/en/java/javase/21/docs/specs/man/jar.html (opens in a new tab)
-
Reflective access control: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/reflect/AccessibleObject.html (opens in a new tab)
-
Field read operations: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/reflect/Field.html (opens in a new tab)
