Getting started with Java 9 modules

Getting started with
Java 9 modules

src/main/java
api/Foo.java
internal/Qux.java
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>example</groupId>
<artifactId>foo</artifactId>
<version>1</version>
</project>
<project>
<artifactId>bar</artifactId>
</project>
src/main/java
api/Bar.java
internal/Baz.java
pom.xml pom.xml
<project>
<dependencies>
<dependency>
</dependency>
</dependencies>
</project>

example.foo
api/Foo.java
internal/Qux.java
example.bar
api/Bar.java
internal/Baz.java
module-info.java module-info.java
module example.foo {} module example.bar {
requires example.foo;
}
module example.foo {
exports api;
}

Scope
Task module descriptor
module descriptor
deployment descriptor
build execution descriptor
API for custom tasks
runtime
compile-time
build-time
Type declarative declarative/programmatic
Unit Java package (sub-)project

api/Foo.class internal/Qux.class api/Bar.class internal/Baz.class
(system) class path
Modularity prior to Java 9 is emulated by class loader hierarchies. By tweaking class
loaders to define multiple parents, it is also possible to run several versions of the
same module (e.g. OSGi).

module loader
example.foo
example.bar
“example.bar reads example.foo”
The integrity of the module graph is verified by the Java 9 runtime. Jars without a
module-info.class are typically contained by the unnamed module that reads all modules.

module example.qux {
exports example.bar;
}
exports api;
}
<project>
<artifactId>qux</artifactId>
</project>
<project>
</project>
<project>
</project>
module example.bar {
}
requires transitive
example.foo;
}
Imports are non-transitive by default (what is a good default for a runtime module system).

requires java.xml;
}
module java.base {
exports java.lang;
exports java.io;
exports java.util;
// ...
}
module java.xml {
exports org.xml.sax;
// ...
}
exports api;
// ...
}

requires java.xml;
}
<project>
</project>
module java.base {
exports java.lang;
exports java.io;
exports java.util;
// ...
}
module java.xml {
// ...
}
Modules can use non-modularized code as automatic modules (referenced by jar name).
Automatic modules export every package and import any module.
Automatic modules should only be used locally to avoid depending on a name.
example-foo-1.jar

module java.base {
exports java.lang;
exports java.io;
exports java.util;
// ...
}
module java.xml {
// ...
}
exports api;
// ...
}
<project>
</project>
Non-modularized code can still run on the class path within the unnamed module.
The unnamed module imports any module but does not export any packages.

module java.base {
exports java.lang;
exports java.io;
exports java.util;
// ...
}
<project>
</project>
import sun.misc.BASE64Encoder
java
--add-exports
java.base/sun.misc=ALL-UNNAMED
Module::addExport
Module::addRead
Instrumentation::redefineModule;

module java.base {
exports java.lang;
exports java.io;
exports java.util;
// ...
}
<project>
</project>
import sun.misc.Unsafe
module jdk.unsupported {
exports sun.misc;
// ...
}

module java.base {
exports java.lang;
exports java.io;
exports java.util;
// ...
}
import sun.misc.Unsafe
exports sun.misc;
// ...
}
requires jdk.unsupported;
}
Despite its name, the jdk.unsupported module is also contained in regular JVMs.

module sample.app {
requires foo.bar.qux;
requires some.lib;
}
java -p foo-bar-1.0.jar Main
java -p foo-bar-qux.jar Main
name version
module sample.app {
requires foo.bar.qux;
}
module some.lib {
requires foo.bar;
}
Automatic module names are instable because of:
1. The inpredictability of a jar's file name
2. The inpredictability of a dependencys future module name
Module names should follow the reverse DNS convention known from package names.
Ideally, a module name should be equal to the module's root package.
Avoid an impedance mismatch between module names and (Maven) artifact ids.
Automatic module names and module naming convention.
throws ResolutionException
Module-Name: foo.bar.qux

class foo.Bar class pkg.Main
Loading a class from the class path.
java
–cp first.jar:second.jar:third.jar
pkg.Main
Class<?> load(String className) {
for (JarFile jarFile : getClassPath()) {
if (jarFile.contains(className)) {
return jarFile.load(className);
}
}
throw new ClassNotFoundException(className);
}
class foo.Bar
Packages can be split among jars unless they are sealed. Yet, sealing is vulnerable.
search
order

Loading a class from the module path.
Map<String, Module> packageToModule;
Class<?> load(String className) {
Module module = packageToModule.get(pkgName(className));
if (module != null && module.contains(className)) {
return module.load(className);
}
throw new ClassNotFoundException(className);
}
example.foo example.bar
Module-Package-ownership: split packages or concealed packages are no longer permitted.
java
–p first.jar:second.jar:third.jar
–m example.foo/pkg.Main

module java.base
module java.scripting
module java.logging module java.instrument
module java.xml
module java.sql
module java.compiler
module java.datatransfer
module java.sql.rowset
module java.naming
module java.management
module java.rmi
module java.management.rmi
module java.prefs
module java.activation
module java.desktop
module java.corba
module java.transaction
module java.security.jgss
module java.security.sasl
module java.xml.crypto
module java.xml.bindmodule java.xml.ws
module java.xml.ws.annotation

package library;
class Api {
@Deprecated
String foo() {
return "foo";
}
String bar() {
return "bar";
}
}
package library;
class Api {
String foo() {
return "foo";
}
}
Dealing with "jar hell"
package library;
class Api {
String bar() {
return "bar";
}
}
library-1.0.jar library-2.0.jar
Api api = new Api();
api.foo();
second-library-1.0.jar
Api api = new Api();
api.bar();
third-library-1.0.jar
throws NoSuchMethodError

package library;
class Api {
String foo() {
return "foo";
}
}
package library;
class Api2 {
String bar() {
return "bar";
}
}
library-1.0.jar library-2.0.jar
Class<?> entryPoint = ModuleLayer.empty()
.defineModules(
Configuration.resolve(ModuleFinder.of(modsDir),
Collections.emptyList(),
ModuleFinder.of(), // no late resolved modules
Collections.singleton("my.module")),
name -> makeClassLoader(name)
).layer().findLoader("my.module").loadClass("my.Main");
With little tweaking, the JPMS is however already capable of isolating packages:

Jars, modular jars and jmods.
javac
-d target
src/module-info.java src/pkg/Main.java
jar
--create
--file lib/example.foo.jar
--main-class=com.greetings.Main
-C target
.
jmod
create
--class-path target
--main-class=com.greetings.Main
lib/example.foo.jmod
JMOD
A jar file containing a module-info.class is considered a modular jar.
Both the jar and the jmod tool support a --module-version parameter.
Versions are however not currently a part of JPMS, “jar hell” is therefore not averted.

Linking modules prior to execution.
jlink
–-module-path ${JAVA_HOME}/jmods:mods
--add-modules example.foo
--launcher run=example.foo/pkg.Main
--output myapp
/myapp
/bin
java
run
/conf
/include
/legal
/lib
release./myapp/bin/run
Hello world!
du –hs myapp
44M myapp
./myapp/bin/java --list-modules
example.foo
java.base@9
Jlink (as of today) can only process jmods and modular jars.

package api;
public class SomeClass {
public void foo() {
/* do something */
}
private void bar() {
/* do something */
}
}
Method foo = SomeClass.class.getMethod("foo");
foo.invoke(new SomeClass());
Method bar = SomeClass.class.getDeclaredMethod("bar");
bar.setAccessible(true); // check against security manager
bar.invoke(new SomeClass());
Reflection and breaking encapsulation
opens api;
}
open module example.foo { }
JVM modules do not open any of their packages (unless specified on the command line)!
java --add-opens
java --illegal-access=<permit,deny>
Module::addOpens
Instrumentation::redefineModule

module my.app {
requires spring;
requires hibernate;
}
module spring {
// ...
}
module hibernate {
// ...
}
open module my.app {
requires spring;
requires hibernate;
}
module my.app {
requires spring;
requires hibernate;
opens beans;
opens dtos;
} package beans;
interface MyBean {
void foo();
}
package internal;
class MyBeanImpl
implements MyBean {
@Override
public void foo() {
/* ... */
}
}
Object foo = ...
foo.getClass()
.getMethod("qux")
.invoke(foo);

module java.base {
exports java.lang;
// ...
}
module my.library { }
Field value = String.class.getDeclaredField("value");
value.setAccessible(true); // java.lang is not 'open'
Reflection against closed APIs is not discovered by the jdeps tool.
An existing class-path application that compiles and
runs on Java SE 8 will, thus, compile and run in
exactly the same way on Java SE 9, so long as it only
uses standard, non-deprecated Java SE APIs.
An existing class-path application that compiles and
runs on Java SE 8 will, thus, compile and run in
exactly the same way on Java SE 9, so long as it only
uses standard, non-deprecated Java SE APIs,
excluding the use of reflection on non-public members.
JPMS
group

package java.lang;
public class ClassLoader {
protected Class<?> defineClass(String name, byte[] b,
int off, int len) {
/* define class and return */
}
}
public class MyBean
{
public void foo() { }
void bar() { }
}
public class ProxyBean extends MyBean
{
@Override public void foo() { }
@Override void bar() { }
}
MyBean mock = Mockito.mock(MyBean.class);
MyBean persisted = entityManager.merge(myBean);
MyBean bean = applicationContext.getBean(MyBean.class);
ClassLoader proxyLoader = new ProxyClassLoader(parent);
Class<?> proxy = proxyLoader.loadClass("ProxyBean");
MethodHandles.Lookup lookup = MethodHandles.lookup();
lookup.defineClass(classFile);
MethodHandle bar = lookup.findVirtual(MyBean.class,
"bar",
MethodType.methodType(void.class);
bar.invoke(new MyBean());
MyBean mock = Mockito.mock(
MyBean.class, MethodHandles.lookup());

module my.library {
requires jdk.unsupported;
}
exports sun.misc;
opens sun.misc;
// ...
}
module java.base {
exports java.lang;
// ...
}
Field theUnsafe = Unsafe.class.getDeclaredField("theUnsafe");
theUnsafe.setAccessible(true);
Unsafe unsafe = (Unsafe) theUnsafe.get(null);
unsafe.defineClass( ... );
package java.lang;
public class Accessor {
public void access() {
// within module
}
}
module my.library { }
Field value = String.class.getDeclaredField("value");
value.setAccessible(true); // java.lang is not 'open'

module example.service {
requires example.spi;
provides pkg.MyService
with impl.MyServiceImpl;
}
module example.spi {
exports pkg.MyService;
}
module example.app {
requires example.spi;
uses pkg.MyService;
}
interface MyService {
String hello();
}
class MyServiceImpl
implements MyService {
String hello() {
return "foo";
}
}
MyService service =
ServiceLoader.load(
MyService.class);
LOL
Compatible with non-modularized META-INF/services entries.

public class SomeHttpClient {
void call(String url) {
try {
Class.forName("org.apache.http.client.HttpClient");
ApacheDispatcher.doCall(HttpClients.createDefault());
} catch (ClassNotFoundException ignored) {
JVMDispatcher.doCall(new URL(url).openConnection());
}
}
}
module library.http {
requires static
httpclient;
}
<dependencies>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
<version>2.0</version>
<optional>true</optional>
</dependency>
</dependencies>
Could be substituted by using a service loader and modules that implement the binding.

module my.app {
requires spring;
opens beans;
}
module my.app {
requires spring;
requires careless.lib;
opens beans to spring;
}
module my.app {
requires spring;
requires careless.lib;
opens beans;
}
module spring {
// ...
}
module careless.lib {
// has vulnerability
}
class Util {
void doCall(String httpVal)
throws Exception {
Class.forName(httpVal)
.getMethod("apply")
.invoke(null);
}
}
It is also possible to qualify exports statements for the creation of friend modules.
This can be useful for priviledged modules within the same module family.

module my.app {
requires web.framework;
opens app;
}
URL ressource = getClass().getResource("/foo/bar.txt");
Resources are only visible to other modules if:
1. They reside in an exported package
2. Belong to the module conducting the lookup
3. Reside in a folder that is not a legal package-name (e.g. META-INF)
4. End with .class
/app/MyWebPage.java
/app/MyWebPage.html
abstract class BaseWebPage {
URL findTemplate() {
String name = getClass()
.getSimpleName() + ".html";
return getClass()
.getResource(name);
}
}
module web.framework {
// ...
}
module my.app {
requires web.framework;
}
class MyWebPage
extends BaseWebPage {
/* ... */
}

Alternative Java module systems: OSGi and JBoss modules
abstract class ClassLoader {
final ClassLoader parent;
Class<?> findClass(String name) {
/* 1. Call parent.findClass
2. Call this.loadClass */
}
Class<?> loadClass(String name) { /* ... */ }
}
class MyModuleClassLoader extends ClassLoader {
final Set<String> selfOwned;
final Map<String, ClassLoader> visible;
@Override Class<?> findClass(String name) {
String pkg = packageOf(name);
if (selfOwned.contains(pkg)) {
return loadClass(name);
}
ClassLoader delegate = visible.get(pkg);
if (delegate != null) {
return delegate.findClass(name);
} else {
throw new ClassNotFoundException();
}
}
@Override Class<?> loadClass(String name) { /* ... */ }
}
Bundle-Name: sampleapp
Bundle-SymbolicName: my.app
Bundle-Version: 1.0
Bundle-Activator: my.Main
Import-Package: some.lib;version="1.0"
Export-Package: my.pkg;version="1.0"
@BundleName("sampleapp")
@BundleActivator(Main.class)
module my.app {
requires osgi.api;
requires some.lib;
exports my.pkg;
}

class Foo {
String bar() { return "bar"; }
}
assertThat(new Foo().bar(), is("Hello World!"));
public static void premain(String arguments,
Instrumentation instrumentation) {
new AgentBuilder.Default()
.type(named("Foo"))
.transform((builder, type, loader, module) ->
builder.method(named("bar"))
.intercept(value("Hello World!"));
)
.installOn(instrumentation);
}
Java agents with Byte Buddy

class Foo {
String bar() {
long start = System.currentTimeMillis();
try {
return somethingComplex();
} finally {
AgentApi.report("Foo", "bar",
System.currentTimeMillis() - start);
}
}
}
class Foo {
String bar(InternalState state) {
long start = System.currentTimeMillis();
try {
} finally {
AgentApi.report("Foo", "bar", state,
System.currentTimeMillis() - start);
}
}
}
class Foo {
String bar() {
}
}
module some.app { }
Java agents are capable of breaking module boundaries:
interface Instrumentation {
void redefineModule(Module module,
Set<Module> extraReads,
Map<String, Set<Module>> extraExports,
Map<String, Set<Module>> extraOpens,
Set<Class<?>> extraUses,
Map<Class<?>, List<Class<?>>> extraProvides);
}
module some.app { exports internal.state; }

static void agentmain(String arg,
Instrumentation inst) {
/* ... */
}
processIdstart()
static void agentmain(String arg,
Instrumentation inst) {
/* ... */
}
String processId = ...
com.sun.tools.attach.VirtualMachine
.attach(processId)
.loadAgent(jarFile, argument);
class Foo {
void bar() {
/* ... */
}
}
class Foo$Mock extends Foo {
@Override void bar() {
Mockito.doMock();
}
}
class Foo {
void bar() {
if (Mockito.isMock(this)) {
Mockito.doMock();
return;
}
/* ... */
}
}
String processId = ...
com.sun.tools.attach.VirtualMachine
.attach(processId)
.loadAgent(jarFile, argument);
processId
processId
new ProcessBuilder(
"java attach.Helper <processId>"
).start();
-Djdk.attach.allowAttachSelf=false

Java platform module system: the controversy
Are modules even (still/even) useful?
Considering microservices, modules are often the better option, both considering
maintainability and performance. We have always used modules with Maven; adding
first-level support offers a chance to better interact with them at runtime.
Think of what we could have instead of Jigsaw in the time it took!
Remember the last time you had to defend a refactoring/maintenance release?
You should always clean up before you expand your feature set.
Java modules breaks all the things!
The "growth only" model is not sustainable if Java should have a future. The JVM
must at some point apply breaking changes to survive/strive.
To make full use of Java, some code needs to cross module boundaries!
Nobody relies on internal APIs for laziness but because it is necessary. Without the
openness of sun.misc.Unsafe in the past, a lot of libraries that make the JVM such
an attractive choice would not exist today. The standard library only offers basic
functionality by design. Especially test libraries and tooling have a legitimate wish
to "cross the line". As of today, any code can however still use Unsafe to leverage
low-level functionality. The standard library still relies heavily on qualified exports!

http://rafael.codes
@rafaelcodes
http://documents4j.com
https://github.com/documents4j/documents4j
http://bytebuddy.net
https://github.com/raphw/byte-buddy

Getting started with Java 9 modules

More Related Content

What's hot (20)

Similar to Getting started with Java 9 modules (20)

More from Rafael Winterhalter (9)

Recently uploaded (20)

Getting started with Java 9 modules