I originally wrote this post for the Java Advent Calendar, where it was published on December 10th.

This post is part of an ongoing series about Project Jigsaw. In the recommended order (which is different from their publication order) these are:

The corresponding tag lists more articles about the topic.


Project Jigsaw will bring modularization to the Java platform and according to the original plan it was going to be feature complete on the 10th of December. So here we are but where is Jigsaw?

Surely a lot happened in the last six months: The prototype came out, the looming removal of internal APIs caused quite a ruckus, the mailing list is full of critical discussions about the project’s design decisions, and JavaOne saw a series of great introductory talks by the Jigsaw team. And then Java 9 got delayed for half year due to Jigsaw.

But let’s ignore all of that for now and just focus on the code. 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 an 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.

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 80 of them (have a look at them with

java -listmods
).

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 no two modules read each other, 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 hidden from the outside world as much as a non-public type in an exported package. Which is even more hidden than package-private types are today 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 -c \
	--file=mods/advent.jar \
	--main-class=advent.Main \
	${compiled class files}
# run (specify a module path and simply name to module to run)
java -mp mods -m 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

-mp mods
, this is called the module path) and which module we would like to launch (with
-m advent
).

Splitting Into Modules

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

Made-up Rationale

The “surprise API”, i.e.

Surprise
and
SurpriseFactory
, is a great success and we want to separate it from the monolith.

The factories that create the surprises turn out to be very dynamic. A lot of work is being done here, they change frequently and which factories are used differs from release to release. So we want to isolate them.

At the same time we plan to create a large Christmas application of which the calendar is only one part. So we’d like to have a separate module for that as well.

We end up with these modules:

  • surprise
    Surprise
    and
    SurpriseFactory
  • calendar – the calendar, which uses the surprise API
  • factories – the
    SurpriseFactory
    implementations
  • main – the original application, now hollowed out to the class
    Main

Looking at their dependencies we see that surprise depends on no other module. Both calendar and factories make use of its types so they must depend on it. Finally, main uses the factories to create the calendar so it depends on both.

jigsaw-hands-on-splitting-into-modules

Implementation

The first step is to reorganize the source code. We’ll stick with the directory structure as proposed by the official quick start guide and have all of our modules in their own folders below

src
:

src
  - advent.calendar: the "calendar" module
      - org ...
      module-info.java
  - advent.factories: the "factories" module
      - org ...
      module-info.java
  - advent.surprise: the "surprise" module
      - org ...
      module-info.java
  - advent: the "main" module
      - org ...
      module-info.java
.gitignore
compileAndRun.sh
LICENSE
README

To keep this readable I truncated the folders below

org
. What’s missing are the packages and eventually the source files for each module. See it on GitHub in its full glory.

Let’s now see what those module infos have to contain and how we can compile and run the application.

surprise

There are no required clauses as surprise has no dependencies. (Except for

java.base
, which is always implicitly required.) It exports the package
advent.surprise
because that contains the two classes
Surprise
and
SurpriseFactory
.

So the

module-info.java
looks as follows:

module advent.surprise {
	// requires no other modules
	// publicly accessible packages
	exports advent.surprise;
}

Compiling and packaging is very similar to the previous section. It is in fact even easier because surprises contains no main class:

# compile
javac -d classes/advent.surprise ${source files}
# package
jar -c --file=mods/advent.surprise.jar ${compiled class files}

calendar

The calendar uses types from the surprise API so the module must depend on surprise. Adding

requires advent.surprise
to the module achieves this.

The module’s API consists of the class

Calendar
. For it to be publicly accessible the containing package
advent.calendar
must be exported. Note that
CalendarSheet
, private to the same package, will not be visible outside the module.

But there is an additional twist: We just made

Calendar.createWithSurprises(List<SurpriseFactory>)
publicly available, which exposes types from the surprise module. So unless modules reading calendar also require surprise, Jigsaw will prevent them from accessing these types, which would lead to compile and runtime errors.

Marking the requires clause as

public
fixes this. With it any module that depends on calendar also reads surprise. This is called implied readability.

The final module-info looks as follows:

module advent.calendar {
	// required modules
	requires public advent.surprise;
	// publicly accessible packages
	exports advent.calendar;
}

Compilation is almost like before but the dependency on surprise must of course be reflected here. For that it suffices to point the compiler to the directory

mods
as it contains the required module:

# compile (point to folder with required modules)
javac -mp mods \
	-d classes/advent.calendar \
	${source files}
# package
jar -c \
	--file=mods/advent.calendar.jar \
	${compiled class files}

factories

The factories implement

SurpriseFactory
so this module must depend on surprise. And since they return instances of
Surprise
from published methods the same line of thought as above leads to a
requires public
clause.

The factories can be found in the package

advent.factories
so that must be exported. Note that the public class
AbstractSurpriseFactory
, which is found in another package, is not accessible outside this module.

So we get:

module advent.factories {
	// required modules
	requires public advent.surprise;
	// publicly accessible packages
	exports advent.factories;
}

Compilation and packaging is analog to calendar.

main

Our application requires the two modules calendar and factories to compile and run. It still has no API to export.

module advent {
	// required modules
	requires advent.calendar;
	requires advent.factories;
	// no exports
}

Compiling and packaging is like with last section’s single module except that the compiler needs to know where to look for the required modules:

#compile
javac -mp mods \
	-d classes/advent \
	${source files}
# package
jar -c \
	--file=mods/advent.jar \
	--main-class=advent.Main \
	${compiled class files}
# run
java -mp mods -m advent

Services

Jigsaw enables loose coupling by implementing the service locator pattern, where the module system itself acts as the locator. Let’s see how that goes.

Made-up Rationale

Somebody recently read a blog post about how cool loose coupling is. Then she looked at our code from above and complained about the tight relationship between main and factories. Why would main even know factories?

Because…

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());
}

Really? Just to instantiate some implementations of a perfectly fine abstraction (the

SurpriseFactory
)?

And we know she’s right. Having someone else provide us with the implementations would remove the direct dependency. Even better, if said middleman would be able to find all implementations on the module path, the calendar’s surprises could easily be configured by adding or removing modules before launching.

This is indeed possible with Jigsaw. We can have a module specify that it provides implementations of an interface. Another module can express that it uses said interface and find all implementations with the

ServiceLocator
.

We use this opportunity to split factories into chocolate and quote and end up with these modules and dependencies:

  • surprise
    Surprise
    and
    SurpriseFactory
  • calendar – the calendar, which uses the surprise API
  • chocolate – the
    ChocolateFactory
    as a service
  • quote – the
    QuoteFactory
    as a service
  • main – the application; no longer requires individual factories

jigsaw-hands-on-services

Implementation

The first step is to reorganize the source code. The only change from before is that

src/advent.factories
is replaced by
src/advent.factory.chocolate
and
src/advent.factory.quote
.

Lets look at the individual modules.

surprise and calendar

Both are unchanged.

chocolate and quote

Both modules are identical except for some names. Let’s look at chocolate because it’s more yummy.

As before with factories the module

requires public
the surprise module.

More interesting are its exports. It provides an implementation of

SurpriseFactory
, namely
ChocolateFactory
, which is specified as follows:

provides advent.surprise.SurpriseFactory
	with advent.factory.chocolate.ChocolateFactory;

Since this class is the entirety of its public API it does not need to export anything else. Hence no other export clause is necessary.

We end up with:

module advent.factory.chocolate {
	// list the required modules
	requires public advent.surprise;
	// specify which class provides which service
	provides advent.surprise.SurpriseFactory
		with advent.factory.chocolate.ChocolateFactory;
}

Compilation and packaging is straight forward:

javac -mp mods \
	-d classes/advent.factory.chocolate \
	${source files}
jar -c \
	--file mods/advent.factory.chocolate.jar \
	${compiled class files}

main

The most interesting part about main is how it uses the ServiceLocator to find implementation of SurpriseFactory. From its main method:

List surpriseFactories = new ArrayList<>();
ServiceLoader.load(SurpriseFactory.class)
	.forEach(surpriseFactories::add);

Our application now only requires calendar but must specify that it uses

SurpriseFactory
. It has no API to export.

module advent {
	// list the required modules
	requires advent.calendar;
	// list the used services
	uses advent.surprise.SurpriseFactory;
	// exports no functionality
}

Compilation and execution are like before.

And we can indeed change the surprises the calendar will eventually contain by simply removing one of the factory modules from the module path. Neat!

Like My Posts About Project Jigsaw?
Then Get My Book!

  • In-depth introduction to Java's new module system:
    • essential concepts and advanced topics
    • compatability and migration
    • tool support and much more...
  • Published by Manning
    • early access in Fall 2016
    • available in Spring 2017
  • Subscribe to my newsletter to stay tuned!
    (And maybe even get a peek.)

Summary

So that’s it. We have seen how to move a monolithic application into a single module and how we can split it up into several. We even used a service locator to decouple our application from concrete implementations of services. All of this is on GitHub so check it out to see more code!

But there is lots more to talk about! Jigsaw brings a couple of incompatibilities but also the means to solve many of them. And we haven’t talked about how reflection interacts with the module system and how to migrate external dependencies.

If these topics interest you, watch this tag as I will surely write about them over the coming months.

The post Jigsaw Hands-On Guide appeared first on blog@CodeFX.