The Java 9 Module System

Beyond the Basics

Nicolai Parlog

codefx.org / @nipafx

Code Europe

@code_europe

Public Service Announcement

I assume you know the JPMS basics
there’s much to talk about
⇝ this is only about "advanced" JPMS features
slides at slides.codefx.org

Java Module System Basics

The very short version

Modules

have a unique name
express their dependencies
export specific packages
and hide the rest

These information

are defined in module-info.java
get compiled to module-info.class
end up in JAR root folder

Readability

Modules express dependencies with requires clauses:

module A {
	requires B;
}

module system checks all dependencies
(⇝ reliable configuration)
lets module read its dependencies

Accessibility

Modules export packages with exports clauses

module B {
	exports p;
}

Code in module A can only access Type in module B if:

Type is public
Type is in an exported package
A reads B

(⇝ strong encapsulation)

Jigsaw Advent Calendar

A simple example

Find it on GitHub!

Structure

Code

public static void main(String[] args) {
	List<SurpriseFactory> factories = asList(
		new ChocolateFactory(), new QuoteFactory());
	Calendar cal = Calendar.create(factories);
	println(cal.asText());
}

Module Structure

module surprise {
	// requires no other modules
	exports org.codefx.advent.surprise;
}

module calendar {
	requires surprise;
	exports org.codefx.advent.calendar;
}

module factories {
	requires surprise;
	exports org.codefx.advent.factories;
}

module advent {
	requires calendar;
	requires factories;
	requires surprise;
}

Module Creation

Compilation, Packaging, Execution

# compile all modules at once
$ javac -d classes
    --module-source-path "src"
    --module advent
# package one by one, eventually advent
$ jar --create
    --file mods/advent.jar
    --main-class advent.Main
    ${*.class}
# launch the application
$ java --module-path mods --module advent

Java Module System Beyond The Basics

Transitive Dependencies

Optional Dependencies

Services

Qualified Exports

Reflective Access

Java Module System Beyond The Basics

Transitive Dependencies

Optional Dependencies

Services

Qualified Exports

Reflective Access

Transitive Dependencies

Not all dependencies are created equal:

most are used within a module
some are used on the boundary
between modules

Transitive dependencies are about the latter.

Exposing dependencies

Example in calendar exposing surprise:

public static Calendar create(
		List<SurpriseFactory> factories) {
	// ...
}

⇝ Module calendar is unusable without surprise!

Try and Error?

How can users of exposing module
determine required dependencies?

Try and error?

No!

Implied Readability

Exposing module can mark dependencies
on exposed modules with
requires transitive:

module A {
	requires transitive B;
}

A reads B as usual
modules reading A will read B
without having to require it

⇝ A implies readability of B

Implied Readability

Applied to the advent calendar:

module calendar {
	requires transitive surprise;
	// ...
}

Further Applications

Implied readability is surprisingly versatile

aggregator modules
splitting modules up
even merging modules
renaming modules

Aggregator Modules

Making it easier to consume
calendar, factories, surprise:

module adventcalendar {
	requires transitive calendar;
	requires transitive factories;
	requires transitive surprise;
}

Splitting Modules

If factories gets split into
api, chocolate, and quotes:

module factories {
	requires transitive factory.api;
	requires transitive factory.chocolate;
	requires transitive factory.quotes;
}

Merging Modules

If calendar, factories, surprise
are merged into adventcalendar:

module calendar {
	requires transitive adventcalendar;
}

module factories {
	requires transitive adventcalendar;
}

module surprise {
	requires transitive adventcalendar;
}

Careful: Users suddenly depend on a large module!

Renaming Modules

If factories becomes surprisefactories:

module factories {
	requires transitive surprisefactories;
}

Summary

With A requires transitive B:

A reads B
any module reading A reads B

Applications:

make API usable without further dependencies
aggregator modules
splitting, merging, renaming modules

More at codefx.org:

Implied Readability

Java Module System Beyond The Basics

Transitive Dependencies

Optional Dependencies

Services

Qualified Exports

Reflective Access

Optional Dependencies

Not all dependencies are equally required:

some are needed for a module to function
some can be absent and code adapts
some are only needed to enhance
another module’s features

Optional dependencies are about the latter two.

Adapting Code

Use case:

a library may be absent from some deployments
code is aware and does not call absent modules

Example:

each SurpriseFactory implementation
has its own module
advent works without any specific factory

Adapting Code

Enhancing A Module

Use case:

a project may provide usability functions
for other libraries
such code will not be called if library modules
are absent

Example:

hypothetical library uber-lib
provides usability functions for various libraries

Enhancing A Module

Conundrum

With what we know so far:

for code to compile against another module
that module has to be required
a required module has to be present
at launch time

⇝ If a module’s types are used
it has to be present at run time

(Reliable configuration!)

Optional Dependencies

Dependency can be marked requires static:

module A {
	requires static B;
}

at compile time: A requires B as usual
at run time:
- if B is present, A reads B
- otherwise, app can launch
  but access to B can fail

Adapting Code

For advent and the two factories:

module advent {
	requires calendar;
	requires surprise;
	requires static factory.chocolate;
	requires static factory.quote;
}

Adapting Code

Checking whether module is present:

Optional<SurpriseFactory> createChocolateFactory() {
	if (isModulePresent("factory.chocolate"))
		return Optional.of(new ChocolateFactory());
	else
		return Optional.empty();
}

Enhancing A Module

For uber-lib:

module uber.lib {
	requires static com.google.guava;
	requires static org.apache.commons.lang;
	requires static io.vavr;
	requires static com.aol.cyclops;
}

Assumptions:

nobody calls into Guava part without using Guava
no runtime checks necessary

Summary

With A requires static B:

at compile time: A requires B as usual
at runtime: B may be absent

Two kinds of applications:

modules with code adapting to absence
utility libraries that aren’t called
without that dependency

More at codefx.org:

Optional Dependencies

Java Module System Beyond The Basics

Transitive Dependencies

Optional Dependencies

Services

Qualified Exports

Reflective Access

Dependency Inversion?

Service Locator Pattern

Consumers and implementations
of an API should be decoupled.

Service locator pattern:

service registry as central arbiter
implementors inform registry
consumers call registry to get implementations

Services in JPMS

In the JPMS:

modules declare which services they use
modules declare which services they provide
ServiceLoader is the registry
code can interact with it to load services

Service Declarations

Module declarations:

// consumer
module A {
	uses some.Service;
}

// provider
module B {
	provides some.Service
		with some.Type;
}

Loading Services

A never "sees" providers like B
module system picks up all providers
A can get providers from ServiceLoader

ServiceLoader.load(Service.class)

Factory Services

module advent {
	requires calendar;
	uses surprise.SurpriseFactory;
}

module factory.chocolate {
	requires surprise;
	provides surprise.SurpriseFactory
		with factory.quote.ChocolateFactory;
}

module factory.quote {
	requires surprise;
	provides surprise.SurpriseFactory
		with factory.quote.QuoteFactory;
}

Factory Services

Factory Services

public static void main(String[] args) {
	List<SurpriseFactory> factories = ServiceLoader
		.load(SurpriseFactory.class).stream()
		.map(Provider::get)
		.collect(toList());
	Calendar cal = Calendar.create(factories);
	System.out.println(cal.asText());
}

Summary

To decouple API consumers and providers:

consumer uses Service
provider provides Service with Impl

Module system is service locator;
request implementations from ServiceLoader:

ServiceLoader.load(Service.class)

Java Module System Beyond The Basics

Transitive Dependencies

Optional Dependencies

Services

Qualified Exports

Reflective Access

Qualified Exports

So far, exported packages are visible
to every reading module.

What if a set of modules wants to share code?

Known Problem

Similar to utility classes:

if class should be visible outside of package,
it has to be public ⇝ visible to everybody
if package should be visible outside of module,
it has to be exported ⇝ visible to everybody

Module system fixes the former.
What about the latter?

Qualified Exports

module A {
	exports some.pack to B;
}

B can access some.pack
as if regularly exported
other modules can not access it
as if not exported at all

Factory Utilities

To ease implementation of SurpriseFactory:

create new module factory
add class AbstractSurpriseFactory
export that package only to
factory implementation modules

module factory {
	requires transitive surprise;
	exports factory
		to factory.chocolate, factory.quote;
}

Summary

With A exports pack to B:

only B can access types in some.pack
other modules behave as if some.pack
is not exported

Use to share sensible code between modules.

Java Module System Beyond The Basics

Transitive Dependencies

Optional Dependencies

Services

Qualified Exports

Reflective Access

Exporting a package makes it public API:

modules can compile code against it
clients expect it to be stable

What if a type is only meant
to be accessed via reflection?

(Think Spring, Hibernate, etc.)

Open Packages

module A {
	opens some.pack;
}

at compile time:
types in some.pack are not accessible
at run time:
all types and members in some.pack
are accessible

A qualified variant (opens to) exists.

Open Modules

open module A {
	// no more `opens` clauses
}

The same as open packages
but for all of them!

Summary

With open modules or open packages:

code can be made accessible
at run time only
particularly valuable to open
for reflection

Use to make types available for reflection
without making them public API.

Command Line Options

The module system is pretty strict but…

… not all modules are well-designed
… not all use cases were intended

What to do then?

Command line options to the rescue!
(I often call them "escape hatches".)

Command Line Options

All command line flags can be applied
to javac and java!

When used during compilation,
they do not change the resulting
module descriptor!

Add Modules

If a module is not required,
it might not make it into the module graph.

Help it get there with --add-modules:

$ java --module-path mods
#   --add-modules <module>(,<module>)*
    --add-modules java.xml.ws.annotation
    --module advent

Add JavaEE Modules

JavaEE modules are not resolved by default!

java.activation
java.corba
java.transaction
java.xml.bind
java.xml.ws
java.xml.ws.annotation

They need to be added with --add-modules!

Add Readability Edges

Maybe a module in the graph is not readable
by another but you need it to be.

Add readability edges with --add-reads:

$ java --module-path mods
#   --add-reads <module>=<target>(,<more>)*
    --add-reads advent=factories
    --module advent

Add Exports

A common case:

A module needs types that
the owning module doesn’t export.

Export them with --add-exports:

$ java --module-path mods
#   --add-exports <module>/<package>=<target>
    --add-exports factories/factory.quotes=advent
    --module advent

Use target ALL-UNNAMED to export to all modules.

Open Packages

Another common case:

A module reflects on types from a package that
the owning module doesn’t open.

Open packages with add-opens:

$ java --module-path mods
#   --add-opens <module>/<package>=<target>
    --add-opens factories/factory.quotes=advent
    --module advent

Use target ALL-UNNAMED to open to all modules.

(It is not possible to open an entire module.)

Patch Modules

Maybe you have a package split…

Mend it with --patch-module:

$ java --module-path mods
    --add-modules java.xml.ws.annotation
#   --patch-module <module>=<JAR>
    --patch-module java.xml.ws.annotation=jsr305.jar
    --module advent

All classes from jsr305.jar are put
into java.xml.ws.annotation.

Patch Module

By putting JAR content into a module A:

split packages can be mended
A needs to read JAR’s dependencies,
which need to export used packages
modules using JAR content need to read A
and A needs to export used packages

Often used with --add-reads and --add-exports.

Summary

Edit module graph with:

--add-modules to add modules
--add-reads to add readability edges
--add-exports to export packages to modules
--add-opens to open packages to modules
--patch-module to add classes to module

The latter two accept ALL-UNNAMED as target.

More at codefx.org:

Five Command Line Options To Hack The JPMS

Incremental Modularization

Moving Into Module Land

Why Is It Even An Option?

most module systems are "in or out",
but modularized JDK and legacy JARs
have to cooperate!
there is a boundary between
legacy and modules

Incremental modularization means
moving that boundary.

Enablers

Incremental modularization is enabled by two features:

Unnamed Module(s)
Automatic Modules

And the fact that module and class path coexist:

modular JARs can be put on either
"regular" JARs can be put on either

The Unnamed Module

Why The Class Path "Just Works"

Definition

The Unnamed Module
contains all JARs on the class path
(including modular JARs).

has no name (surprise!)
can read all modules
exports all packages

Inside the unnamed module
"the chaos of the class path" lives on.

Example

Put all your JARs on the class path.

No Access

what if your code was modularized?
and your dependencies were not?
proper modules can not depend on
"the chaos on the class path"
this is not possible:
```
module advent {
	requires unnamed;
}
```

No Access

Automatic Modules

From Modules To The Class Path

Definition

An Automatic Module
is created for each "regular" JAR
on the module path.

name defined by manifest entry
AUTOMATIC-MODULE-NAME or
derived from JAR name
can read all modules
(including the Unnamed Module)
exports all packages

Example

put guava-19.0.jar on the module path
then this works:
```
module advent {
	requires guava;
}
```

Example

What Goes Where?

	Class Path	Module Path
Regular JAR	Unnamed Module	Automatic Module
Modular JAR	Unnamed Module	Explicit Module

Class Path

Module Path

Regular JAR

Unnamed Module

Automatic Module

Modular JAR

Unnamed Module

Explicit Module

Unnamed or named module?
The user decides, not the maintainer!

Modularization Strategies

Three strategies emerge:

bottom-up
top-down
inside-out

Bottom-Up

Works best for projects without
unmodularized dependencies
(libraries).

turn project JARs into modules
they still work on the class path
clients can move them to the module path
whenever they want

Top-Down

Required for projects with
unmodularized dependencies
(applications).

turn project JARs into modules

Top-Down

modularized dependencies:
- require direct ones
- put all on the module path
unmodularized dependencies:
- require direct ones with automatic name
- put direct ones on the module path
- put others on the class path

Top-Down

When dependencies get modularized:

hopefully the name didn’t change
if they are already on the module path,
nothing changes
otherwise move them there
check their dependencies

Inside-Out

What about published projects with
unmodularized dependencies
(libraries)?

top-down mostly works
but there’s an important detail
about automatic module names!

Inside-Out

Automatic Module Names

automatic module name may
be based on JAR name
file names can differ
across build environments
module name can change
when project gets modularized

⇝ Such automatic module names are unstable.

Inside-Out

Impossible Module Requirements

dependencies might require the same
module by different names
the module system does not support that
there is no way to launch that application!

⇝ Do not publish modules
that depend on automatic modules
whose names are based on file names!

Inside-Out

Manifest Entry

thanks to manifest entry,
projects can publish their module name
assumption is that it won’t change
when project gets modularized
that makes these names stable

⇝ It is ok to publish modules
that depend on automatic modules
whose names are based on manifest entry.

Analyzing Dependencies With JDeps

Helping You Modularize!

About JDeps

a command line tool
analyzes bytecode to
detect dependencies
exists since Java 8
really shines with modules

Simplest Invocation

$ jdeps sh-2.6.3.jar

> sh-2.6.3.jar -> java.base
> sh-2.6.3.jar -> java.datatransfer
> sh-2.6.3.jar -> java.desktop
# ... truncated more module dependencies ...
>    edu.udo.sh -> com.beust.jcommander  not found
>    edu.udo.sh -> edu.udo.sh.data       sh-2.6.3.jar
>    edu.udo.sh -> edu.udo.sh.gui        sh-2.6.3.jar
>    edu.udo.sh -> edu.udo.sh.gui.util   sh-2.6.3.jar
>    edu.udo.sh -> edu.udo.sh.util       sh-2.6.3.jar
>    edu.udo.sh -> java.io               java.base
>    edu.udo.sh -> java.lang             java.base
>    edu.udo.sh -> javax.swing           java.desktop
# ... truncated many more package dependencies ...

Analyzing Dependencies

$ jdeps
	--class-path 'libs/*' -recursive
	sh-2.6.3.jar

# ... truncated split package warnings ...
# ... truncated some module/JAR dependencies...
> sh-2.6.3.jar -> libs/commons-codec-1.6.jar
> sh-2.6.3.jar -> libs/commons-io-2.4.jar
> sh-2.6.3.jar -> libs/dom4j-1.6.1.jar
> sh-2.6.3.jar -> libs/exp4j-0.1.38.jar
> sh-2.6.3.jar -> libs/guava-18.0.jar
# ... truncated more module/JAR dependencies...
# ... truncated many, many package dependencies ...

Creating Graphs

$ jdeps
	--class-path 'libs/*' -recursive
	--dot-output dots
	sh-2.6.3.jar
# sed -i 's/-1.0-SNAPSHOT.jar//g' summary.dot
# sed -i '/java.base/d' summary.dot
$ dot -Tpng -O dots/summary.dot

JDK-Internal APIs

$ jdeps
	--class-path 'libs/*' -recursive
	--jdk-internals
	sh-2.6.3.jar

Creating Runtime Images With JLink

Custom-Made For Your Application

Remember This?

Benefiting From JDK Modularization

Create a JDK install with just the code you need:

know which modules your app uses (⇝ jdeps)
create an image with those modules (⇝ jlink)

This is about jlink.

A Minimal JDK Image

Create with jlink

$ jlink
#   define output folder for the image
    --output jdk
#   where to find modules?
    --module-path $JAVA_HOME/jmods
#   which modules to add (includes dependencies!)
    --add-modules java.base

Try it out:

$ jdk/bin/java --list-modules
> java.base

Image For A Backend

Say you use JAX-WS, JAXP, JAXB, JDBC, and JUL:

$ jlink
    --output jdk
    --module-path $JAVA_HOME/jmods
    --add-modules java.xml.ws,java.xml,java.xml.bind
	--add-modules java.sql,java.logging

Image For A Backend

$ jdk/bin/java --list-modules
> java.activation
> java.base
> java.compiler
> java.datatransfer
> java.desktop
> java.logging
> java.management
> java.prefs
> java.sql
> java.xml
> java.xml.bind
> java.xml.ws
> java.xml.ws.annotation
> jdk.httpserver
> jdk.unsupported

Image Including Your App

To create an image for your app
all JARs need to be modularized!
(Including dependencies.)

$ jlink
    --output jdk
    --module-path $JAVA_HOME/jmods:mods
    --add-modules advent
#   services are not resolves automatically
    --add-modules factory.surprise,factory.chocolate

Launching the app:

jdk/bin/java -module advent

Creating A Launcher

You can even create a launcher:

$ jlink
    --output jdk
    --module-path $JAVA_HOME/jmods:mods
    --add-modules advent,...
#   --launcher <name>=<module>[/<mainclass>]
    --launcher calendar=advent

Launching the app: