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> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>bar</artifactId> <version>1</version> </project> src/main/java api/Bar.java internal/Baz.java pom.xml pom.xml <project> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>bar</artifactId> <version>1</version> <dependencies> <dependency> <groupId>example</groupId> <artifactId>foo</artifactId> <version>1</version> </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 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).

api/Foo.class internal/Qux.class api/Bar.class internal/Baz.class api/Foo.class internal/Qux.class api/Bar.class internal/Baz.class 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; } module example.foo { requires example.foo; exports api; } <project> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>qux</artifactId> <version>1</version> </project> <project> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>bar</artifactId> <version>1</version> </project> <project> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>foo</artifactId> <version>1</version> </project> module example.bar { requires example.foo; } module example.bar { requires transitive example.foo; } Imports are non-transitive by default (what is a good default for a runtime module system).

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

module example.bar { requires example.foo; requires java.xml; } <project> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>foo</artifactId> <version>1</version> </project> module java.base { exports java.lang; exports java.io; exports java.util; // ... } module java.xml { exports org.xml.sax; // ... } 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 org.xml.sax; // ... } module example.foo { exports api; // ... } <project> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>bar</artifactId> <version>1</version> </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> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>bar</artifactId> <version>1</version> </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> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>bar</artifactId> <version>1</version> </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 module jdk.unsupported { exports sun.misc; // ... } module example.bar { 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 module example.foo { 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; } module 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 { return somethingComplex(); } finally { AgentApi.report("Foo", "bar", state, System.currentTimeMillis() - start); } } } class Foo { String bar() { return somethingComplex(); } } 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

Similar to Getting started with Java 9 modules

More from Rafael Winterhalter

Recently uploaded

Getting started with Java 9 modules