Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Language Features by Version

Java modules (JPMS)

Reference for the Java Platform Module System: module-info.java directives, requires, exports, opens, services, and inspecting modules at run time.

The Java Platform Module System (JPMS, introduced in Java 9) lets you group packages into a named module with a declared interface. A module states which other modules it needs (requires) and which of its packages other code may use (exports). Everything else inside the module is hidden, even public classes, which gives Java real encapsulation above the package level.

The JDK itself is split into modules (java.base, java.sql, java.net.http, ...). java.base is always present and implicitly required. Your own code is modular only if the root of its source tree contains a file named module-info.java. Code without one lives in the unnamed module and can read everything; that is what the source launcher on this page uses, so the module declarations below are read-only and the runnable examples inspect the JDK's modules and build descriptors by hand.

Java
module com.example.shop {
    requires java.sql;
    requires transitive com.example.model;
    exports com.example.shop.api;
    opens com.example.shop.entity to com.fasterxml.jackson.databind;
    uses com.example.shop.spi.PaymentProvider;
    provides com.example.shop.spi.PaymentProvider with com.example.shop.pay.CardPayments;
}

Try it

Java Inspecting the JDK's modules

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 Building a module descriptor in code

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.

The directives

Directive Meaning
requires M; This module needs module M at compile time and run time.
requires transitive M; Anyone who requires this module also reads M (use it when M's types appear in your public API).
requires static M; M is needed to compile but optional at run time.
exports P; Public types of package P are accessible to all modules.
exports P to A, B; Only modules A and B may access P (qualified export).
opens P; P is open to deep reflection (private members) at run time.
opens P to A; Reflection access only for module A; frameworks like Jackson or Hibernate need this.
open module M { } Every package is open for reflection.
uses S; This module consumes service interface S via ServiceLoader.
provides S with C; This module supplies implementation C of service S.

exports controls compile-time and run-time access to public types; opens controls run-time reflective access to all members. A package can be exported, opened, both, or neither.

Command line

Terminal
# Read-only: tools shown for reference
javac -d out --module-source-path src $(find src -name "*.java")
java --module-path out --module com.example.shop/com.example.shop.Main

java --list-modules              # modules in the runtime image
java --describe-module java.sql  # what a module requires and exports
jdeps --module-path libs app.jar # dependency analysis
jlink --add-modules java.base,java.sql --output slim-jre   # custom runtime image

Usage notes

  • A module name follows package naming rules and should be unique, normally the reverse-DNS name of the root package. Dots only, no hyphens.
  • Cyclic dependencies between modules are not allowed. Split packages (the same package in two modules) are not allowed either.
  • Libraries on the module path without a module-info become automatic modules; the JAR file name (or an Automatic-Module-Name manifest entry) provides the name. Libraries on the class path all end up in the unnamed module.
  • Class.forName and reflection see only exported or opened packages. If a framework fails with InaccessibleObjectException, add opens for the package, or --add-opens on the command line as a last resort.
  • Since Java 17 the JDK's own internals (sun.*, jdk.internal.*) are strongly encapsulated; the old flag --illegal-access no longer has any effect.
  • Many applications never need module-info.java. It pays off for libraries with a clear public API and for jlink runtime images.
  • Java 25's import module java.base; is an unrelated, convenient source-level feature; see simple source files.