Java Module System Hands-On Guide

In this post we'll take an existing demo application and modularize it with Java 9. If you want to follow along, head over to GitHub, where all of the code can be found. The setup instructions are important to get the scripts running with Java 9. For brevity, I removed the prefix org.codefx.demo from all package, module, and folder names in this article.

The Application Before Jigsaw

Even though I do my best to ignore the whole Christmas kerfuffle, it seemed prudent to have the demo uphold the spirit of the season. So it models an advent calendar:

• There is a calendar, which has 24 calendar sheets.
• Each sheet knows its day of the month and contains a surprise.
• The death march towards Christmas is symbolized by printing the sheets (and thus the surprises) to the console.

Of course the calendar needs to be created first. It can do that by itself but it needs a way to create surprises. To this end it gets handed a list of surprise factories. This is what the main method looks like:

public static void main(String[] args) {
        List<SurpriseFactory> surpriseFactories = Arrays.asList(
                        new ChocolateFactory(),
                        new QuoteFactory()
        );
        Calendar calendar =
                Calendar.createWithSurprises(surpriseFactories);
        System.out.println(calendar.asText());
}

The initial state of the project is by no means the best of what is possible before Jigsaw. Quite the contrary, it is a simplistic starting point. It consists of a single module (in the abstract sense, not the Jigsaw interpretation) that contains all required types:

• "Surprise API" - Surprise and SurpriseFactory (both are interfaces)
• "Calendar API" - Calendar and CalendarSheet to create the calendar
• Surprises - a couple of Surprise and SurpriseFactory implementations
• Main - to wire up and run the whole thing.

Compiling and running is straight forward (commands for Java 8):

# compile
javac -d classes/advent ${source files}
# package
jar -cfm jars/advent.jar ${manifest and compiled class files}
# run
java -jar jars/advent.jar

Entering Jigsaw Land

The next step is small but important. It changes nothing about the code or its organization but moves it into a Jigsaw module.

Modules

So what's a module? To quote the highly recommended State of the Module System:

A module is a named, self-describing collection of code and data. Its code is organized as a set of packages containing types, i.e., Java classes and interfaces; its data includes resources and other kinds of static information.

To control how its code refers to types in other modules, a module declares which other modules it requires in order to be compiled and run. To control how code in other modules refers to types in its packages, a module declares which of those packages it exports.

(The last paragraph is actually from an old version of the document but I like how it summarizes dependencies and exports.)

So compared to a JAR a module has a name that is recognized by the JVM, declares which other modules it depends on and defines which packages are part of its public API.

Name

A module's name can be arbitrary. But to ensure uniqueness it is recommended to stick with the inverse-URL naming schema of packages. So while this is not necessary it will often mean that the module name is a prefix of the packages it contains.

Dependencies

A module lists the other modules it depends on to compile and run. This is true for application and library modules but also for modules in the JDK itself, which was split up into about 100 of them (have a look at them with java --list-modules).

Again from the design overview:

When one module depends directly upon another in the module graph then code in the first module will be able to refer to types in the second module. We therefore say that the first module reads the second or, equivalently, that the second module is readable by the first.

[...]

The module system ensures that every dependence is fulfilled by precisely one other module, that the module graph is acyclic, that every module reads at most one module defining a given package, and that modules defining identically-named packages do not interfere with each other.

When any of the properties is violated, the module system refuses to compile or launch the code. This is an immense improvement over the brittle classpath, where e.g. missing JARs would only be discovered at runtime, crashing the application.

It is also worth to point out that a module is only able to access another's types if it directly depends on it. So if A depends on B, which depends on C, then A is unable to access C unless it requires it explicitly.

Exports

A module lists the packages it exports. Only public types in these packages are accessible from outside the module.

This means that public is no longer really public. A public type in a non-exported package is as inaccessible to the outside world as a non-public type in an exported package. Which is even more inaccessible than package-private types are before Java 9 because the module system does not even allow reflective access to them. As Jigsaw is currently implemented command line flags are the only way around this.

Implementation

To be able to create a module, the project needs a module-info.java in its root source directory:

module advent {
    // no imports or exports
}

Wait, didn't I say that we have to declare dependencies on JDK modules as well? So why didn't we mention anything here? All Java code requires Object and that class, as well as the few others the demo uses, are part of the module java.base. So literally every Java module depends on java.base, which led the Jigsaw team to the decision to automatically require it. So we do not have to mention it explicitly.

The biggest change is the script to compile and run (commands for Java 9):

# compile (include module-info.java)
javac -d classes/advent ${source files}
# package (add module-info.class and specify main class)
jar --create \
        --file=mods/advent.jar \
        --main-class=advent.Main \
        ${compiled class files}
# run (specify a module path and simply name to module to run)
java --module-path mods --module advent

We can see that compilation is almost the same - we only need to include the new module-info.java in the list of classes.

The jar command will create a so-called modular JAR, i.e. a JAR that contains a module. Unlike before we need no manifest anymore but can specify the main class directly. Note how the JAR is created in the directory mods.

Utterly different is the way the application is started. The idea is to tell Java where to find the application modules (with --module-path mods, this is called the module path) and which module we would like to launch (with --module advent).

Splitting Into Modules

Now it's time to really get to know Jigsaw and split that monolith up into separate modules.

Continue reading %Java Module System Hands-On Guide%

by Nicolai Parlog via SitePoint