Module Declaration

Each module has a module declaration located into a special new file called module-info.java, located in the top level of the directory. To define a module in Java 9, we create the file module-info.java and put inside it the new keyword module followed by the module name and the module declaration in curly brackets.

Declaring a module is easy and straightforward. In this example, a module called com.apress.moduleA is declared inside the module-info.java file:

module com.apress.moduleA {}

In this case, the module declaration doesn’t contain anything besides the module heading. Module com.apress.moduleA doesn’t require any modules, nor does it export any packages, and it doesn’t provide or consume any services.

As already mentioned, each module must have a module declaration and thus must contain an own module-info.java file. This rule applies no matter whether it’s a platform module or a module created by developers. If the module-info.java file isn’t present, the Java compiler doesn’t treat the source code as a module. The module-info.java file gets compiled in exactly the same way as a Java file.

If we change the name of the module-info.java file to something else, the compiler will interpret the file as a normal file rather than as a module descriptor. In this case, the module system won’t be able to recognize the module anymore.

Let’s describe some cases to see what we can put in a module-info.java file and what we can’t. Module-info.java can’t contain anything besides the module definition. The Java compiler can recognize syntax errors in the module declaration.

If the module declaration isn’t in the module-info.java file, the following error message will be displayed by the Java compiler, and the compilation will fail:

Error: module declarations should be in a file named module-info.java

A Java class can’t be put into the module-info.java file instead of a module. If you try to do so, the compilation will also fail:

error: cannot access module-info
  bad source file: srccom.apress.moduleAmodule-info.java
    file does not contain module declaration
    Please remove or make sure it appears in the correct subdirectory of the sourcepath.

Besides that, attempting to write two module declarations in a single module-info.java file will also result in a compilation error. As we already observed in the examples presented earlier, the Java compiler gives concrete indications about the cause and the location of the errors. In this way, we can go directly to the line of code that generates the issues and provide a fix for it.

The module-info.java module descriptor is compiled together with the source code. As a result, .class files, including a module-info.class file, are generated. All these compiled files can be packaged as a modular JAR file (we cover modular JAR files later in this chapter). The compiler treats module-info.java like any other Java file and translates it into a module-info.class file that we can put in a JAR file. The result is a modular JAR.

Platform modules consist of a module-info.java file by default. If we create our own module, in most cases we have to create and write the content of the module-info.java file on our own. But there are two cases when we don’t write a module-info.java file on our own:

• When we put a JAR file on the module path, a module-info.java file will be automatically generated.

• When we automatically generate a module-info.java file for a specific JAR file using the JDeps tool and the option --generate-module-info.

Don’t worry if notions like module path and JDeps are unfamiliar to you. You’ll find out later in this book what they are.

The requires Clause

The requires clause is used inside the module declaration (module-info.java) to express the module that the actual module needs upon in order to fulfill its dependencies. It’s used to express the module’s dependencies.

Figure 4-2 shows the syntax of the requires clause.

Figure 4-2. Syntax of the requires clause

The syntax is simple and concise. The requires directive specifies the name of the module it depends upon, followed by a semicolon. Inside the curly brackets of the module declaration we can put one or more requires clauses, each of them followed by the name of the module.

In the following example, the module com.apress.moduleA requires two modules, module com.apress.moduleB and module com.apress.moduleC:

module com.apress.moduleA {
        requires com.apress.moduleB;
        requires com.apress.moduleC;
}

In this example, two dependencies are expressed using the requires clauses. Module com.apress.moduleA has a dependency on module com.apress.moduleB and also has a dependency on module com.apress.moduleC. In this case, we say that module com.apress.moduleA requires (or reads) module com.apress.moduleB and requires (or reads) module com.apress.moduleC.

Figure 4-3 shows a module graph that illustrates these dependencies.

Figure 4-3. Module graph expressing dependencies between the three modules

In the module graph we have an arrow from module com.apress.moduleA to module com.apress.moduleB and also an arrow to module com.apress.moduleC. There is no arrow between module com.apress.moduleB and module com.apress.moduleC because those two modules don’t have dependencies between them. The direction of the arrow is straightforward: from com.apress.moduleA to com.apress.moduleB, because module com.apress.moduleA reads the module com.apress.moduleB and not inversely.

What does it mean that module com.apress.moduleA has a dependency on module com.apress.moduleB and on module com.apress.moduleC? It means that module com.apress.moduleA uses types that are part of module com.apress.moduleB and of module com.apress.moduleC. Because module com.apress.moduleA uses types from those modules, it has dependencies on them that must be explicit declared in the module descriptor module-info.java. In this way, the Java compiler knows at compile-time what the dependencies of a module are and doesn’t allow the compilation if a single dependency is not fulfilled.

Note

Compared to the class path, the situation when a module dependency isn’t fulfilled is detected right at compile-time using the Java 9 Module System. It would have not been allowed for module com.apress.moduleB to also read module com.apress.moduleA at the same time at compile-time. We would then have had a circular dependency, which is in JDK 9 forbidden by the Java compiler.

If we try to run module com.apress.moduleA, a resolution is first performed. A resolution represents a process that searches and discovers the modules required by a module. All the modules found on the host system are being searched, and the modules found are searched again for dependencies. This process continues and runs until every required module has been covered and until every dependency of every required module has been solved. In our case, the resolution is simple, because module com.apress.moduleA requires only two modules: module com.apress.moduleB and module com.apress.moduleC. We suppose that these last two modules don’t have any dependencies upon other modules. In this case, the resolution process is successfully finished after all three modules are added to the module graph. For instance, if module com.apress.moduleB has had other dependencies, these would have been resolved and also added to the module graph. The result of the resolution process contains the entire data required for compiling and running the root module, com.apress.moduleA.

Every module implicitly requires java.base, as we already know. Mentioning requires java.base in the module descriptor is unnecessary because module java.base is by default required by every module. The module java.base will always be located right at the bottom of the module graph because every module depends upon it. Figure 4-4 shows the previous module graph with module java.base included at the bottom.

Figure 4-4. Module graph expressing dependencies between modules, including module java.base

If a module descriptor doesn’t contain any requires clauses, the module doesn’t have any dependency on any module except for module java.base. Module java.base doesn’t have any requires directives because it doesn’t depend upon any other module.

Until now, we’ve looked at only the positive cases. Let’s also explore some cases when something goes wrong and the compilation fails. The compilation will fail if the module used in the requires clause isn’t found. The following module declaration states that it requires module com.apress.moduleB, but if this module hasn’t been defined, compiling com.apress.moduleA will result in an error, because its dependencies can’t be fulfilled:

module com.apress.moduleA {
        requires com.apress.moduleB;
}

We state that a module isn’t defined if it doesn’t have a module-info.java file or if its module-info.java file doesn’t contain the right name of the module. In the previous example, the output of the compilation of module com.apress.moduleA results in an error:

error: module not found: com.apress.moduleB

We get the same results if we have a qualified export to a module that isn’t found.

Loops in module declarations aren’t allowed, as in the following example:

module com.apress.moduleA {
        requires com.apress.moduleA;
}

This module declaration has a cyclic dependence and results in a compilation error:

error: cyclic dependence involving com.apress.moduleA requires com.apress.moduleA

Note

Cyclic dependencies aren’t allowed by the module system at compile-time.

Listing 4-1 shows an example of a simple circular dependency between three modules.

Listing 4-1. Defining Three Module Descriptors for Three Distinct Modules

// module-info.java (module com.apress.moduleA)
module com.apress.moduleA {
        requires com.apress.moduleB;
}

// module-info.java (module com.apress.moduleB)
module com.apress.moduleB {
        requires com.apress.moduleC;
}

// module-info.java (module com.apress.moduleC)
module com.apress.moduleC {
        requires com.apress.moduleA;
}

A circular dependency is present because of the following conditions:

• module com.apress.moduleA depends on module com.apress.moduleB.

• module com.apress.moduleB depends on module com.apress.moduleC.

• module com.apress.moduleC depends on module com.apress.moduleA.

The compilation of these three modules fails because it results in the same cyclic dependence error as in the previous example.

Every requires statement must contain only one module name. It can’t enumerate two module names using a comma in a single requires statement. In this case, we’ll get an error during compilation. It’s also forbidden to duplicate two requires statements in the same module declaration. The compilation error message would then be as follows:

error: duplicate requires: <module_name>

What happens when a module depends on other module but doesn’t declare this dependency inside its module descriptor? In this next example, the descriptor for module com.apress.moduleA reflects that it doesn’t require any other module. Listing 4-2 shows the module descriptor of this module:

Listing 4-2. The Module Descriptor of module com.apress.moduleA

// module-info.java
module com.apress.moduleA {

}

In Listing 4-3, module com.apress.moduleA contains a class called Main that imports and makes use of types from module com.apress.moduleB.

Listing 4-3. The Main Class of module com.apress.moduleA

// Main.java (module com.apress.moduleA)
package com.apress.moduleA;
import com.apress.moduleB.*;

public class Main {
        public static void main(String[] args) {
                Employee employee = new Employee("John", "Albert");
                System.out.println("First name is : " + employee.getFirstName());
                System.out.println("Last name is : " + employee.getLastName());
        }
}

Listing 4-4 defines the module com.apress.moduleB, which has an empty module declaration.

Listing 4-4. The Module Descriptor of module com.apress.moduleB

// module-info.java
module com.apress.moduleB {

}

Listing 4-5 defines a POJO class as part of the com.apress.moduleB module.

Listing 4-5. Class Employee from module com.apress.moduleB

// Employee.java (module com.apress.moduleB)
package com.apress.moduleB;
public class Employee {

        private String firstName;
        private String lastName;

        public Employee() {
        }

        public Employee(String firstName, String lastName) {
                this.firstName = firstName;
                this.lastName = lastName;
        }

        public String getFirstName() {
                return firstName;
        }

        public String getLastName() {
                return lastName;
        }
}

We compile all the .java files from both modules at the same time using the following command:

javac -d output --module-source-path src $(find  . -name "*.java")

Note

This compilation is done using Cygwin in Windows. Cygwin is a Unix-like command-line interface that runs in Windows. Throughout this book all the operations are performed using Cygwin.

For compilation we use the --module-source-path command-line option in order to indicate to javac the location of the source code of the modules. In our example, the --module-source-path src option defines that the subdirectories of the src directory comprise the code for various modules.

The compilation fails, and we’re informed that the package com.apress.moduleB doesn’t exist:

.srccom.apress.moduleAcomapressmoduleAMain.java:3: error: package com.apress.moduleB does not exist
import com.apress.moduleB.*;
^
.srccom.apress.moduleAcomapressmoduleAMain.java:8: error: cannot find symbol
                Employee employee = new Employee("John", "Albert");
                ^
  symbol:   class Employee
  location: class Main
.srccom.apress.moduleAcomapressmoduleAMain.java:8: error: cannot find symbol
                Employee employee = new Employee("John", "Albert");
                                        ^
  symbol:   class Employee
  location: class Main
3 errors

Module com.apress.moduleA has an empty module declaration. It doesn’t require any other module, so it can’t access types from other modules according to the strong encapsulation mechanism introduced in Jigsaw. This is why attempting to access types from the module com.apress.moduleB inside com.apress.moduleA results in a compilation error.

Note

You can find the source code for this example in the directory /ch04/requiresClause.

Let’s edit module-info.java of the module com.apress.moduleA and add the dependency to module com.apress.moduleB. Listing 4-6 shows its new module descriptor.

Listing 4-6. The Module Descriptor of module com.apress.moduleA

// module-info.java
module com.apress.moduleA {
        requires com.apress.moduleB;
}

Now we try to compile the source code again using the same options. Unfortunately, exactly the same compilation error as the one that we previously had. That’s because in Java 9 it’s not enough to specify that a module requires another module in order to access types from that module.

Additionally, the second module must export some of its types in order to make them accessible to the modules that depend upon it. In our case, for the compilation to successfully work, we must modify module-info.java of module com.apress.moduleB and specify that it exports all the types from package com.apress.moduleB. Listing 4-7 shows the new definition of its module-info.java file.

Listing 4-7. The Module Descriptor of Module com.apress.moduleB

// module-info.java
module com.apress.moduleB {
        exports com.apress.moduleB;
}

To recap, we’ve learned up to now how to define dependencies upon other modules using the requires clause. The property of a module to specify the modules that it requires represents the base of reliable configuration. Until now we’ve used only the simple form of the requires clause. Hence, the requires clause can also include the static keyword as well as the transitive keyword. We explain the requires transitive clause later in the “Accessibility” section.

The requires static myModule clause indicates that the module myModule should be present only at compile-time. At runtime, its presence isn’t mandatory. In this way, we must have a compile-time dependency, but no runtime dependency.

Let’s find out how to make a module express that it makes its packages available for other modules that depend upon it. The next section explains how the exports clause can be used inside the module declaration.

The exports Clause

The exports clause has the role of exporting a package at compile-time as well as at runtime. It allows a module to specify which packages it exports. Only an exported package can be available to other modules, provided that the other conditions regarding reliable configuration are met. The reverse is also true. A package that isn’t exported isn’t available for any other modules.

Note

A module doesn’t export any package by default. This means that by default, no package from the current module is available to other modules for access.

The exports clause is specified in the module descriptor by using the keyword exports followed by the package name. It’s forbidden to separate packages or modules using a comma. For each package, a separate exports clause must exist.

Figure 4-5 shows the syntax of the exports clause.

Figure 4-5. Syntax of the exports clause

Similar to the requires clause, the exports clause has some constraints. For example, duplicating the exports statements inside the module declaration isn’t allowed and results in a compilation error:

error: duplicate export: <module_name>

We suppose that module com.apress.moduleB wants to make two of its packages, com.apress.moduleB.packageB1 and com.apress.moduleB.packageB2, available to other modules that require it. In this case we say that module com.apress.moduleB exports those packages. Listing 4-8 illustrates this in its module declaration.

Listing 4-8. The module-info.java of module com.apress.moduleB

module com.apress.moduleB {
        exports com.apress.moduleB.packageB1;
        exports com.apress.moduleB.packageB2;
}

Listing 4-9 states that module com.apress.moduleC also exports a package called com.apress.moduleC.packageC1.

Listing 4-9. The Module Descriptor of module com.apress.moduleC

module com.apress.moduleC {
        exports com.apress.moduleC.packageC1;
}

In the following module graph, module com.apress.moduleB has two packages that are both exported. Module com.apress.moduleC also consists of two packages, but only one is exported according to its module definition. Package com.apress.moduleC.packageC2 isn’t exported and therefore will never be accessible outside the module com.apress.moduleC. Any other module attempting to make use of package com.apress.moduleC.packageC2 will not only fail, it will also not be compiled successfully.

Figure 4-6 shows a new enhanced type of the module graph where we have also inserted the packages that the module contains. The packages com.apress.moduleB.packageB1, com.apress.moduleB.packageB2 and com.apress.moduleC.packageC1 are exported, and the com.apress.moduleC.packageC2 package is not exported.

Figure 4-6. Module graph showing which packages are exported and which aren’t

Module com.apress.moduleA can successfully access types in both packages packageB1 and packagesB2 for the following reasons:

• It reads module com.apress.moduleB.

• The packages packageB1 and packageB2 are being exported by module com.apress.moduleB.

However, if a new package were added into module com.apress.moduleB, it would not be accessible to module com.apress.moduleA unless it were declared as exported in the module description of module com.apress.moduleB. Module com.apress.moduleA can access types from com.apress.moduleC, but only from package packageC1 because this is the only package that is being exported by module com.apress.moduleC. Package packageC2 is not being exported and therefore can’t be accessed by module com.apress.moduleA.

We’ve learned so far how to set up a module declaration file and how to use the requires and exports clauses. Listing 4-10 presents a simple module with both requires and exports clauses.

Listing 4-10. The Module Descriptor of module com.apress.moduleA Using Both requires and exports Clauses

module com.apress.moduleA {
    requires com.apress.moduleB;
    exports com.apress.moduleA.packageP1;
}

In this example, we defined a module called com.apress.moduleA that depends upon another module called com.apress.moduleB and also exports the package called com.apress.moduleA.packageP1.

The opens Clause

Until now we’ve seen how we can achieve strong encapsulation using the exports directive. But what happens if we need to access some types using reflection?

Note

The exports clause just shown doesn’t allow its non-public types to become accessible by using deep reflection.

There are two different situations for using reflection in Java 9:

• Code in the unnamed module (the class path) can access code in any named modules using reflection. This is possible due to a flag called --illegal-access that’s set by default and that was added by the JCP team in order to ease migration. Many frameworks such as Hibernate and JPA need reflective access to code in named modules. These frameworks typically reside on the class path. Chapter 8 discusses the --illegal-access flag in more detail.

• Code in a named module can’t access code in any named modules using reflection.

This is where the new opens clause and the --add-opens command-line option come in play.

In order to solve this problem, a new directive called opens was introduced. Its role is to provide reflective access to the types passed as parameter.

Note

Using opens to export a package that has some internal implementation isn’t recommended. Doing so will expose the internal implementation and break the strong encapsulation rules.

Figure 4-7 illustrates the syntax of the opens clause.

Figure 4-7. The syntax of the opens clause

The opens clause is another clause that can exist in a module descriptor, besides the requires and exports clauses discussed earlier in this chapter. The opens clause is used inside the module declaration to define the packages that are available for deep reflection at runtime for all modules. Therefore, both the public and the private types of the package are accessible using deep reflection by code in other modules.

Note

Packages inside a module are by default available for deep reflection only by code in any unnamed module.

The opens directive can also be qualified by specifying a list of target named modules, as illustrated in Figure 4-8.

Figure 4-8. The syntax of the qualified opens clause

There are some characteristics of the opens clauses you should know. First, it’s important to know that it is possible to use both exports and opens directives for the same package. In this case, the package is exported for access at compile-time and runtime and also available for deep reflection at runtime. As a result, its public types can be accessed at compile-time and at runtime, and both its public and private types can be accessed at runtime using reflection. Second, the opens directive can’t be used inside an open module. Open modules are covered later in this chapter.

Note

The opens directive can’t use wildcards and cannot contain more than one package.

Compile a Single Module

Here’s a very simple example of compiling a single module using JDK 9. Suppose we have a module com.apress.moduleA that has no dependencies. It contains a Main.java file inside its package com.apress.moduleA. The structure of the folder is as follows:

src/com.apress.moduleA/
                 module-info.java
                 com/
                     apress/
                           moduleA/
                                  Main.java

Listing 4-11 shows the content of class Main. It prints a message on the console.

Listing 4-11. The Main class from the module com.apress.moduleA

// Main.java
package com.apress.moduleA;
public class Main {
        public static void main(String[] args) {
                System.out.println(“Here is Java 9!”);
        }
}

Listing 4-12 shows the module-info.java file of module com.apress.moduleA. It doesn’t define any clause.

Listing 4-12. The Module Descriptor for moduleA

// module-info.java
module com.apress.moduleA {

}

First we create the destination directory where the compiler outputs to using the mkdir command:

mkdir –p outputDir

Then we use the Java compiler to compile the Main.java file and the module-info.java file. The compilation will create a .class file for each .java file:

$ javac –d outputDir/com.apress.moduleA src/com.apress.moduleA/module-info.java src/com.apress.moduleA/com/apress/moduleA/Main.java

The javac command gets the files that is has to compile. The -d option specifies the directory where the compiler outputs to. In this case, it will output to the directory outputDir/com.apress.moduleA. The last two parameters represent the path to the files that we want to compile, module-info.java and Main.java.

The corresponding class files are generated during the compilation in the directory passed as parameter to the option -d. The compilation of a single module is done very much the same as in Java 7 or 8 without necessarily needing to use other compiler flags than the ones used in the older versions of Java. Compared to Java 8, the single distinction here is that module-info.java was also compiled.

Run an Application Containing a Single Module

To run the previously compiled classes, we use the Java launcher with the following command:

$ java --module-path outputDir --module com.apress.moduleA/com.apress.moduleA.Main

As a result, the string “Here is Java9!” is printed at the console. We recognize in the previous listing that the java command uses new flags for handling modules. The --module-path option, introduced in Java 9, gets as parameter a directory or a list of directories containing the location of the already compiled files. In our case, these are in the outputDir directory. The module path is used in order for the compiler to be able to locate the modules at runtime.

The differences between the module path and the class path are listed later in this chapter, in the section “The Module Path.”

The second option used by the Java launcher is the command-line option --module. It’s used to specify the main class and the main module by taking a parameter in form of <module_name> / <main_class>. The location of the main class is mandatory information that the java command needs to be aware of.

The Java launcher will load the root module com.apress.moduleA, resolve all its dependencies and transitive dependencies by running the resolution process, and finally run its Main class, which was passed to the option --module. At the end, the message is printed in the console.

Congratulations! You just learned how to successfully compile and run your first module in Java 9.

If we had tried to run the java command without the --module-path option, like this

$ java –m com.apress.moduleA/com.apress.moduleA.Main

the following error message would have been displayed:

Error occurred during initialization of VM
java.lang.module.ResolutionException: Module com.apress.moduleA not found
        at java.lang.module.Resolver.fail(java.base@9-ea/Resolver.java:796)
        at java.lang.module.Resolver.resolveRequires(java.base@9-ea/Configuration.java:370)
        at java.lang.module.Configuration.resolveRequiresAndUses(java.base@9-ea/ModuleDescriptor.java:2081(
        at jdk.internal.module.ModuleBootstrap.boot(java.base@9-ea/ModuleBootstrap.java:263)
        at java.lang.System.initPhase2(java.base@9-ea/System.java:1925)

What does this error mean? Module com.apress.moduleA isn’t found because we didn’t inform the Java launcher about the location of the compiled modules. The directory where the compiled modules are located has to be specified using the --module-path option. The Java launcher can’t find the modules unless we explicitly specify their location.

Compile Multiple Modules

Until now, we’ve compiled and executed a single module. But for the compilation of two or more modules, some extra compiler flags have been introduced in Java 9. In the following example you’ll learn how to compile multiple modules at the same time.

Suppose we have a total of three modules: module com.apress.moduleA, module com.apress.moduleB, and module com.apress.moduleC. The structure of the folders for the three modules is like this:

src/com.apress.moduleA/
                             module-info.java
                             com/
                                   apress/
                                          moduleA/
                                                      Main.java
    com.apress.moduleB/
                             module-info.java
                             com/        
                                   apress/
                                          moduleB/
                                                      ClassB1.java
                                                      ClassB2.java
    com.apress.moduleC/
                             module-info.java
                             com/
                                   apress/
                                          moduleC/
                                                      ClassC1.java
                                                      ClassC2.java

Further, suppose that for each module the module-info.java doesn’t contain any clause. Listing 4-13 shows the javac command used to compile only the module com.apress.moduleA.

Listing 4-13. Compile module com.apress.moduleA Using the --module-source-path Flag

$ javac –d outputDir --module-source-path src src/com.apress.moduleA/module-info.java src/com.apress.moduleA/com/apress/moduleA/Main.java

The compilation of multiple modules at the same time is done using the new --module-source-path command-line option introduced in Java 9. It’s used to tell javac about the sources in the directory. In this case we point the --module-source-path to the src directory and output our compiled modules into the outputDir directory.

The compilation generates the following classes inside the outputDir directory:

outputDir/com.apress.moduleA/
                                    com/
                                        apress/
                                               moduleA/
                                                       Main.class
                                    module-info.class

The other two modules, com.apress.moduleB and com.apress.moduleC, haven’t been generated because we didn’t specify them in the javac command. We compiled only the module com.apress.moduleA.

Let’s specify that module com.apress.moduleA has a dependency on module com.apress.moduleB and on com.apress.moduleC. Listing 4-14 shows the module-info.java file of module com.apress.moduleA where we define the dependency using the requires clause.

Listing 4-14. The Module Descriptor of module com.apress.moduleA

// module-info.java
module com.apress.moduleA {
        requires com.apress.moduleB;
        requires com.apress.moduleC;
}

If we run the javac command from Listing 4-13, we get the following structure of the outputDir directory:

outputDir/com.apress.moduleA/
                            com/
                                        apress/
                                                   moduleA/
                                                        Main.class
                                    module-info.class
          com.apress.moduleB/
                                    module-info.class
          com.apress.moduleC/
                                    module-info.class

In the javac command, we specified to compile only the Main.java and the module-info.java files from module com.apress.moduleA. But due to the fact that module com.apress.moduleA requires both modules com.apress.moduleB and com.apress.moduleC, the module descriptors from com.apress.moduleB and com.apress.moduleC have also been compiled to class files.

We compile all the classes that end with .java using the following command:

$ javac -d outputDir --module-source-path src $(find . -name "*.java")

The --module-source-path option specifies the location of non-compiled files. We search for all the files that end with the extension .java, including the module descriptor, of course. All the files ending with .java from all the modules have been compiled to .class files. The structure of outputDir is shown in the following code. Both Java classes and the module-info.java files have been compiled to .class files:

outputDir/com.apress.moduleA/
                                    com/
                                          apress/
                                                 moduleA/
                                                             Main.class
                                    module-info.class
            com.apress.moduleB/
                                    com/
                                          apress/
                                                   moduleB/
                                                             ClassB1.class
                                                             ClassB2.class
                                    module-info.class
            com.apress.moduleC/
                                    com/
                                         apress/
                                                moduleC/
                                                                ClassC1.class
                                                                ClassC2.class
                                     module-info.class

Run an Application Containing Multiple Modules

To run the previously compiled classes, we use the Java launcher with the following command:

$ java --module-path outputDir --module com.apress.moduleA/com.apress.moduleA.Main

This is the same java command used in the previous example, when we ran an application consisting of only one module. But now we have three modules inside the application that we want to run, so why do we specify a single module?

The --module option needs to get only the name of the root module. It doesn’t need to get all the modules. By getting the root module, it starts a resolution process and finds the other modules according to the information present in the module descriptor.

The resolution process starts with module com.apress.moduleA and then finds the modules com.apress.moduleB and com.apress.moduleC. After it finishes, the Main class of the root module is executed.

In this section, we’ve learned how to compile and run multiple modules using Java 9. Now let’s see an example where compilation fails due to the broken accessibility rules. Here, we import ClassB1 and ClassB2 into Main.java. Listing 4-15 shows the Main class of com.apress.moduleA.

Listing 4-15. The Main Class

// Main.java
package com.apress.moduleA;
import com.apress.moduleB.ClassB1;
import com.apress.moduleC.ClassC1;
public class Main {
        public static void main(String[] args) {
                System.out.println("Here is Java 9!");
        }
}

We know from the previous example that module com.apress.moduleA requires modules com.apress.moduleB and com.apress.moduleC. By compiling all the Java files

$ javac -d outputDir --module-source-path src $(find . -name "*.java")

the following error is thrown:

Main.java:3: error: ClassB1 is not visible because package com.apress.moduleB is not visible
import com.apress.moduleB.ClassB1;

Main.java:4: error: ClassC1 is not visible because package com.apress.moduleC is not visible
import com.apress.moduleC.ClassC1;

2 errors

The compilation fails as a result of strong encapsulation. The classes ClassB1 and ClassC1 can’t be imported into the Main class. Even if module com.apress.moduleA requires the other two modules, it can’t access types from them because those types aren’t exported by these modules. The public access modifier used to define the classes ClassB1 and ClassC1 isn’t able to enforce accessibility any more in Java 9.

In order to make the classes ClassB1 and ClassC1 available to the Main class, we must explicitly specify the following two things:

• In the module descriptor of module com.apress.moduleB, we specify that the package containing the ClassB1 is exported.

• In the module descriptor of module com.apress.moduleC, we specify that the packages containing the ClassC1 is exported.

By doing this, all classes from the exported package from module com.apress.moduleB and from the exported package from module com.apress.moduleC will be accessible in this way to module com.apress.moduleA, and the compilation will succeed without any error.

Private vs. Public Methods

We extend our example to be able to call a method from a different module. A private method won’t be able to be accessed from other module even if the module is read and the corresponding types are exported.

Listing 4-16 shows the class ClassB1 from package com.apress.moduleB which has a new private static method.

Listing 4-16. Class ClassB1 Contains a Private Method

// ClassB1.java
package com.apress.moduleB;
public class ClassB1 {
        private static String getInfoForClassB1() {
                return "ClassB1 from ModuleB";
        }
}

Listing 4-17 shows how the Main class from module com.apress.moduleA calls the static method from ClassB1.

Listing 4-17. Class Main

// Main.java
package com.apress.moduleA;
import com.apress.moduleB.ClassB1;
import com.apress.moduleC.ClassC1;

public class Main {
        public static void main(String[] args) {
                System.out.println(“Here is Java 9!”);
                System.out.println(ClassB1.getInfoForClassB1());
        }
}

The compilation fails with the following error message:

Main.java:10: error: getInfoForClassB1() has private access in ClassB1

By setting the getInfoForClassB1() method to public in ClassB1.java, the compilation will succeed. Running the application

$ java --module-path outputDir –m com.apress.moduleA/com.apress.moduleA.Main

results in the following being printed:

Here is Java 9!
ClassB1 from ModuleB

In this example, we showed that having an access identifier as private makes the type inaccessible, as in the previous versions of Java.

We’ve learned how to compile and run modular applications in Java 9. In the next section we discover the new modular JAR files introduced in Jigsaw.

Structure of a Modular JAR

The structure of a modular JAR file is similar to the one of a normal JAR file, except a module-info.class file is present. Here’s an example of a modular JAR file:

META-INF/
META-INF/MANIFEST.MF
module-info.class
com/apress/moduleA/Main.class
com/apress/moduleB/ClassB1.class
com/apress/moduleB/ClassB2.class
...

There is also a MANIFEST.MF file located in the META-INF directory. The module-info.class file is located in the root directory. All our compiled .class files are present in the modular JAR.

Up to now, we’ve learned about modular JAR files and about their structure. But how can we create one? We’ll find the answer in the next section when we talk about packaging and present the jar tool used to create modular JAR files.

Package as a Modular JAR Using the jar Tool

The jar tool has been enhanced to support the newly introduced concept of modules. Table 4-2 displays the new options that have been added in JDK 9 to the jar tool, according to the official JDK 9 API specification.

The options presented in Table 4-2 can be used when we create modular JARs or when we update a non-modular JAR. The jar --help command has also been enhanced in JDK 9. It contains more detailed descriptions about each command.

Using the jar tool, we create a new modular JAR file called moduleA.jar in the lib directory by packaging everything that exists in the modules directory:

$ jar --create --file lib/moduleA.jar --main-class com.apress.moduleA.Main –c modules

• The --create option creates the modular JAR file.

• The --file option indicates the name of the modular JAR that will be created. It also specifies the location where it will be created (in our case, the lib directory).

• The --main-class option sets the Main class while the module is being packaged.

• The -c option specifies the location where the compiled modules are (in our case, they’re in the modules directory, which contains the compiled class files for the module com.apress.moduleA).

$ jar --describe-module

$ jar -d

Application Module Path

The application module path is used by the Java launcher to mark the directory that incorporates the application modules. It’s expressed using the new command-line option --module-path or its short-form, -p.

Figure 4-9 shows the command-line syntax of the module path flag:

Figure 4-9. Syntax of the --module-path command-line option

The module path flag gets a list of directories as parameters separated by a colon. There can be an unlimited number of directories listed, but for each of them there has to be a colon separating them.

The modules contained in the directories that form the module path can be:

• Packaged as modular JAR files.

• Exploded as standalone class files.

The Java launcher can load exactly the module that it needs from the module path because it knows this information due to the configurations that exist in the module declaration.

At runtime, using the module path is possible to specify the different types of modules that we’ve built together with the project. A module can be only in one place. If it’s in more than one place, the first occurrence will be retained, and the other occurrences won’t be taken into consideration.

Besides the application module path, there are two more types of module path: the compilation module path and the upgrade module path.

Compilation Module Path

The compilation module path, which contains definitions of modules in source form and is used together with javac, is specified using the new Java option --module-source-path on the command-line. It’s used during the compilation to inform the Java compiler of the location of the modules that must be searched.

Figure 4-10 illustrates the syntax of the command-line --module-source-path option:

Figure 4-10. Syntax of the --module-source-path command-line option

The --module-source-path flag specifies a list of Java source files to be compiled. They can be listed one after another separated by a blank space.

Generally, we can think of the --module-source-path command-line option as the module correspondent of the --sourcepath option.

Upgrade Module Path

The upgrade module path is specified using the Java compiler option --upgrade-module-path on the command-line. According to OpenJDK, “it contains compiled definitions of modules intended to be used in place of upgradeable modules built-in to the environment.” The upgrade module path isn’t covered in this book.

In this section we’ll talk about the module resolution process.

Root Module

The root module is the module that the resolution process starts with. It’s specified in the java command using the --module option, as we’ve seen in the examples when we ran the modular application.

First, the root module is added to the group of resolved modules. Second, the module system scans the module descriptor of this module and adds all the dependencies (modules) to the group of resolved modules. The process continues, and the Java Platform Module System tries to find the dependencies on the other modules. When all the modules searched are found and the module java.base is reached, the process stops. After the resolving process is finished, we have all the necessary modules for running our software application.

In some cases, a module is on the module path but wasn’t found during the resolution process so that it can be added to the module graph. Here, we have to manually add the module to the module graph. This can be done using the --add-modules command-line option. We discuss this option in more detail in Chapter 8.

It’s important to know that the module resolution process detects any modules that could eventually be missing. If a mandatory module is missing, the module resolution process stops, and an exception is thrown.

Another important topic in Jigsaw is accessibility, covered in the next section.

Readability vs. Implied Readability

Readability is the relation between two modules that refers to the fact that a module that reads another module can access the types from its exported packages. In this case, we say that a module reads another module.

We touched the subject of readability in previous examples when we described the requires and exports directives inside of a module declaration. To recap the concept of readability, you can go back to the “Module Declaration” section, subsection “The requires Clause.” What we haven’t covered yet is the new concept of implied readability.

Implied Readability

Implied readability refers to the situation when

• The first module reads the second module.

• The second module reads the third module.

• The first module logically reads the third module as a result of the two conditions just met.

Suppose we have a module B that uses a type from a module C (B reads C). If another module A reads module B and uses types from module C, then without implied readability, module A should explicit specify that it also requires module C. By using implied readability, it’s not necessary to specify this in module A. It’s enough to specify in the module-info.java of module B that it requires transitive the types from module C. As a result, every module that reads types from module B will automatically be able to access the types from module C.

Figure 4-11 illustrates the corresponding module graph of the three modules and shows the readability relations between them.

Figure 4-11. Module graph showing implied readability

Listing 4-18 illustrates the module descriptor of module A, which requires module B.

Listing 4-18. Module Descriptor of Module A

// module-info.java
module A {
        requires B;
}

Listing 4-19 shows the module descriptor of module B, which requires transitive module C.

Listing 4-19. Module Descriptor of Module B

// module-info.java
module B {
        requires transitive C;
}

It’s not necessary for module A to require module C, because module B requires transitive module C. As a result, module A can automatically access types from module C.

Note

Implied readability is achieved by adding the statement requires transitive in the module declaration, followed by the name of the module that the current module depends upon.

Figure 4-12 illustrates the syntax of the requires transitive clause. It takes a module name as parameter.

Figure 4-12. Syntax of the requires transitive clause

Let’s look at an example of implied readability with platform modules in order to understand this better. Listing 4-20 shows the module declaration of the platform module java.desktop that defines requires transitive clauses in order to take advantage of implied readability.

Listing 4-20. The Module Descriptor of module java.desktop

// module-info.java
module java.desktop {
        requires transitive java.datatransfer;
        requires transitive java.xml;
        requires java.prefs;

        exports java.applet;
        ...
}

Listing 4-21 is an excerpt of the class DocumentHandler located in module java.desktop in the package com.sun.beans.decoder:

Listing 4-21. Class DocumentHandler from Module java.desktop

// jdk/src/java.desktop/share/classes/DocumentHandler.java

package com.sun.beans.decoder;

import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParserFactory;
...

public final class DocumentHandler extends DefaultHandler {

...

  public void parse(final InputSource input) {
        if ((this.acc == null) && (null != System.getSecurityManager())) {
            throw new SecurityException("AccessControlContext is not set");
        }
        AccessControlContext stack = AccessController.getContext();
        SharedSecrets.getJavaSecurityAccess().doIntersectionPrivilege(new PrivilegedAction<Void>() {
            public Void run() {
                try {
                    SAXParserFactory.newInstance().newSAXParser().parse(input, DocumentHandler.this);
                }
                catch (ParserConfigurationException exception) {
                    handleException(exception);
                }
                catch (SAXException wrapper) {
                    Exception exception = wrapper.getException();
                    if (exception == null) {
                        exception = wrapper;
                    }
                    handleException(exception);
                }
                catch (IOException exception) {
                    handleException(exception);
                }
                return null;
            }
        }, stack, this.acc);
    }
}

As you can see, the class DocumentHandler from module java.desktop uses SaxParserFactory from the java.xml module. This denotes that module java.desktop uses a type from module java.xml, so a readability relation occurs between module java.desktop and module java.xml.

If we add a dependency to the java.desktop module in our module descriptor and try to use the parse() method from the DocumentHandler, we’re attempting to access types not only from module java.desktop but also from module java.xml. In order to access the method from our own module, it’s mandatory that the module java.xml is required transitive by the module java.desktop. In this way our module can take advantage of implied readability and have access to the types from the module java.xml without explicitly requiring them. Any module that requires module java.desktop automatically requires the modules java.datatransfer and java.xml, because both are present in the module descriptor of module java.desktop. By requiring the module java.desktop, we get access to the exported packages from modules java.desktop, java.datatransfer, and java.xml.

If we omit the transitive keyword and use only the requires directive, we have the situation where our module is able to access types only from the module java.desktop, but not from java.xml.

Suppose we create a simple module called myModule that requires module java.desktop. Listing 4-22 shows the module descriptor of module myModule.

Listing 4-22. Module Descriptor of Module myModule

// module-info.java
module myModule {
        requires java.desktop;
}

Figure 4-13 shows the module graph of the module myModule and expresses the readability together with the implied readability relations between modules.

Figure 4-13. The module graph of myModule

We have the following situation:

• myModule requires java.desktop (readability illustrated with a dashed line in the graph).

• java.desktop module requires transitive module java.datatransfer and module java.xml (implied readability illustrated with a solid line).

Our module myModule gets readability to modules java.datatransfer and java.xml without needing to explicitly require them. As a result, it can use types from these two modules without having to worry about the need to specifically declare the dependencies to them.

Now that we’ve learned what implied readability is, let’s see what a qualified export means.

Qualified Exports

A module can export all its packages or a group of its packages to all the modules. The exports clause has been enhanced to specify that a module can export a group of its packages only to a set of named modules.

Listing 4-23 is an excerpt of the module descriptor from the module java.rmi.

Listing 4-23. Excerpt from Module Descriptor of module java.rmi

// module-info.java
module java.rmi {
    ...
    exports com.sun.rmi.rmid to java.base;
    exports sun.rmi.registry to
        java.management;
    exports sun.rmi.server to
        java.management,
        jdk.jconsole;
    exports sun.rmi.transport to
        java.management,
        jdk.jconsole;
}

Package com.sun.rmi.rmid is exported using a qualified export to module java.base. Therefore it’s accessible only inside the module java.base. The other modules can’t access it. Only the modules specified after the to clause will be able to access the package.

The syntax used for defining qualified exports inside the module-info.java file is shown in Figure 4-14.

Figure 4-14. Qualified exports syntax

Duplicating the names of the modules in a qualified export declaration is prohibited, as shown in Listing 4-24.

Listing 4-24. Qualified Export with a Duplicate Module’s Name

// module-info.java (com.apress.moduleA)
module com.apress.moduleA {

}

// module-info.java (com.apress.moduleB)
module com.apress.moduleB {
        exports com.apress.moduleB to com.apress.moduleA, com.apress.moduleA;
}

A compilation failure will occur in this case:

Error: duplicate export: com.apress.moduleA exports com.apress.moduleB to com.apress.moduleA, com.apress.moduleA

We’ve learned what the qualified exports directives are and how they’re different from standard exports directives. It’s a great advantage to be able to specify only the specific modules that are allowed to access the module’s data. Modules shouldn’t be obligated to expose their packages to all the existing modules.

Qualified exports are a great benefit of strong encapsulation. They’ve been extensively used during the process of modularizing the JDK and are present in a couple of module-info.java files inside the JDK.

We talked about accessibility and discussed the concepts of readability, implied readability, and qualified exports. Next let’s look at the different types of modules introduced in Jigsaw.

Named Modules

The named modules comprise all the modules from the module system except the unnamed module. There are two important things that distinguish an unnamed module from a named one. First, the unnamed module lives on the class path, whereas the named modules live on the module path. Second, the unnamed module doesn’t have a name, whereas each named module has a name. A named module can be a normal module or an automatic module. Named modules are modules declared using a name in the module-info.java module descriptor file. Every module that has a declaration of form module <module_name> in its module-info.java is a named module. This is the single condition that has to be met for a module in order to be classified as a named module. Examples of named modules include all the platform modules, but our own modules can also be included in this category if they respect the unique condition just mentioned. Transforming a JAR file into a named module is possible by merely adding a module-info.class file to it.

Normal Modules

The notion of “normal” modules doesn’t officially exist. We use this term to define a named module that isn’t automatic. The main difference between a normal module and an automatic one is that a normal module has a module descriptor module-info.java, whereas an automatic module doesn’t. Additionally, a normal module is explicitly declared by developers, which declares the module’s dependencies in the module’s module descriptor. The module descriptor of an automatic module isn’t provided by developers. A normal module is declared using the keyword module followed by the name of the module. All the modules we’ve presented until now in this chapter were normal modules. A normal module doesn’t export any of its packages by default. Besides that, its exports clauses must be explicitly specified. The exports clauses export packages at compile-time as well as at runtime. A normal module comprises both basic modules and open modules.

Automatic Modules

An automatic module is a module created after placing a JAR file onto the module path. Comparing an automatic module to a normal one, two important distinctions emerge:

• An automatic module requires by default all the existing modules from the system, which comprise all our own modules, plus all modules from the JDK image, plus all the other automatic modules.

• An automatic module exports all its packages by default.

An automatic module can access types on the class path and is useful for third-party code especially. Automatic modules are used for migrating existing applications to Java 9. Chapter 8 talks about them in more detail.

Basic Modules

We call every named module that isn’t an open module a basic module. However, the term “basic” module doesn’t officially exist in JDK 9. We use it to define a named module that’s neither automatic nor open. A basic module has the same set of characteristics as a normal module, except that it’s not opened for deep reflection.

Open Modules

Inside a module, packages aren’t accessible to code from another module at compile-time, even when using deep reflection. However, many third-party libraries and frameworks use reflection to access the internals of JDK at runtime. As a result, all these frameworks aren’t working in JDK 9 unless reflective access is granted. In JDK 9, reflective access is granted only by code in named modules to code from the class path. It’s not granted by default by code in named modules to code in other named modules. As a result, if the third-party libraries or frameworks lie on the class path, they have reflective access by default in the JDK. If they live on the module path, then they don’t have reflective access in the JDK. But to grant reflective access to all the packages in a module, the module should be declared as open.

An open module is defined by placing the identifier open in front of the keyword module, followed by the name of the module.

Open modules make all the packages inside of the module available for deep reflection. When we say “all the packages”, we mean both the public and private packages. We can also opt between opening an entire module for deep reflection or opening only specific packages. When choosing the latter, we don’t specify an entire module as open but only one or more packages inside the module. The keyword open can be placed near the module name or inside the module descriptor to open specific packages.

Listing 4-25 defines an open module called com.apress.myModule that requires two Spring modules, spring.tx and spring.context.

Listing 4-25. Defining an Open Module

open module com.apress.myModule {
        requires spring.tx;
        requires spring.context;
        exports com.apress.myModule.myPackage;
}

Two important facts must be stressed in regard to the previous example:

• All types from all packages of the module com.apress.myModule are available for deep reflection at runtime.

• At compile-time, only the public and protected types in package com.apress.myModule.myPackage are accessible.

As a result, the Spring framework can make use of the setAccessible() method to access the non-public elements of the com.apress.myModule.myPackage package.

module target {
       exports target;
}

module testReflection {
       requires target;
}

package target;

public class Employee {

    private String employeeName = null;

    public Employee(String employeeName) {
        this.employeeName = employeeName;
    }
}

package testReflection;

import java.lang.reflect.*;
import target.*;

public class Main {

    public static void main(String[] args) {

        Employee employee = new Employee("John");
        try {
            Field employeeField = Employee.class.getDeclaredField("employeeName");
            employeeField.setAccessible(true);
        }
        catch(NoSuchFieldException noSuchFieldException) {
        }
    }
}

javac -d out --module-source-path src $(find . -name "*.java")

$ java --module-path out --module testReflection/testReflection.Main

Exception in thread "main" java.lang.reflect.InaccessibleObjectException: Unable to make field private java.lang.String target.Employee.employeeName accessible: module target does not "opens target" to module testReflection
        at java.base/jdk.internal.reflect.Reflection.throwInaccessibleObjectException(Reflection.java:424)
        at java.base/java.lang.reflect.AccessibleObject.checkCanSetAccessible(AccessibleObject.java:198)
        at java.base/java.lang.reflect.Field.checkCanSetAccessible(Field.java:171)
        at java.base/java.lang.reflect.Field.setAccessible(Field.java:165)
        at testReflection/testReflection.Main.main(Main.java:14)

open module target {
        exports target;
}

The Unnamed Module

An unnamed module, as the term suggests, doesn’t have a name and isn’t declared. It comprises all the JAR files or modular JAR files from the class path. All these JAR files together form the unnamed module. The Java Platform Module System first searches for a specific type on the module path. The module path is searched before the class path. If the type isn’t found on the module path, the search is performed on the class path. If the type is found on the class path, it will be part of the so-called unnamed module. We use the singular term unnamed module instead of the plural unnamed modules because the unnamed module is unique for each class loader. There’s only one, single unnamed module for each class loader.

By default, the unnamed module reads all the named modules from the system. In this way, according to the Java 9 accessibility rules, the unnamed module can access all packages from all the named modules that are being exported. The reverse isn’t true, meaning that the named modules can’t read the unnamed module. If we try to access code on the class path (in the unnamed module) from the module path, the compilation will fail. To succeed, we need to turn the code from the unnamed module into automatic modules. Therefore, we take the JAR file out of the class path and place it on the module path to become an automatic module.

All classes that aren’t contained into the named modules are implicitly contained in the unnamed module. All the packages contained in the unnamed module are open by default to all the modules from the module path, which makes reflective access from the module path on the class path possible.

Observable Modules

The observable modules are not a separate category of modules. This is why we didn’t include them in the classification of modules. The term observable modules is used to denominate all the modules from the system: platform modules, library modules, and our own modules. The modules from the module path are part of the observable modules too.