Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Keywords and Statements

Java module declarations (module-info)

Reference for the Java module system: module-info.java, requires, exports, opens, uses and provides, plus the Module API you can run and inspect.

A module is a named group of packages with an explicit description of what it needs and what it shows to others. The description lives in a file called module-info.java at the root of the sources. The module system (Java Platform Module System, JPMS, introduced in Java 9) gives strong encapsulation: a public class in a package that the module does not export cannot be used from outside.

The JDK itself is split into modules (java.base, java.sql, java.net.http, and so on). Most application code still runs on the classpath, in the so-called unnamed module, and works without any module-info.java.

Java
// module-info.java
module com.example.shop {
    requires java.sql;                     // needs another module
    requires transitive java.logging;      // readers of this module also read java.logging
    exports com.example.shop.api;          // visible to everyone
    exports com.example.shop.spi to com.example.plugins;   // qualified export
    opens com.example.shop.model;          // deep reflection allowed (frameworks)
    uses com.example.shop.spi.Payment;     // service consumer
    provides com.example.shop.spi.Payment with com.example.shop.card.CardPayment;
}

The sandbox compiles a single source file, so module-info.java itself is shown read-only. The examples below inspect the runtime module graph instead.

Try it

Java Which module does a class belong to?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Inspecting a module descriptor

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
[open] module name {
    directive*
}
Directive Meaning
requires m; This module reads module m at compile time and run time.
requires transitive m; Also grants m to every module that requires this one (implied readability).
requires static m; Needed to compile, optional at run time.
exports p; The public types of package p are accessible to all modules.
exports p to m1, m2; Qualified export, only to the named modules.
opens p; Allows reflective access to all members of p at run time (also private ones).
opens p to m; Qualified opens.
uses S; This module consumes service S through ServiceLoader.
provides S with Impl; This module supplies implementation Impl for service S.
open module name { } Opens every package for reflection.

Usage notes

  • module, requires, exports, ... are restricted keywords: they are only keywords inside module-info.java, so int module = 1; and a method named exports() remain legal.
  • Readability versus accessibility: a module can use a type only if it reads the defining module (requires) and the package is exported to it. java.base is always read implicitly.
  • Reflection: exports does not allow reflecting on private members; opens does. Frameworks that use field injection or serialization often need opens. Without it you get InaccessibleObjectException.
  • Cyclic requires are forbidden, and two modules cannot export or contain the same package (split packages).
  • Names: module names follow package naming (reverse domain), and a module name need not match a package name.
  • Automatic modules: a plain JAR placed on the module path becomes an automatic module, which exports every package and reads all modules. It helps with migration to modules, but it is a temporary state.
  • Tools: java --module-path mods -m com.example.shop/com.example.shop.Main runs a module, jar --describe-module and java --describe-module show descriptors, jlink builds a trimmed runtime that contains only the modules you need, and java --list-modules lists the available ones.
  • Do you need it? Applications can skip modules entirely. They pay off in libraries that want a hard API boundary and in applications that ship a custom runtime image.
  • Strong encapsulation of the JDK: internal packages such as jdk.internal.misc are not exported, so user code cannot use them (see the last line of the first example).