Standard Modules

The standard modules are managed by the Java Community Process (JCP) . The names of the standard Java SE modules start with java.*. These names are explicit enough, so it’s quite easy to imagine what the role of the module is. For example, the module named java.rmi defines the Remote Method Invocation API, and the module named java.logging defines the Java Logging API. A standard module can consist of standard API packages as well as non-standard API packages. It can also depend upon one or more non-standard modules.

Non-standard Modules

The non-standard modules are specific to JDK. Their names start with jdk.*. Non-standard modules contain packages and specific JDK code, which may be distinct between various implementations of the Java Development Kit. Some JDK modules, such as tools or service providers, don’t export anything, which means they’re not visible outside the module.

Two things are very import to remember: first, that standard API packages must not be exported by non-standard modules, so their visibility remains hidden from outside. Second, and certainly the most important thing to keep in mind, is that the source code that depends only upon Java SE modules will depend only upon standard Java SE types. This is a great advantage because the code becomes portable to all the existing implementations of the Java SE platform, as stated in the official description of the JEP 200 under http://openjdk.java.net .

Turning a JDK-specific API into a Java standard API is possible, but special focus is required regarding compatibility. When considering doing this, you should take into account whether it’s feasible and necessary by looking at the way it’s used. For example, the reason why the Java Debug Interface wasn’t turned into a standard API is because it’s used only by tools and debuggers, so it definitely doesn’t make sense to enhance it to be part of the Java Standard API .

Every platform module contains a folder called classes inside a folder called share. The classes folder contains all the classes that compose the module, along with the module descriptor in a file called module-info.java. Some modules, such as the java.base module, have native code for different operating systems like Windows, Linux, macOS , and so on.

Read the Description of a Module

To get the entire description of a module , we can use the --describe-module command-line option of the Java launcher, followed by the module name:

$ java --describe-module <module_name>

By running the --describe-module option on module java.naming, we get the following output:

java.naming@9
exports javax.naming
exports javax.naming.directory
exports javax.naming.event
exports javax.naming.ldap
exports javax.naming.spi
requires java.base mandated
requires java.security.sasl
uses javax.naming.spi.InitialContextFactory
uses javax.naming.ldap.StartTlsResponse
provides java.security.Provider with sun.security.provider.certpath.ldap.JdkLDAP
qualified exports com.sun.jndi.toolkit.ctx to jdk.naming.dns
qualified exports com.sun.jndi.toolkit.url to jdk.naming.dns jdk.naming.rmi
contains com.sun.jndi.ldap
contains com.sun.jndi.ldap.ext
contains com.sun.jndi.ldap.pool
contains com.sun.jndi.ldap.sasl                                                          
contains com.sun.jndi.toolkit.dir
contains com.sun.jndi.url.ldap
contains com.sun.jndi.url.ldaps
contains com.sun.naming.internal
contains sun.security.provider.certpath.ldap

The preceding code displays the entire information contained in the module-info.java file of the java.naming module. It additionally contains the contains clauses, which aren’t displayed in the module-info.java file:

• The exports statements denote that module java.naming make the packages javax.naming, javax.naming.directory, javax.naming.event, javax.naming.ldap, and javax.naming.spi available to any other module that depends on it (on module java.naming).

• The requires statements from the preceding code denote that module java.naming depends on module java.base and also on module java.security.sasl, meaning that the exported types in those two modules are used inside the java.naming module. For instance, the class LDAPCertStore from the java.naming module imports all the java.security subpackages that are part of module java.security.sasl.

• The uses statement takes as an argument a type name that represent a service type. In our case, module java.naming consumes instances of InitialContextFactory and StartTlsResponse.

• The provides statement specifies that the module provides the implementation of java.security.Provider (from module java.base) with sun.security.provider.certpath.ldap.JdkLDAP.

• The statement qualified exports com.sun.jndi.toolkit.url to jdk.naming.rmi means that package com.sun.jndi.toolkit.url from the java.naming module should be accessible only in the module jdk.naming.rmi. If we take a look in the jdk.naming.rmi module, we find there a class called rmiUrlContext that imports the class com.sun.jndi.toolkit.url.GenericURLContext from module java.naming. This is why module java.naming needs to specify that it exports the package to module jdk.naming.rmi.

• The contains clauses list all the packages from the module that aren’t part of the standard API.

Chapter 4 explains in detail what the exports, requires, uses, and provides clauses mean and how they can be used.

Module java.base

With more than 5,600 classes and a size of more than 43 MB, java.base is one of the largest modules of the Java Platform Module System. Every module depends on java.base by default, as the java.base module is located at the bottom of the module graph, representing the core of the system.

The module java.base contains the core APIs and encapsulates the Java runtime. It’s not mandatory for a module to explicitly declare that it depends on module java.base because it depends on it automatically. Writing requires java.base is allowed, but it’s not necessary because the compiler inserts it anyway by default.

The module java.base contains the following packages:

• java.io

• java.lang.*

• java.math

• java.net.*

• java.nio.*

• java.security.*

• java.text.*

• java.time.*

• java.util.*

• javax.crypto.*

• javax.net.*

• javax.security .*

The module java.base represents the root of the module system because it contains classes like java.lang.Object, java.lang.Class, java.lang.String, java.lang.System, and reflection classes like java.lang.reflect.Constructor and java.lang.reflect.Method.

All the Java platform packages are exported by the java.base module, meaning they’re accessible to any other modules :

// module-info.java (module java.base)
module java.base {
        exports java.io;
        exports java.lang;
        exports java.lang.module;
        ...
        ...
        exports java.text;
        exports java.time;
        exports java.util;
        exports javax.net;
}

The module java.base, called the base module of the system, depends upon no other module. We say that it has no dependencies upon other modules, meaning that its module-info.java file contains no requires clauses. Module java.base also contains the new java.lang.module package introduced in JDK 9, which is part of the new module API. Chapter 9 covers the java.lang.module package. It’s also important to remember that java.base is not an aggregator module.

There will be situations when java.base will be the only module you need in order to compile and run a simple Java application. If all the types you need are in packages contained in the java.base module, then java.base is all you need. Due to the fact that java.base has no dependencies on other modules, there aren’t any other modules that have to be utilized together with java.base. This is a great advantage because before JDK 9 we had to take the entire JDK since even a simple class like java.lang.Object previously had to be used with a large number of classes. A module also contains a new file called module-info.java, which represents the module descriptor, which Chapter 4 describes in detail.

In addition, java.base contains lots of JDK internal packages like jdk.internal.util, sun.io, sun.text, sun.util, com.sun.crypto.provider, com.sun.net.ssl, and more.

We’ve seen how the JDK was modularized and what the module graph looks like. In the next section, you’ll learn about the modularization of the source code .

New Scheme for the Source Code

Figure 3-2 illustrates the new scheme of the source code in the JDK.

Figure 3-2. New scheme of JDK 9 source code

The src directory of the JDK contains a list of directories that represent modules names. Each module has its own directory. The directories’ modules names start with java.* or jdk.* and represent the names of the modules.

Every module directory contains a share directory, which consists of cross-platform source code. Additionally, a module directory can also contain other directories related to operating systems, like aix, linux, macosx, solaris, unix, and windows. These directories contain source code pertaining to a single operating system only. Not all the modules contain all the operating-system directories just listed. There are modules that contain operating-system-specific source code for all the operating systems (like java.base or java.desktop) or only for a part of them. For instance, the module java.prefs consists only of three operating-system directories: macosx, unix, and windows—meaning that this module doesn’t have any source code specific to Linux or Solaris inside it.

The next level of directories inside a module contains directories with names like classes, conf, lib, native, and doc. Except for the conf directories, the other four directories can also be found in JDK 8 under the share directory.

The classes directories in JDK 9 consist of Java source files grouped into directories that designate the structure of their packages. We want to point out two main differences to JDK 8: first, in JDK 9 there’s a classes directory for each of the existing modules . Even the aggregator modules have a classes directory. Second, in JDK 9 a module-info.java file is placed in the root of the classes directory. The module-info.java file represents the module descriptor and was introduced in Java 9. Each module has a module-info.java file inside its classes directory. The classes directory can contain java, javax, jdk, sun, com, or org directories, depending on the packages contained in it.

The conf directory includes configuration files, which may be properties files, security policy files, policy files, and so on. This is a new directory that didn’t exist in JDK 8.

The lib directory is present only in java.base and consists of the file default.policy in the directories share, solaris, and windows.

The native directory holds C and C++ source files, native classes, and procedures. It can contain some of the following directories: include, launcher, common, libfdlibm, libjava, libjimage, libjli, libnet, libnio, libverify, libzip, and more. According to Open JDK, the names of the directories correspond “to the names of the shared libraries into which the compiled code will be linked.” The include folder represents an exception to this rule because it has C/C++ header files in it.

Table 3-3 shows where some of the most important classes in Java are now located.

The next subsection describes the new structure of the source code in JDK 9.

Comparison Source Code Structure

Here’s a short comparison between the structure of the source code in JDK 8 and JDK 9. In JDK 8, the structure of the source code looks like this:

jdk / src / share / {back; bin; classes; demo; doc; instrument; javavm; lib; native; npt; sample; transport}

In JDK 9, the structure of the source looks like this:

jdk / src / <module_name> / share / {classes; conf; lib; native; doc}

As you can see, an intermediary directory containing the module name was added between the directories src and share. Another important difference between JDK 8 and 9 is that in JDK 9 for each classes directory of each module there’s a module-info.java file at the root level. In JDK 9, under the classes directory and its subdirectories are only the packages and the classes that belong to the corresponding module. In JDK 8, the classes directory and its subdirectories contain all the packages and classes that comprise the Java platform.

Build Process Adjustments

Not only the source code, but the build itself was organized around modules. There are a new proposed layout and new build targets. The output emitted during the build is different in Java 9 compared to previous versions. The build was changed so that it builds everything as modules. Besides that, the make files have been split into module specific files.

Table 3-4 shows the new structure of the build system in JDK 9 compared to the one that existed in JDK 8.

Table 3-5 shows a list of target commands together with their descriptions that are used to build the JDK 9 . These are described in the official JDK 9 API specification.

The prospect of compiling only one module at a time is one of the most important changes to the build system. A module can be compiled together with its dependencies, and the compiled classes are divided into modules. During the build process, the modules that are independent can be compiled at the same time. If module boundaries are violated, the build process won’t succeed.

The first module to be compiled is the java.base module because it’s required by all other modules. The module graph is traversed in a reversed order (starting from bottom to top) during the compilation. This makes sense because by compiling the modules successively from java.base up to the top of the module graph, we avoid the situation of compiling a module that has a dependency on a module that has not been compiled.

The JCP team performed significant modifications to the build system in order for modules to be built independently. For instance , a change performed in the java.logging module won’t determine a new build of the java.base module. This is a great achievement because it boosts productivity.