The Java 9 Module System

Beyond the basics

Nicolai Parlog

codefx.org / @nipafx

Zürich

@VoxxedZurich

Breaking News!

But before we come to that…​

Old News!

Oracle JDK ≠ OpenJDK

  • no free Oracle JDK from Java 11 on

  • Oracle ships OpenJDK builds

  • but only for current major version:
    ⇝ 10 ⇝ 10.0.1 ⇝ 10.0.4
    ⇝ 11 ⇝ 11.0.1 ⇝ 11.0.4
    ⇝ 12 ⇝ 12.0.1 ⇝ 12.0.4

  • there is no spoon free LTS by Oracle!

⇝ More in my weekly:
No Free Java LTS Version?

Breaking News!

Oracle released a
Java Client Roadmap Update
with plans for:

  • Applets

  • Web Start

  • JavaFX

  • Swing/AWT

Applets

  • Applets are deprecated in Java 9

  • Applets are removed from Java SE 11

  • Applets won’t be in Oracle’s OpenJDK 11 builds

Web Start

  • Web Start is deprecated in Java 9

  • Web Start is removed from Java SE 11

  • Web Start won’t be in Oracle’s OpenJDK 11 builds

JavaFX

  • was never part of Java SE
    (unlikely to change soon)

  • was never in Oracle’s OpenJDK builds
    (just as unlikely to change)

  • will be removed from Oracle JDK 11

If your project uses JavaFX,
you can’t rely on its presence
on your customers' machines!

JavaFX

Quote:

Oracle is working with interested third parties to make it easier to build and maintain JavaFX as a separately distributable open-source module.

Not a quote:

Oracle wants to reduce/terminate investment in JavaFX.

Swing/AWT

Quote:

Oracle will continue developing Swing and AWT in Java SE 8 and Java SE 11 (18.9 LTS). This means they will be supported by Oracle through at least 2026.

What this doesn’t say:

  • support is free

  • support goes beyond Java 11

Swing/AWT

Hypothetically Oracle could
remove Swing/AWT from Java SE 12
and its statement still holds.

More Breaking News…​

To hear about such news:

Public Service Announcement

  • who knows the JPMS basics?

  • there’s much to talk about
    ⇝ this can only cover parts of the JPMS

  • slides at slides.codefx.org

Java Module System Basics

The very short version

Modules

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

advent calendar 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

b2e21fbf

Module Structure

advent calendar module multi
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) {
	// ...
}
advent requires transitive problem

⇝ 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;
	// ...
}
advent requires transitive solution

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

advent requires static

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

uber lib requires static

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?

advent 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;
}

(A and B need access to some.Service)

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 surprise;
	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

advent 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

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.

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:

jdk/bin/calendar

More Options

  • --bind-services: link in all service providers

  • --limit-modules: limit universe of observable mods

  • --no-header-files: exclude include header files

  • --no-man-pages: exclude man pages

  • --strip-debug: strip debug information

Summary

You can use jlink to:

  • create a runtime image
    with just the right classes

  • create a runtime image
    including your code

This should make certain kinds of deploys
smaller and easier.

About Nicolai Parlog

37% off with
code fccparlog

tiny.cc/jms

Follow

💻 codefx.org
▶ youtube.com/c/codefx
🐦 @nipafx

Want More?

⇜ Get my book!

You can hire me:

  • training (Java 8/9, JUnit 5)

  • consulting (Java 8/9)

Image Credits

Introduction

Project Jigsaw

Java Module System

Incremental Modularization

Migration Challenges

Rest