Computing the Name of the Automatic Module

If the attribute Automatic-Module-Name isn’t set, the name of the automatic module is automatically derived from the name of the JAR file. If the attribute Automatic-Module-Name is set, but the JAR also contains a module-info.class file, then the information stored in the attribute Automatic-Module-Name is simply ignored. The name of the automatic module will be the same as the one defined inside the module-info.class file.

Next let’s talk about the filename-based algorithm used by Jigsaw for computing the name of the automatic module from the name of the JAR. Two strings are derived from the JAR file: the name of the automatic module and its version:

1. The .jar suffix is removed from the name of the JAR file. The resulting string is further used for determining and extracting the name and the version of the automatic module.

2. The module name is extracted. According to the JDK 9 API documentation, “if the name matches the regular expression -(\d+(\.|$)), then the module name will be derived from the subsequence preceding the hyphen of the first occurrence. The subsequence after the hyphen is parsed as a version and it is ignored if it can’t be parsed as a version.”

3. Some replacements on the name of the module are performed. The JDK 9 API documentation states that “all non-alphanumeric characters ([^A-Za-z0-9]) in the module name are replaced with a dot (‘.’), all repeating dots are replaced with one dot, and all leading and trailing dots are removed.”

Table 8-1 shows some examples of deriving the name and the version from a couple of JAR files. The first column represents the name of the JAR file, and the second and third columns represent the automatically extracted name of the module and version, respectively. The fourth column tells us if an error occurred or not.

The name and version of the guava-19.0.jar JAR file could be successfully derived. According to the filename-based algorithm , first the jar suffix is deleted. The result string is "guava-19.0". Afterward, the name of the module is extracted by searching for the first occurrence of the hyphen. The new string is extracted from the beginning of the resulting string until the last position before the hyphen. In our case, the string found is "guava", which corresponds to the name of the module. The string after the hyphen represents the version of the module: "19.0".

The name and version of the JAR hadoop-common-2.8.0.jar can be successfully extracted. The name of the module is hadoop.common because the hyphen from hadoop-common is replaced with a dot.

There are situations when we’re not able to extract the name of the automatic module. An example is the JAR file called spark-core_2.10-2.1.0.jar. When attempting to extract its name, we get the following error:

Unable to derive module descriptor for: spark-core_2.10-2.1.0.jar
spark.core.2.10: Invalid module name: '2' isn’t a Java identifier

The filename-based algorithm searches for the last hyphen in the string "spark_core-2.10-2.1.0" and splits the string into name and version. The resulting string for the name is "spark_core-2.10". The hyphens on this string are replaced with dots. Therefore, the string "spark.core.2.10" is computed as the name of the module. However, this string is invalid because it contains the identifiers 2 and 10, which aren’t valid as Java identifiers. As a result, an error is thrown, and the name of the automatic module can’t be extracted. If we place this JAR on the module path, we get the following exception:

java.lang.module.ResolutionException: Unable to derive module descriptor for: spark-core_2.10-2.10.jar

We get the same kind of error when we attempt to extract the module name from our com.apress.myModule0.0.1.jar, from our 123.jar, or from our 1my-module.jar:

Unable to derive module descriptor for: com.apress.myModule0.0.1.jar
com.apress.myModule0.0.1: Invalid module name: '0' isn’t a Java identifier

Unable to derive module descriptor for: 123.jar
123: Invalid module name: '123' isn’t a Java identifier

Unable to derive module descriptor for: 1my-module.jar
1my.module: Invalid module name: '1my' isn’t a Java identifier

Attempting to place any of these three JARs on the module path will result in a ResolutionException being thrown.

For the JAR commons-lang3-3.0.jar, the automatic module’s name is commons.lang3. As we can observe, the digits are preserved at the end of the module name.

The JDK 9 specification recommends that the modules names follow the reverse Internet domain-name convention. According to the specification, “a module’s name should correspond to the name of its principal exported API package, which should also follow that convention. If a module doesn’t have such a package, or if for legacy reasons it must have a name that doesn’t correspond to one of its exported packages, then its name should at least start with the reversed form of an Internet domain with which the author is associated.”

Describing a JAR File

If we have a JAR that we want to use as an automatic module and want to find out what kind of name the JPMS system derives out of it, we can use the --describe-module option of the jar tool:

jar --describe-module --file <our_JAR_name>

The --describe-module option prints the following:

• The name of the module and the version

• The module descriptor

• The entire list of packages that the JAR consists of

Listing 8-1 displays the results of running the jar command with the --describe-module option on the guava.jar file.

Listing 8-1. Running jar --describe-module on the guava-19.0.jar File

$ jar --describe-module --file guava-19.0.jar
No module descriptor found. Derived automatic module.

[email protected] automatic
requires java.base mandated
contains com.google.common.annotations
contains com.google.common.base
contains com.google.common.base.internal
contains com.google.common.cache
contains com.google.common.collect
contains com.google.common.escape
contains com.google.common.eventbus
contains com.google.common.hash
contains com.google.common.html
contains com.google.common.io
contains com.google.common.math
contains com.google.common.net
contains com.google.common.primitives
contains com.google.common.reflect
contains com.google.common.util.concurrent
contains com.google.common.xml
contains com.google.thirdparty.publicsuffix

The module system finds no module descriptor inside the guava-19.0.jar, so it derives an automatic module out of the JAR file. The new automatic module has the name “guava” and the version “19.0”. It requires java.base and consists of the packages listed above.

No Support for Automatic Modules at Link-time

There’s a limitation regarding the use of automatic modules at link-time using Jlink. There’s no support for automatic modules at link-time, which means that linking automatic modules into a runtime image is deliberately not supported. Automatic modules can’t be used with Jlink because they have access to the class path. That means that if automatic modules were hypothetically supported by Jlink, errors of type NoClassDefFoundError would have been thrown at runtime.

The ModuleDescriptor class of the new module API contains a method called isAutomatic(). This method returns true if the module is an automatic one and false otherwise. We talk about the new module API and the API support for automatic modules in the next chapter.

Now that we’ve covered almost everything we need to know about automatic modules, it’s time to look at the JDeps tool, which is an extremely important tool used to find dependencies of a library.

Find Dependencies of Unsupported JDK Internal APIs

JDeps has an option called --jdk-internals that finds dependencies of any unsupported JDK internal APIs that are private to the JDK implementation. Its syntax is as follows:

jdeps --jdk-internals --class-path <input_file>

As an input, we can specify a JAR file or a .class file that will be analyzed.

Listing 8-2 shows an example of using JDeps with the option --jdk-internals by taking the Guava library and checking whether it has any unsupported APIs.

Listing 8-2. Running jdeps --jdk-internals on the JAR File guava-19.0.jar

$ jdeps --jdk-internals guava-19.0.jar
guava-19.0.jar -> jdk.unsupported
   com.google.common.cache.Striped64 -> sun.misc.Unsafe JDK internal API (jdk.unsupported)
   com.google.common.cache.Striped64$1 -> sun.misc.Unsafe JDK internal API (jdk.unsupported)
   com.google.common.cache.Striped64$Cell -> sun.misc.Unsafe JDK internal API (jdk.unsupported)
   com.google.common.primitives.UnsignedBytes$LexicographicalComparatorHolder$UnsafeComparator -> sun.misc.Unsafe
JDK internal API (jdk.unsupported)
   com.google.common.primitives.UnsignedBytes$LexicographicalComparatorHolder$UnsafeComparator$1 -> sun.misc.Unsafe
JDK internal API (jdk.unsupported)
   com.google.common.util.concurrent.AbstractFuture$UnsafeAtomicHelper -> sun.misc.Unsafe
JDK internal API (jdk.unsupported)
   com.google.common.util.concurrent.AbstractFuture$UnsafeAtomicHelper$1 -> sun.misc.Unsafe
JDK internal API (jdk.unsupported)

Warning: JDK internal APIs are unsupported and private to JDK implementation that are
subject to be removed or changed incompatibly and could break your application.
Please modify your code to eliminate dependency on any JDK internal APIs.
For the most recent update on JDK internal API replacements, please check:
https://wiki.openjdk.java.net/display/JDK8/Java+Dependency+Analysis+Tool

JDK Internal API                         Suggested Replacement
----------------                         ---------------------
sun.misc.Unsafe                          See http://openjdk.java.net/jeps/260

In the output we can see that JDeps finds all the JDK internal libraries that the Guava library is using. In our case, it finds the JDK internal class sun.misc.Unsafe in five different locations, listed in the preceding code.

JDeps also suggests replacements for the internal APIs found. For sun.misc.Unsafe it suggests taking a look on the Open JDK website at JEP 260. In general, JDeps is capable of giving clear information about possible replacements by suggesting the class name that could be eventually used instead.

In order to prepare for using Java 9, JDeps is very useful because we can check whether our JAR files from the class path are making use of JDK internal APIs. It isn’t mandatory to replace the JDK internal APIs with the ones suggested by JDeps. We can replace them with whatever library we want. But we should replace them so that we can compile and run our application with JDK 9.

Generate Module Descriptors with JDeps

JDeps can be used to generate a module descriptor for one or more JAR files using the command-line option --generate-module-info:

jdeps --generate-module-info <output_directory> <list_of_jar_files>

This command gets two parameters :

• <output_directory> represents the directory where the module-info.java files will be created.

• <list_of_jar_files> represents one or more JAR files for which a module-info will be generated. The list is separated by a blank space. For each JAR, each dependency must be listed here.

This command creates a module descriptor module-info.java for each JAR file that we pass. To demonstrate this, next we generate a module-info.java file for the junit-4.12.jar file. We also have to pass the hamcrest-core-1.3.jar file because this JAR is a dependency of JUnit:

jdeps --generate-module-info output hamcrest-core-1.3.jar junit-4.12.jar

As a result, two module-info files are created inside the output directory, one for JUnit and one for Hamcrest Core:

outputjunitmodule-info.java
outputhamcrest.coremodule-info.java

Listing 8-3 shows an excerpt of the module-info.java files created.

Listing 8-3. Module Descriptors for JUnit and Hamcrest Core That Were Generated by JDeps

 module junit {
    requires transitive hamcrest.core;
    requires java.management;
    exports junit.extensions;
    exports junit.framework;
    exports junit.runner;
    exports junit.textui;
    exports org.junit;
    exports org.junit.experimental;
    ...
    exports org.junit.runners;
    exports org.junit.runners.model;
    exports org.junit.runners.parameterized;
    exports org.junit.validator;
}

module hamcrest.core {
    exports org.hamcrest;
    exports org.hamcrest.core;
    exports org.hamcrest.internal;
}

JDeps can also generate a module-info.java file for an open module. The command is generate-open-module and it takes the same type of parameters:

jdeps --generate-open-module <output_director> <name_of_jar_file>

The only difference is that this command creates a module descriptor that defines an open module instead of a simple module. As a result, no packages are exported. This is suitable for frameworks that access the JDK using reflection.

JDeps also provides other useful features. Table 8-2 shows a list of the most useful options offered by JDeps, as defined in the JDK 9 API specification.

We’ve looked at automatic modules and JDeps. It’s time to focus on the Java 9 encapsulation topic. We’ll learn how to break the encapsulation in Java 9, how to open packages and modules, and how to use the --add-opens, --add-reads, and --add-modules command-line options.

Exporting a Package at Compile-time and Runtime

The --add-exports option added to the Java compiler (javac) exports a package to a specific named module or to the unnamed module. It corresponds to the qualified export "exports … to" statement from the module declaration. It can be used to break the encapsulation of JDK internal APIs and to make them accessible in a named module or in the unnamed module.

The following shows the syntax of the --add-exports command-line option:

--add-exports <source_module>/<name_of_package_to_be_exported>=<list_of_target_modules>

• <source_module> represents the module where the package to be exported is located.

• <name_of_package_to_be_exported> represents the name of the package that will be exported to the <list_of_target_modules>.

• <list_of_target_modules> represents a comma-separated list of modules that will gain access to the exported package.

In Figure 8-1 the package sun.net, located in module java.base, is exported to our module com.apress.jdkinternal .

Figure 8-1. Exporting the sun.net package to a named module with the --add-exports option

In this way, the package sun.net will be accessible from our the module com.apress.jdkinternal. By compiling our application again using the option --add-exports mentioned earlier, the package sun.net will be exported to our module. We pass the module where the package is located (java.base) and the module where the package should be exported (com.apress.jdkinternal).

To compile we have to use the --add-exports option, as mentioned:

$  javac –d outputDir --add-exports java.base/sun.net=com.apress.jdkinternal --module-source-path src $(find . –name "*.java")

The compilation succeeds, and the .class files are created. However, a warning is displayed, informing us that URLCanonicalizer is an internal proprietary API that may be removed in a future release:

warning: URLCanonicalizer is internal proprietary API and may be removed in a future release
import sun.net.URLCanonicalizer;

We run the application by using exactly the same --add-exports command:

java --module-path outputDir --add-exports java.base/sun.net=com.javausergroup.jdkinternal -m com.apress.jdkinternal/com.apress.jdkinternal.Main

Because we need readability at runtime, not only at compile-time, it’s mandatory to use the same --add-exports option with the same arguments when running the application. If we had run our application without the --add-exports flag, the following error would have been thrown:

Exception in thread "main" java.lang.IllegalAccessError: class com.apress.jdkinternal.Main (in module com.apress.jdkinternal) can’t access class sun.net.URLCanonicalizer (in module java.base) because module java.base doesn’t export sun.net to module com.apress.jdkinternal
        at com.apress.jdkinternal/com.apress.jdkinternal.Main.main

The IllegalAccessError occurs at runtime because the package sun.net isn’t exported.

--add-exports java.base/sun.net=ALL-UNNAMED

Add-Exports: java.base/sun.net

Opening Packages for Deep Reflection

Chapter 4 talked about the opens clause in the module descriptors. There we mentioned that deep reflection is by default allowed by code in a named module to code on the class path, but by default it’s not allowed to code in another named module. In this second case, in order to allow reflective access from code in a named module to code in another named module, we could use the new --add-opens command-line option. It’s used to provide deep reflective access from one module to another module or to the code on the class path. It’s equivalent to a qualified opens from a module declaration:

opens <package_name> to <list_of_target_modules>

The syntax of the add-opens command-line option goes like this:

--add-opens <source_module>/<name_of_package_to_be_opened>=<list_of_target_modules>

The package defined and located in the <source_module> is opened for deep reflective access to the modules listed in the <list_of_target_modules>. These modules will be able to access the package at runtime only using deep reflection but won’t be able to access the package during compilation. If we put the constant ALL-UNNAMED instead of the <list_of_target_modules>, then the entire code on the class path will be able to access the package at runtime using deep reflection. However, this last case happens already by default, so we should use it only if someone programmatically disabled reflective access by code in a named module to code from the class path.

Because automatic modules open all their packages by default, there’s no need to open them using the --add-opens option. Now that we know how to open packages at runtime for deep reflection, let’s learn how to add readability at runtime using the option --add-reads.

Providing Readability Between Modules

The --add-reads command-line option is used at both compile-time and runtime to add readability from a module to another module. Its syntax is as follows:

--add-reads <source_module>=<list_of_target_modules>

By using the --add-reads command-line option, the <source_module> gets readability to all the modules represented by the <list_of_target_modules>, which means that the <source_module> will require all those modules. This is equivalent to providing a requires clause in a module descriptor:

module <source_module> {
        requires target_module_A;
        requires target_module_B;
}

We can make a module <source_module> read the entire class path by providing the constant ALL-UNNAMED to the --add-reads option:

--add-reads <source_module>=ALL-UNNAMED                

This option is used merely during testing—for instance, when a module is patched at compile-time and at runtime in order to add tests in the same modules as the module under test. During testing, we might need a module to read another module, although the first module doesn’t depend on the other module because it doesn’t define a requires directive to the other module. By using the --add-reads option, we get readability between the two modules. The first module will be able access all the exported types from the other module.

Suppose we have a Junit test class inside our module com.apress.testing. This class extends a class from the Junit library. So we need a readability relation from our module com.apress.testing to the automatic module junit. This can be achieved very simply using the --add-reads option:

--add-reads com.apress.testing=junit

If we have the Junit library on the class path and don’t want to move to the module path, then we use the ALL-UNNAMED constant to provide readability between our module and the entire code on the class path:

--add-reads com.apress.testing=ALL-UNNAMED

Chapter 11 provides an explanatory example of using the --add-reads command-line option for running JUnit tests.

Before we discuss the --add-modules command-line option, there’s one more thing worth mentioning: when we use reflection on a member in a module, readability is automatically granted.

Adding Modules to the Root Set

The --add-modules command-line option is used to add modules directly to the set of root modules. Hence, the modules will be resolved. This option is used to resolve modules that aren’t resolved by default.

Its syntax is simple. It takes one or more modules separated by comma:

--add-modules <module_name>(,<module_name)*

<module_name> represents the name of a module that will be added to the default set of root modules

There are three values that can be used with the --add-modules option instead of specifying a list of modules:

• ALL-DEFAULT: The official specification released for JDK 9 states that by using the ALL-DEFAULT option “the default set of root modules for the unnamed module, as defined above, is added to the root set. This is useful when the application is a container that hosts other applications which can, in turn, depend upon modules not required by the container itself.”

• ALL-SYSTEM: This option adds all the system modules to the root set.

• ALL-MODULE-PATH: This option adds all the observable modules found on the module path to the root set. It’s helpful to be able to add each module from the module path at once to the root set. For a large list of automatic modules, it’s more practical and easier to add all of them at once and without the need to enumerate them one by one. Maven uses this option considerably because it needs all the modules from the module path.

The --add-modules option is also used by Jlink to set the root module inside the runtime image. We saw in Chapter 7 how to create a runtime image and how to add modules to the runtime image using the --add-modules command-line option.

The --add-modules option can be repeated. The following usages of --add-modules options have the same effect and cause no errors:

--add-modules com.apress.moduleA --add-modules com.apress.moduleB
--add-modules com.apress.moduleA,com.apress.moduleB

Next we’ll look at an explanatory example to better understand when we should use the --add-modules option. We download the junit-4-12.jar and the hamcrest-core-1.3.jar and put them into a folder. We run jdeps -s on the entire folder to find all the dependencies of the two JAR files:

 $ jdeps -s *.jar
hamcrest-core-1.3.jar -> java.base
junit-4.12.jar -> hamcrest-core-1.3.jar
junit-4.12.jar -> java.base
junit-4.12.jar -> java.management

Hamcrest-Core depends only on java.base, meaning it use types only from java.base. Hence, Junit is depending on Hamcrest-Core because it uses types from it. If we look inside the content of Junit, we can see lots of imports from Hamcrest-Core packages.

Suppose we have a module com.apress.myModule and we put the junit-4.1.2.jar and the hamcrest-core-1.3.jar files on the module path in order to use them as automatic modules. You already learned at the beginning of this chapter, in the “Automatic Modules” section, that an automatic module can’t declare dependencies on other modules. So we can’t use the directive requires hamcrest-core because we don’t have a module descriptor available where to place it, because an automatic module doesn’t have a module descriptor module-info.java. The situation is depicted in Figure 8-2.

Figure 8-2. Relation between named modules and automatic modules that have dependencies

Module com.apress.myModule contains in its module descriptor a requires junit clause. The automatic module junit uses types from the automatic module hamcrest.core. The module graph contains the modules com.apress.myModule and junit. The module hamcrest.core isn’t added to the module graph because it can’t be identified during the resolution process. There’s no requires clause inside the junit automatic module so that the module system could discover the hamcrest.core automatic module and add it to the module graph. This means we have to manually add the hamcrest.core automatic module to the module graph using the --add-modules option at both compile-time and runtime :

--add-modules hamcrest.core

If we don’t add the hamcrest.core module to the module graph, the classes from the hamcrest.core won’t be found and an exception of type ClassNotFoundException will be thrown at runtime.

Another option provided by default in JDK is the --illegal-access one, covered in the next section.

The --illegal-access Option

The --illegal-access option was added into JDK 9 to ease migration. This option states that code on the class path can perform illegal reflective access by default.

With the --illegal-access option, the code on the class path gets reflective access to types in any named modules. The reflective access is done using standard reflection-related APIs like java.lang.reflect and java.lang.invoke. --illegal-access is very useful for third-party frameworks like Spring, Hibernate, or Guava, which were so designed that they need to perform reflective access inside the internals of the JDK in order to be able to work properly.

The syntax of the --illegal-access option is as follows:

java --illegal-access <options>

The --illegal-access option can take one of four possible parameters: permit, warn, debug, and deny:

• --illegal-access=permit: The permit mode represents the default behavior in Java 9. It states that every package from every module is opened for deep reflection to code in all the unnamed modules. The unnamed modules represent the class path. This means that at runtime the code from the class path can access the entire information stored in modules using deep reflection. A warning will be displayed during the first access.

• --illegal-access=warn: The warn mode is very similar to the permit mode previously discussed. The only difference is that the warn mode returns a warning each time an illegal access is performed using reflection.

• --illegal-access=debug: The debug mode shows a warning in the stack trace for every illegal access performed using reflection.

• --illegal-access=deny: The deny mode disables all the illegal access operations using reflection. When this mode is set, no illegal access can be done using reflection. Hence, this mode can be overwritten by the command-line option --add-opens. With --add-opens we’re able to open specific packages for reflection.

However, the JCP team announced that the --illegal-access option will be removed in JDK 10. It will be available only in JDK 9 in order to ease migration of third-party libraries that were constructed by making use of deep reflective access into the internals of the JDK. The --illegal-access option has not been planned right from the beginning. It was added later in order to ease migration to Java 9, because an important number of external libraries and frameworks use reflection to access the internal APIs of the JDK.

This option emits warning messages when used:

WARNING: Illegal access by A to B (permitted by C)

• A is the name of the type that contains the code that invoked the reflective operation in question.

• B is the name of the member being accessed.

• C is the name of the command-line option that enabled this access.

The next example shows what kind of warning messages are displayed when a library performs illegal reflective access to types in the JDK. We run the java -jar command on the the JRuby Complete-9.1 JAR file:

$ java -jar jruby-complete-9.1.12.0.jar

WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by org.jruby.util.io.FilenoUtil (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to method sun.nio.ch.SelChImpl.getFD()
WARNING: Please consider reporting this to the maintainers of org.jruby.util.io.FilenoUtil
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

A warning message lets us know that the jruby-complete-9.1.12.0.jar performs an illegal reflective access operation on method sun.nio.ch.SelChImpl.getFD() of the JDK. This illegal reflective access is allowed, because the --illegal-access flag is set by default.

If we want to see a warning for every illegal access performed, we can use the mode=warn of the --illegal-access command-line option:

$ java --illegal-access=warn -jar jruby-complete-9.1.12.0.jar

WARNING: Illegal reflective access by org.jruby.util.io.FilenoUtil (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to method sun.nio.ch.SelChImpl.getFD()
WARNING: Illegal reflective access by org.jruby.util.io.FilenoUtil (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to field sun.nio.ch.FileChannelImpl.fd
WARNING: Illegal reflective access by org.jruby.util.io.FilenoUtil (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to field java.io.FileDescriptor.fd
WARNING: Illegal reflective access by jnr.posix.JavaLibCHelper (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to method sun.nio.ch.SelChImpl.getFD()
WARNING: Illegal reflective access by jnr.posix.JavaLibCHelper (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to field sun.nio.ch.FileChannelImpl.fd
WARNING: Illegal reflective access by jnr.posix.JavaLibCHelper (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to field java.io.FileDescriptor.fd
WARNING: Illegal reflective access by jnr.posix.JavaLibCHelper (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to field java.io.FileDescriptor.handle
WARNING: Illegal reflective access by org.jruby.java.invokers.RubyToJavaInvoker (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to method java.lang.Object.clone()
WARNING: Illegal reflective access by org.jruby.java.invokers.RubyToJavaInvoker (file:/C:/Users/Alex/Downloads/jruby-complete-9.1.12.0.jar) to method java.lang.Object.finalize()
...

The output is very long, so we decided not to include it all. You can see that the type that performs the illegal reflective access is displayed together with the name of the method or the field from the JDK that’s accessed reflectively.

The JDK 9 API introduced a new useful method in the AccessibleObject class of package java.lang.reflect called boolean canAccess(Object object). This method lets us test whether the caller can access this reflected object. The method returns true if access is allowed and false otherwise. According to the JDK 9 API documentation, an IllegalArgumentException will be thrown if “this reflected object is a static member or constructor or if it is an instance method or field and the given object is null.” To avoid any exceptions, we could also use the new boolean trySetAccessible() method from the same class. This method doesn’t throw any exceptions except a SecurityException if the request is denied by the Security Manager.

We talked about the command-line flags. Now it’s time to present some migration issues that can commonly occur.

Encapsulated JDK Internal APIs

Throughout the book we’ve talked about the encapsulation of the JDK internals APIs. This can cause critical problems when we move to JDK 9. However, this probably isn’t the most encountered problem during migration to JDK 9. In our opinion, the split packages and cyclic dependencies problems can occur more often.

Two independent solutions can help solve the problem of JDK internal APIs:

• Replace each of your JDK internal APIs with supported APIs.

• Keep the existing JDK internal APIs and use the --add-exports command-line option to break the encapsulation—to make the JDK internal APIs accessible to code in other modules or to code on the class path.

The first solution is by far the better one because we completely get rid of the unsupported JDK APIs in our code. Because the JDK internal APIs are marked as deprecated, it’s wise to provide replacements for them as soon as possible.

The second solution is reasonable if you don’t have enough time to replace the unsupported JDK internal APIs with supported ones. If all you want is to make your code compile and run again using JDK 9 this time, using the --add-exports option is a way to move forward. However, Oracle has stated that the JDK unsupported APIs will be removed in the next major JDK release. This could be JDK 10 or later. Sooner or later, you’ll have to replace them with supported JDK APIs in order to ensure that your code won’t break. As a conclusion, adding the --add-exports option is just a temporary solution to make code work. There’s no guarantee how long this workaround will work. It all depends on how long the unsupported JDK APIs that you’re using will remain in JDK and not be removed.

We already saw in this chapter how to identify the presence of JDK internal APIs in a JAR file or in a module: by using the JDeps tool with the option --jdk-internals. Let’s move on to discuss another possible problem we may encounter during compilation: not resolved modules.

Not Resolved Modules

Remember the module graph that resulted after the modularization of the JDK ? Figure 8-3 shows a small part of it.

Figure 8-3. Small part of the module graph of the Java SE modules with module java.se.ee at the top

Module java.se.ee is located right at the top of the module graph, and module java.se is only a level below. As described in Chapter 3, the differences between the module java.se.ee and the module java.se are as follows:

• The module java.se.ee collects all modules that comprise the Java SE platform, including the modules that overlap with the Java EE platform.

• The module java.se collects all the modules that comprise the Java SE platform that don’t overlap with the Java EE platform.

• The module java.se.ee contains a total number of five modules that aren’t present in module java.se: java.xml.ws, java.xml.bind, java.corba, java.activation, and java.xml.ws.annotation.

We deliberately use the term collects instead of contains here because both module java.se.ee and module java.se are aggregator modules, which means that according to the JDK 9 specification, they “collect and re-export the content of other modules but add no content of their own.”

During the compilation process in JDK 9, the java.se module is considered the root module and not the java.se.ee module. This means that in the compilation step, the visible modules are the ones that are under the java.se module. It also means that the five modules from the module java.se.ee that aren’t in module java.se aren’t visible at compilation.

If our code makes use of any of the following five modules, the compilation will fail:

• java.xml.ws

• java.xml.ws.annotation

• java.xml.bind

• java.corba

• java.activation

We can compare the modules contained by the java.se module with the modules contained by the java.se.ee module by limiting the observable modules with the --limit-modules option. The following two commands return the name of all the modules having module java.se and java.se.ee, respectively, in the root of the transitive closure:

java --limit-modules java.se --list-modules
java --limit-modules java.se.ee --list-modules

The solution for getting rid of the non-resolved modules problem is simple. We have to add the modules to the default root set of modules at both compile-time and runtime using the --add-modules command-line option, so they can be resolved:

--add-modules <module_name>

For instance, if we’re using types from module java.xml.ws, then it’s absolutely necessary to always add the module java.xml.ws in the root set of modules at both compile-time and runtime:

javac --add-modules java.xml.ws
java --add-modules java.xml.ws

As a result, the java.xml.ws module is resolved and can be used.

We now know that by adding the modules to the root set of module we can solve compilation errors like "package java.activation doesn't exist" or "package java.xml.bind doesn't exist".

It’s time to explore another issue that can occur during migration: split packages.

Split Packages

The split packages problem is one of the most serious problems that can take place in the Java 9 modular world. Split packages occur when two or more members of a package reside in more than one module. In order to support reliable configuration, the Java Platform Module System doesn’t allow split packages at compile-time. The reason is that the system loads all the modules from the module path with a single class loader, which can’t have more than one single type of a package. Two modules loaded by the same class loader can’t split a package.

Figure 8-4 illustrates two modules having a split package.

Figure 8-4. Two modules having a split package

Module A and module B contain both the package myPackage. Even if the modules contain different subpackages, the split package problem is present, because they share a package with the same name. The split package arises even if the packages aren’t exported.

In this case, the compilation will fail with the following error because we have split packages at compile-time:

error: module A reads package myPackage from both A and B

This error clearly states that the package B is in both module A and module C.

A split package problem can occur for every type of package, even for packages that aren’t exported, the so-called concealed packages . If two modules contain a package with the same name, an error will occur when we put the modules on the module path. It doesn’t matter if the packages are exported, open, or concealed. The split package problem will occur anyway.

It’s also important to mention another aspect. If we develop our own module that uses a package name that already exists in one of the platform modules, we have the split packages problem too.

There’s no universal solution to repair the split packages problem. You can choose whatever solution you want in order to reach the desired goal—to not have a package or members of a package with the same name in more than one module.

Suppose we have two third-party JAR files that share a package with the same name. Some of the most used solutions to fix the split packages problems include the following:

• Create a single JAR file out of the two JAR files. Combine them into a single JAR file. If we have two third-party JAR files that share a package with the same name, then we could make a single JAR file out of the two by unzipping them in the same directory and then zipping the entire directory into a single ZIP file. Don’t forget to change the suffix of the new ZIP file into a JAR file. In this way, we have just one single JAR that can be put into the module path and have just one automatic module, not two. The package is now in a single module, and the split packages issue is gone.

• Check to see whether one of the JARs can be eventually replaced by a different one. If there’s a chance of replacing the JAR with another one, we should at least try it.

• Rename one of the packages. Renaming one of the packages is also a solution to consider. The probability of success depends on the structure of the classes and especially if the classes live in a single namespace or not.

Until now we’ve talked about different use cases for JAR files . Let’s move on to modules. There are three possible solutions that can help getting rid of split packages in the case of modules:

• Create a single module out of two or more modules: Combine them into a single module. If we have two modules that share a package with the same name, then we could eventually redesign our code and have just one module out of the two.

• Create a third module: Another option would be to take the entire packages that cause the split package problem from both modules and move them into a third new module, which exports the packages we need inside our module. This solution is much easier to implement.

• Attempt to remove the package dependencies: This is questionable and can be implemented only if you really don’t need the dependency anymore.

You’ve seen some suggestions of how to solve the split packages problem . You can choose these approaches or implement your own solutions in order to reach the goal of not having a package with the same name in more than one module.

The JEP 200 states that “a non-standard module must not export any standard API packages.” This makes sense because if we have our own module com.apress.myModule, we shouldn’t, for example, export the java.sql package, because the java.sql package is already exported by the java.sql platform module. This will result in a split package.

One requirement of the JPMS states that “the Java compiler, virtual machine, and runtime system must ensure that modules that contain packages of the same name don’t interfere with each other. If two distinct modules contain packages of the same name then, from the perspective of each module, all of the types and members in that package are defined only by that module. Code in that package in one module must not be able to access package-private types or members in that package in the other module.”

The next section talks about another problem that can arise: cyclic dependencies.

Cyclic Dependencies

A cyclic dependency is a relation between two or more modules expressed by the fact that the modules depend on each other, either directly or indirectly. Cyclic dependencies are considered anti-patterns. They aren’t allowed at compile-time in Java 9. If two modules contain a cyclic dependency, the compilation will fail. Jigsaw deliberately imposes a cyclic dependency check during compilation. The requirement imposed by the Java Platform Module System is severe: no cycle dependencies are allowed in the module graph.

However, cyclic dependencies are allowed at runtime, but only after the module graph is already resolved. We refer here to the reads relations of runtime modules, which are allowed at runtime. Cyclic dependencies aren’t allowed at compile-time, link-time, and runtime when the module graph is resolved for the first time. But at runtime, you can add readability edges using the command-line option --add-reads. At runtime, you can introduce a cyclic dependency using the --add-reads option because the module graph has already been resolved before and because we’re at runtime, not at compile-time.

The reasons for interdicting cyclic dependencies are justified: to simplify the module system or to make the module graph more understandable. Two modules that require each other would be better represented as a single module.

Cyclic dependencies can occur often for automatic modules, for instance. Because automatic modules imply readability to all other modules, the likelihood of getting two modules that depend on each other isn’t low.

Chapter 4 had an example of cyclic dependency in our module declaration. Cyclic dependencies can be solved by using interfaces to decouple the coupling between modules. A module should depend on an interface, not on another module. This can be implemented using the Service Provider API described in Chapter 6. What we need to do is to implement Service consumers and Service providers to decouple the coupling between modules.

We covered the cyclic dependencies issue in this section. The next section covers the new versioning scheme introduced in JDK 9.

New Versioning Scheme

Java 9 introduces a new format to define the version. This matters for a migration point of view because code that relies on the old string format will break. The maintainers of the Hadoop library had to fix the Hadoop library because it was broken in JDK 9 due to the introduction of the new version format:

System.getProperty("java.version").substring(0, 3).compareTo("1.7") >= 0

This piece of code isn’t working on JDK 9 anymore, because the version is no longer represented as 1.7. Instead of 1.7, the new version could have a format similar to 7 (containing only the major version) or 7.1.1 (containing the major version, minor version, and security version).

The format of the new version string is as follows:

$MAJOR.$MINOR.$SECURITY.$PATCH

• $MAJOR serves as the major version of a JDK release.

• $MINOR serves as the minor version of a JDK release.

• $SECURITY serves as a security-related release of the JDK.

The changes affect not only java -version, but also the following system properties: java.runtime.version, java.vm.version, java.specification.version, and java.vm.specification.version.

We know how the new version looks in JDK 9, so let’s move on and see what methods were removed in JDK 9.

Removed Methods in JDK 9

The following methods have been completely removed in Java 9:

• java.util.logging.LogManager.addPropertyChangeListener

• java.util.logging.LogManager.removePropertyChangeListener

• java.util.jar.Pack200.Packer.addPropertyChangeListener

• java.util.jar.Pack200.Packer.removePropertyChangeListener

• java.util.jar.Pack200.Unpacker.addPropertyChangeListener

• java.util.jar.Pack200.Unpacker.removePropertyChangeListener

We should make sure not to use these six methods in Java 9—otherwise our code will break at compile-time. The probability of having one at least one of these six methods in our code is low.

Another change in JDK 9, with a definitely greater impact, is the removal of the runtime rt.jar and of tools.jar and dt.jar .

Removal of rt.jar, tools.jar, and dt.jar

Chapter 2 talked about the removal of the rt.jar, tools.jar, and dt.jar in JDK 9. This can have a consequence on our code if we make assumptions throughout our code based on one of these three JAR files. But the impact is greater on tools rather than on our own code.

Calling the ClassLoader::getSystemResource() method in JDK 9 won’t return an URL to a JAR file. Instead, it will return a valid URL.

If we call the method getSystemResource() with the parameter java/lang/Class.class,

ClassLoader.getSystemResource("java/lang/Class.class")

The following URL will be returned:

jrt:/java.base/java/lang/Class.class

We have to be aware of these new changes and check if our code expects to receive this URL in a specific format, which may now not be the same.

Let’s move to the next section, where we show migration strategies for migrating a Java application to Java 9.

Top-down Migration

We have a small application that reads some news from a JSON file using Google Gson . It logs the output using SLF4J and formats it using Google Guava. Therefore, we have four JAR libraries on the class path:

• slf4j-simple-1.7.25.jar

• slf4j-api-1.7.25.jar

• guava-21.0.jar

• gson-2.8.0.jar

Our application consists of a POJO class called News that has four attributes: id, title, category, and link. It also consists of a Main class that reads the entire information from the news.json file as a list of News objects. A for loop iterates over the entire list of News, formats the results so that everything is uppercase, and then logs the results.

Listing 8-5 shows the News class .

Listing 8-5. The News Class

package org.news;

public class News {

    private String id;

    private String title;

    private String category;

    private String link;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getCategory() {
        return category;
    }

    public void setCategory(String category) {
        this.category = category;
    }

    public String getLink() {
        return link;
    }

    public void setLink(String link) {
        this.link = link;
    }

    @Override
    public String toString() {
        return "Id: " + id + " - " + "Title: " + title + " - " + "Category: " + category + " - " + "Link: " + link;
    }
}

Listing 8-6 represents the Main class , which imports packages from Gson, Guava, and SLF4J, reads the news.json, logs its content, and also formats it.

Listing 8-6. The Main Class of our Application

package org.news;

import java.io.*;
import java.lang.reflect.Type;
import java.util.ArrayList;
import java.util.List;
import com.google.gson.reflect.TypeToken;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.common.base.CaseFormat;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {

    public static void main(String[] args) throws FileNotFoundException {

        Logger logger = LoggerFactory.getLogger(Main.class);

        BufferedReader bufferedReader = new BufferedReader(new FileReader("news.json"));

        Type listType = new TypeToken<ArrayList<News>>(){}.getType();
        List<News> yourClassList = new Gson().fromJson(bufferedReader, listType);

        for(News news : yourClassList) {
            logger.info("Id: " + CaseFormat.LOWER_UNDERSCORE.to(CaseFormat.UPPER_UNDERSCORE, news.getId()));
            logger.info("Title: " + CaseFormat.LOWER_UNDERSCORE.to(CaseFormat.UPPER_UNDERSCORE, news.getTitle()));
            logger.info("Category: " + CaseFormat.LOWER_UNDERSCORE.to(CaseFormat.UPPER_UNDERSCORE, news.getCategory()));
            logger.info("Link: " + CaseFormat.LOWER_UNDERSCORE.to(CaseFormat.UPPER_UNDERSCORE, news.getLink()));
        }
    }
}

First, we compile and run our application in JDK 9 using only the class path, so we’re sure that our application works in JDK 9 without any changes.

javac -d out -cp "lib/gson-2.8.0.jar;lib/guava-21.0.jar;lib/slf4j-api-1.7.25.jar;lib/slf4j-simple-1.7.25.jar" $(find src -name '*.java')

We create a JAR file named news.jar:

jar --create --file lib/news.jar -C out.

Finally, we run our application:

java -cp "lib/gson-2.8.0.jar;lib/guava-21.0.jar;lib/slf4j-api-1.7.25.jar;lib/slf4j-simple-1.7.25.jar;lib/news.jar" org.news.Main

Our application is running successfully. We now have the confirmation that our not modularized application is running with JDK 9 without any changes.

Let’s start the modularization process. In this part we’ll modularize our News application only as part of the top-down migration strategy. We won’t modularize and won’t even change the four JAR files that represent our dependencies.

The first thing we do is to create a module-info.java file in the root directory. We have to figure out what kind of requires and exports clauses we need to put inside the module descriptor. We have to require our dependency JAR files inside the module descriptor and we do this by putting them on the module path so they become automatic modules. We covered the automatic modules in detail at the beginning of this chapter, where we also talked about how to find out the name of the generated automatic modules:

jar --describe-module --file gson-2.8.0.jar

By running the command jar --describe-module on the Gson JAR file , we find out that the generated name of the automatic module is gson. We add this name into our module descriptor and do the same for all the other JAR files , because our application depends on these. If we’re not sure about the dependencies used by our application, we can run the Jdeps on our previously created news.jar file:

$ jdeps -cp "lib/gson-2.8.0.jar;lib/guava-21.0.jar;lib/slf4j-api-1.7.25.jar;lib/slf4j-simple-1.7.25.jar;lib/news.jar" -s lib/news.jar

news.jar -> libgson-2.8.0.jar
news.jar -> libguava-21.0.jar
news.jar -> java.base
news.jar -> libslf4j-api-1.7.25.jar

The JDeps tool informs us that our news.jar file has dependencies on three JAR files and on module java.base.

Our module-info.java looks like this:

module news {
    requires slf4j.simple;
    requires slf4j.api;
    requires guava;
    requires gson;
}

Because our News application is standalone and isn’t an API, we have no exports clauses. We don’t need to give our application to somebody else to include it in their own application, so exports clauses are for the moment not necessary.

We compile our application:

javac -d modules --module-path lib --module-source-path src -m news

Now, if we take a look in the modules directory, we see that we have .class files not only for the corresponding Java classes, but also for the module-info.java we have a compiled module-info.class file .

We create a modular JAR for our application :

jar --create --file lib/news.jar -C modules/news.

Next we run our Main class:

java --module-path lib -m news/org.news.Main

Unfortunately, we got a ClassNotFoundException, which informs us that the class java.sql.Time can’t be found:

Exception in thread "main" java.lang.NoClassDefFoundError: java/sql/Time
        at [email protected]/com.google.gson.Gson.<init>(Gson.java:240)
        at [email protected]/com.google.gson.Gson.<init>(Gson.java:174)
        at news/org.news.Main.main(Main.java:23)
Caused by: java.lang.ClassNotFoundException: java.sql.Time
        at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(Unknown Source)
        at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(Unknown Source)
        at java.base/java.lang.ClassLoader.loadClass(Unknown Source)
        ... 3 more

The java.sql.Time class is located in the java.sql module. We need to add this module to the root set of modules using the --add-modules option so it can be resolved:

java --add-modules java.sql --module-path lib -m news/org.news.Main

The previous error doesn’t appear anymore, because it was solved. Unfortunately, we get now a different type of exception:

Exception in thread "main" java.lang.reflect.InaccessibleObjectException: Unable to make field private java.lang.String org.news.News.id accessible: module news doesn’t "opens org.news" to module gson
        at java.base/java.lang.reflect.AccessibleObject.checkCanSetAccessible(Unknown Source)
        at java.base/java.lang.reflect.AccessibleObject.checkCanSetAccessible(Unknown Source)
        at java.base/java.lang.reflect.Field.checkCanSetAccessible(Unknown Source)
        at java.base/java.lang.reflect.Field.setAccessible(Unknown Source)

We get an InaccessibleObjectException because Gson is performing deep reflective access into the JDK and it doesn’t succeed because our package org.news is by default not opened for deep reflection. We have to open our package org.news to module Gson using a qualified opens clause. Therefore, we need to add the following statement in our module descriptor:

opens org.news to gson;

We compile and run our application again, and, because we opened the org.news package so that the Gson library can perform deep reflection on it, it works.

In this section, we managed to migrate an application that uses JAR files to run on JDK 9. We created a module for our own code and put the JAR files on the module path by transforming them into automatic modules. We don’t have any code on the class path, because the entire code is now on the module path.

This was top-down migration , where we modularize our application and use the JAR libraries as automatic modules on the module path .