JMOD Files

According to the JDK 9 documentation, “for the purpose of modularizing the JDK, a new artifact format called JMOD goes beyond JAR files to accommodate native code, configuration files, and other kinds of data that do not fit naturally, if at all, into JAR files.”

A JMOD file is a new module artifact that consists of a compiled module definition in the form of a ZIP file. It enhances a JAR file by also including native code and configuration files. JMOD is a new format used for packaging the modules. This new format isn’t executable.

A JMOD file is an alternative to the modular JAR file covered in Chapter 4. It’s mostly used when a module also contains native code . JMOD files are used to package the modules of the JDK, but they can be used only at compile-time and link-time. They can’t be used at runtime. The JMOD files are also used by the Jlink tool to create a modular runtime image. The directory consisting of the JMOD files represents the module path used by the linker.

jmod create <options> <jmod-file>

jmod list <jmod-file>

jmod describe <jmod-file>

Multi-release JAR files

Suppose you want to switch to the latest JDK version but have a third-party library that’s incompatible with the latest version of the JDK. As a consequence, you decide not to switch to the latest JDK version at least until the third-party library you’re using will be made compatible with the latest version of the JDK. This is a bad scenario that was solved in Java 9 by the introduction of multi-release JAR files, which allow packaging code for different versions of the JDK in a single JAR file.

Multi-release JAR files were implemented in JDK 9 in JEP 238. This JEP isn’t part of Jigsaw. We mention it here because it’s an important feature that helps during migration to Java 9. It doesn’t depend on the Java Platform Module System at all. We can use multi-release JAR files in a non-modular world, too.

Java 9 enhances the JAR file format so that multiple major versions of a class can be stored inside a single JAR file, in its META-INF directory. The new JAR file format is called a multi-release JAR and can consist of a single library for different JDK versions. The correct versions of the classes are loaded at runtime depending on the JDK version used by the user. A multi-release JAR file changes the structure of a JAR file only to a low degree.

Listing 10-1 shows a multi-release JAR file that contains versioning metadata for JDK 8 and JDK 9.

Listing 10-1. Multi-release JAR file Having Versioning Metadata for JDK 8 and JDK 9

Root of JAR
        -   A1.class
        -   B1.class
        -   C1.class
        -   D1.class
        -   E1.class
-META-INF
        - MANIFEST.MF
        - versions
                - 8
                        - A1.class
                        - B1.class
                        - F1.class
                - 9
                        - A1.class
                        - C1.class
                        - D1.class
                        - F1.class
                        - G1.class

In this example, we have Java .class files in the root directory of the JAR, but also in the 8 and 9 directories. In the META-INF directory , we have the MANIFEST.MF file and a directory called versions, which contains two directories: a directory called 8 that represents the resources provided for JDK 8 and a directory called 9 that represents the resources provided for JDK 9. There are Java .class files in the 8 directory and in the 9 directory. The classes inside the 8 directory will be considered when we use JDK 8, and the classes inside the 9 directory will be considered when we use JDK 9.

The classes in the root directory of the JAR file will be considered in the following situations:

• If we’re using a version of JDK different from JDK 8 or JDK 9

• If we’re using JDK 8 or JDK 9 and the corresponding classes aren’t present in the versions/8 and versions/9 directories

We’ll explain this in detail. For the multi-release JAR file just discussed, we first have to know whether the JDK version we’re using supports multi-release JAR files. If it doesn’t, then everything inside the versions/8 and versions/9 directories will be ignored, and only the class files from the root directory will be considered: A1.class, B1.class, C1.class, D1.class, and E1.class.

When we use a JDK version different from JDK 8 or JDK 9, only the class files from the root directory will be used. In our example, the classes F1 and G1, present only in the versions/9 directory, won’t be used at all.

When we use JDK 8, the following classes will be used:

A1.class (from the versions/8 directory)
B1.class (from the versions/8 directory)
C1.class (from the root directory)
D1.class (from the root directory)
E1.class (from the root directory)
F1.class (from the versions/8 directory)

Instead, when we use JDK 9, the following classes will be used:

A1.class (from the versions/9 directory)
B1.class (from the root directory)
C1.class (from the versions/9 directory)
D1.class (from the versions/9 directory)
E1.class (from the root directory)
F1.class (from the versions/9 directory)
G1.class (from the versions/9 directory)

As you can see from this example, the classes inside a specific 8 or 9 directory, if present, override the classes from the root directory. But this happens only if we’re using JDK 8 or JDK 9, respectively.

A module-info.class file can also be added inside the versions directory of a multi-release JAR file. This feature is supported by the jar tool. But a module-info.class can’t be placed in the root directory.

A multi-release JAR file has an attribute called Multi-Release set to true, declared in its MANIFEST.MF:

Multi-Release: true

This attribute distinguishes a multi-release JAR from a non-multi-release one. If the attribute is set to false or is missing, we have a normal JAR.

A multi-release JAR file retains the structure of a JAR file. What a multi-release JAR adds is a directory called versions, under the META-INF directory. This directory can contain subdirectories for specific major JDK versions: 6, 7, 8, 9, and so on. Inside these subdirectories we can put the .class files specific to that JDK version.

What happens if a version of the JDK doesn’t support multi-release JARs? In this case, only the classes and resources present in the root of the JAR files are visible. Everything inside the versions directory will be invisible and implicitly not be taken into account.

Next, we’ll explain how to build a multi-release JAR file.

jar --create --file --release <version_number> <options>

jar --create --file myMultiReleaseJar.jar -C classesDirectoryJDK8 --release 9 -C classesDirectoryJDK9 .

jar --update --file myMultiReleaseJAR.jar --release 10 -C classesDirectoryJDK10 .

Class Loading Mechanism in JDK 9

This section covers the class loading mechanism in JDK 9. As you know, the role of a class loader is to load a class. The JCP team didn’t change the class loading process in JDK 9. The Classloader API hasn’t been modified in JDK 9. The same class loaders from JDK 8 are present in JDK 9: the bootstrap class loader, the platform class loader, and the application class loader.

The class loading process in JDK 9 is the same as in the previous versions of the JDK: first, the request to load a type is delegated to the parent class loader. The parent class loader delegates further to its parent class loader. This process traverses the application class loader and platform class loader and stops at the bootstrap class loader. If the bootstrap class loader can’t load the type, the class loader that started the delegation process will load the type.

By examining the structural layers that compose the JDK 9, we can observe that the Java Platform Module System (JPMS) is located on top of the JVM, under the class loading architecture. Right at the bottom we have the Java Virtual Machine (JVM). Above that we have the JPMS, and above the JPMS we have the three types of class loaders mentioned earlier. This architecture is illustrated clearly in Figure 10-1.

Figure 10-1. Overview over the structure of JDK 9

The bootstrap class loader is used to define the classes from most of the modules, like java.base, java.sql, or java.logging. The platform class loader is used to define the classes from only a few modules, like java.corba or java.transaction. Both bootstrap and platform class loader load types from platform modules, whereas the application class loader loads types from the module path. The application class loader is used to define the classes from jdk.compiler, junit, guava, slf4j, and so on. In JDK 9, the application and platform class loaders aren’t instances of the class java.net.URLClassLoader anymore.

Jigsaw allows loading modules using our own class loaders. This can be done using the method defineModules() from the Module class, but this feature is pretty advanced, so not many developers will ever use it.

Jigsaw also introduced support for class loader names. Class loaders can have optional names. If the name isn’t specified when a class loader is created, it will have no name. The name of the class loader is retrieved by the getName() method of the Classloader class. The name of the module’s class loader is always mentioned together with the module name and version in warning messages or stack traces.

Because a class loader can have a name attribute in JDK 9, a new constructor has been added for the Classloader class that creates a new class loader of the specified name by using the specified parent class loader for delegation:

protected ClassLoader(String name, Classloader parent)

Jigsaw also allows you to find a class by name in a specific module with the help of the new findClass() method, which gets as parameter the name of the module and the binary name of the class:

Class<?> findClass(String moduleName, String name)

This method returns the Class object or null if the class couldn’t be found. If we pass a name for the module, then the method will always return null. Otherwise, it will call the findClass(name) method by passing the name of the class. This method isn’t useful in a modular context unless we have our own class loader implementation that supports the loading from modules. Then we could overwrite this method.

The Extension class loader was renamed to platform class loader in JDK 9. The name of the built-in platform class loader is platform. The new static getPlatformClassLoader() method returns a platform class loader via which all the built-in Java SE and JDK types are visible. This method checks for permissions and can throw a SecurityException exception.

A class loader can load types from multiple modules if two conditions are simultaneously met:

• All types from every module are loaded by just one single class loader.

• Modules are independent and don’t conflict with each other.

To assure backwards compatibility, it’s possible to load types from the class path. Every class loader has a unique unnamed module that’s retrieved by the new method getUnnamedModule() located in the java.lang.Classloader class. If the class loader loads a type that isn’t defined in a named module, that type is in the unnamed module. The unnamed module from the application class loader loads types from the class path when these types are in packages that aren’t defined by any known module.

Layers

Suppose we want to add a couple of new modules at runtime into our application. We don’t know all the modules that we need straight at compile-time, so we need the possibility of adding new modules later at runtime. Fortunately, the Java Platform Module System provides a solution for this in the form of a new concept called layers . Layers group a set of modules and are used to add new modules at runtime into an application. The JDK 9 API specifies that a layer maps each module in the graph to the unique class responsible for loading the types defined in that module. Therefore, a layer is used to find a class loader in order to load classes for a graph of modules.

Not all applications make use of layers. The applications that use layers are those that implement a container architecture, where modules are dynamically added and linked at runtime. On top of the existing layer, a container application can create a new layer. It does that by resolving the initial module of the application against a whole set of observable modules, like non-platform modules from the lower layer, upgradeable platform modules that can have different versions, different service providers, and so on. Nevertheless, a container application might require a different version of a module already present in the runtime environment. This can be implemented in Jigsaw using the powerful features introduced by layers.

A layer is built at runtime from a graph of modules. Each layer has the following:

• A configuration, represented by an instance of the Configuration class located in package java.lang.module

• A function that maps each module to a class loader, represented by an instance of the ClassLoader class located in package java.lang

According to the JDK 9 API specification, a configuration “encapsulates the readability graph that is the output of the resolution. It is the result of resolution or resolution with service binding.” The following sections talk about configurations.

Layers can be built in a hierarchy similar to a stack. They can be created on top of the boot layer, and other layers can be created on top of the previously created layers, and so on. The Java Virtual Machine has the boot layer, which is the basic and the first layer used by the JPMS.

The ModuleLayer class from the package java.lang in the module java.base represents an instance of a layer. A ModuleLayer object is obtained by calling the getLayer() method on a Module. A module layer contains only named modules. Hence, if we call the getLayer() method on an unnamed module, a null is returned. Otherwise a ModuleLayer object is returned:

ModuleLayer moduleLayer = module.getLayer();

Next we’ll look at the boot layer, which is the most important layer.

ModuleLayer bootLayer = ModuleLayer.boot();
Set<Module> modulesSet = bootLayer.modules();

Optional<Module> myModule = bootLayer.findModule("com.apress.myModule");

InputStream inputStream = myModule.getResourceAsStream(resourceName);

Configuration configuration = ModuleLayer.boot().configuration()

Path ourDirectory = ...;
ModuleFinder finder = ModuleFinder.of(ourDirectory);
Configuration parentConfiguration = ModuleLayer.boot().configuration();
Configuration configuration = parentConfiguration.resolve(finder, ModuleFinder.of(), Set.of("com.apress.myModule");

ModuleLayer parentLayer = ModuleLayer.boot();
ClassLoader classLoader = ClassLoader.getSystemClassLoader();
ModuleLayer layer = parent.defineModulesWithOneLoader(configuration, classLoader)

ModuleLayer moduleLayer = ModuleLayer.boot();

    moduleLayer.modules().stream().forEach(module -> {
        String moduleName = module.getName();
        System.out.println("Name of the module is: " + moduleName);
    });

Name of the module is: jdk.javadoc
Name of the module is: jdk.deploy
Name of the module is: javafx.graphics
Name of the module is: java.security.jgss
Name of the module is: jdk.editpad
Name of the module is: java.compiler
Name of the module is: jdk.jdeps
Name of the module is: jdk.packager
Name of the module is: java.management.rmi
Name of the module is: javafx.swing
Name of the module is: jdk.attach
Name of the module is: java.desktop
Name of the module is: jdk.unsupported
Name of the module is: javafx.fxml
...

package modulelayer;

import java.lang.ModuleLayer;
import java.util.List;

public class LayerUtil {

    public static void describeCurrentAndParentLayers() {

        // prints the layer information for the current layer
        ModuleLayer thisModuleLayer = LayerUtil.class.getModule().getLayer();
        printLayerInformation(thisModuleLayer);

        // gets all the parents of the layer
        List<ModuleLayer> parentModuleLayerList = thisModuleLayer.parents();

        if(parentModuleLayerList.isEmpty()) {
            System.out.println("This layer has no parent layers");
        }
        else {
            for(ModuleLayer moduleLayer : parentModuleLayerList) {
                printLayerInformation(moduleLayer);
            }
        }
    }

    private static void printLayerInformation(ModuleLayer moduleLayer) {
        System.out.println("The name of the modules in this layer are: " + moduleLayer.toString());
        System.out.println("The configuration for this layer: " + moduleLayer.configuration());
    }

    public static void main(String[] args) {
        describeCurrentAndParentLayers();
    }
}

Upgradeable Modules

A module is upgradeable if it can be upgraded by deploying it on the upgrade module path. The JPMS performs a check at link-time and runtime to make sure that only the upgradeable modules are allowed to be upgraded.

From the Java SE modules, the only upgradeable modules are the ones from module java.se.ee. The upgradeable modules are java.activation, java.compiler, java.corba, java.transaction, java.xml.bind, java.xml.ws, java.xml.ws.annotation, and jdk.internal.vm.compiler. A couple of standard modules from JDK are upgradeable.

javac and java provide a command-line option called --upgrade-module-path that takes a list of directories. These directories contain modules that replace the existing modules in the runtime image. For example, to upgrade JAXB, we can execute the following command:

java --upgrade-module-path myDirectory --add-modules java.xml.bind

Here, myDirectory represents a directory that contains the modules that will replace the existing modules.

For upgrading a module in the runtime image, a module can be deployed on the upgrade module path. An automatic module can also be deployed on the upgrade module path. But an automatic module can’t be upgraded because an upgradeable module is linked into a runtime image, whereas an automatic module isn’t linked into a runtime image.

Features Coming in the Next Releases

Some features will be coming in the next releases of JDK. The JCP team announced that the next releases will resolve two issues that we have now and will also add two new features. The new features that will come in the next releases are the following:

• multi-module JAR files: Now a modular JAR file can contain only a single module. It’s not allowed to contain more than one module. In practice, we can have large JAR files that contain different pieces of functionality that don’t pass into a single module. So it would be better to have multiple modules in a single modular JAR file.

• Additional module-layer operations: The ModuleLayer.Controller API will be enhanced with new methods, like addUses() and addPackage().

The issues that will be solved in the next releases are the following:

• Concealed package conflicts: This issue was covered in Chapter 8. The problem is that two distinct modules can’t share the same name of a package. The proposal made by the JCP team is to avoid concealed package conflicts by doing a redesign so that modules that contain conflicting packages will be loaded in their own class loaders.

• Cyclic module relationships: This issue was also covered in Chapter 8. The proposal for the next JDK releases is to allow cyclic relationships among modules at runtime.

Summary

We started this chapter by looking at the new JMOD files together with the jmod tool. Then we talked about multi-release JAR files, which represent one single JAR file. Therefore, they’re only a unit of release and can be used, for example, for replacing JDK internal APIs. If we’re using a JDK internal API in Java 8, we can provide a new class with a replacement for it in JDK 9 and place both class files in a multi-release JAR file. Multi-release JAR files were introduced to be able to use a specific version of the JDK, even if some third-party libraries haven’t been yet upgraded to the last version. They help third-party libraries to use API features from newer releases of Java.

Further, we explained the new notion of layer in the context of the Java Platform Module System. I explained what layers are, why they’re useful, and how we can create our own layers. If an application uses layers, it will probably use only the boot layer. I covered the class loading mechanism in JDK 9 and explained how it fits together with the new module system. We learned that there is no relation between class loaders and modules enforced by Jigsaw.

The chapter concluded by talking about upgradeable modules and about some features that will come in the next JDK releases.

In Chapter 11, you’ll learn how to unit test modular applications.