Modules
A module is a group of packages with a name and a declaration of what it needs and what it offers. The JDK itself is a set of modules, which is why java --list-modules prints a hundred lines; a program of your own may be one, and then the compiler checks its dependencies at the level of the module and not only of the classpath. Since Java 9 the file that declares it is module-info.java.
module-info.java
The smallest module is a name and an empty body, and it is a file in the root of the source tree, next to the packages it contains:
module demo {
}
A module that offers code adds exports for each package another module may use, and a module that needs another adds requires; the next section has both. A package that is not exported is not reachable from another module, even when its class is public. That is the change the module system makes: a public class in a named module is public to the module and not to the world, and exports is what opens the door.
A class in a module
The class is in a package, and the package is in the module, so the file lives under two folders that repeat those names. It reads its own module from the class it is in:
package demo;
public class Main {
public static void main(String[] args) {
System.out.println("hello from a module");
Module module = Main.class.getModule();
System.out.println("module: " + module.getName());
System.out.println("named: " + module.isNamed());
}
}
javac and java with modules
The compiler takes the module declaration and the sources, and the launcher is told which module and which class to run with -m. The folder out is the module path, and the compiled module-info.class sits beside the package folder:
javac -d out demo/module-info.java demo/demo/Main.java
java --module-path out -m demo/demo.Main
hello from a module
module: demo
named: true
The name on the left of the slash is the module and the name on the right is the class with its package. The second line confirms the name the class reports, and the third says that the module is named, which is the property the module system adds.
The same class on the classpath prints module: null and named: false, because a class on the classpath is in the unnamed module; that is how a library can tell whether it is running inside a module. A program that needs to know should test that name and not assume either way.
Two modules
The second module needs the first, and its declaration says so with requires. The library exports its one package, and its class is the one the client calls:
module demo.lib {
exports demo.lib;
}
package demo.lib;
public class Greeting {
public static String hello() {
return "hello from the lib module";
}
public static void main(String[] args) {
System.out.println(hello());
}
}
The library has a main of its own so that the two-module run has a class to start; the client has none, because its job in this lesson is the compile. The client requires the library, imports the exported package and calls it, which is allowed precisely because the library exported it. The library is compiled on its own, into its own folder, and then the client is compiled with that folder on the module path:
module demo.app {
requires demo.lib;
}
package demo.app;
import demo.lib.Greeting;
public class Client {
static String message() {
return Greeting.hello();
}
}
javac -d libout lib/module-info.java lib/demo/lib/Greeting.java
javac --module-path libout -d appout app/module-info.java app/demo/app/Client.java
java --module-path libout:appout -m demo.lib/demo.lib.Greeting
hello from the lib module
The client compiles only because demo.app requires a module that exports the package. Remove the requires and the compiler reports that the package is not visible; remove the exports and it reports the same, which is the two halves of the same check. The run starts the library's class and prints its greeting, which proves that the module path holds both modules.
describe-module
The launcher can read a compiled module back and print what it declares:
java --module-path out --describe-module demo
demo file:///tmp/demo/out/
requires java.base mandated
contains demo
The path in the first line is the folder the run used, and it differs on every machine. java.base mandated is the dependency every module has and none writes, and contains demo is the package the module holds. A module with an export prints a line for it as well, which is the shortest way to check that a build produced the declaration a program expects.
Exercises
- Run the single module on the classpath and show that the module name is null.
- Remove the requires of demo.app and read the compiler error.
- Add a second package to the library, export it, and call it from the client.
- Print java --list-modules and count the modules of the JDK.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is a module?
Answer
A named group of packages with a declaration of what it needs and offers
The declaration is module-info.java, and it covers a set of packages.
-
What does
exportsdo in a module?Answer
Makes a package reachable from other modules
A public class in a named module is public only inside it until its package is exported.
-
Which call runs a class of a module?
Answer
java --module-path out -m demo/demo.Main
The launcher needs the module path and the module and class separated by a slash.
-
What does this program print when it runs on the classpath?
public class Q1 { public static void main(String[] args) { System.out.println(Q1.class.getModule().getName()); } }Answer
null
A class on the classpath is in the unnamed module, and its name is null.
-
What does
requiresdeclare?Answer
That this module needs another one at compile time and run time
requires names the dependency, and exports opens a package to the modules that have it.
-
What is the unnamed module?
Answer
The module of the classes on the classpath, which has no name
The classpath is kept for compatibility, and its classes are all in the unnamed module.
-
Why does a module change what public means?
Answer
A public class of an unexported package is not visible to other modules
The module boundary is checked before the class visibility, which is the point of the system.
-
What does this program print when it runs on the classpath?
public class Q2 { public static void main(String[] args) { System.out.println(Q2.class.getModule().isNamed()); } }Answer
false
The classpath puts the class in the unnamed module, and the quiz program runs there.
-
Which command shows what a compiled module declares?
Answer
java --describe-module with the module path
describe-module prints the requires, the exports and the packages the module contains.
-
What does the JDK gain from being modular?
Answer
A program can ship only the modules it uses, and the boundaries are checked
jlink builds a runtime of the needed modules, and the compiler enforces the exports.
The code on this page was built with OpenJDK 21.0.13 (javac and java) and run on Alpine Linux in a Docker container.
Article author: Arthur Isaev